Guide en

Shroudly: user guide

Shroudly is a free, open-source app for Windows, macOS, Linux and Android that opens websites and apps blocked by internet censorship. It is not a VPN service: nothing goes through a server in between, there is no account and nothing to configure. When you close it, your computer or phone is left exactly as it was.

What Shroudly does

Most internet filters decide what to block by reading the first packet of each connection. That packet carries the name of the site you are opening (the TLS "SNI" or the HTTP "Host"). Shroudly runs a small proxy on your own computer and sends that first packet in a shape the filter cannot read, while the real site receives it unchanged. Many filters also answer name lookups (DNS) with false addresses; Shroudly looks names up over encrypted DNS, so those false answers no longer reach you.

• Your traffic still goes straight to the real site. Nothing passes through anyone else's server, so speed stays the same.
• It finds what works by itself. For each blocked site, Shroudly tries its techniques one after another, uses the one that works and remembers it.
• It fixes what it can by itself. When Shroudly sees what is in the way (Discord or Roblox blocked on your network, a program stuck around it, a site that needs Advanced mode), it turns on what is needed and tells you in one line. You do not have to find anything in the settings.
• Connections that are not blocked are passed through untouched.
• It changes nothing for good. While protection is on, Shroudly points the system proxy at itself; when you stop it, quit, log out, or even if it crashes, the previous setting is put back.
• On Android, every app goes through it. On a phone, Shroudly uses Android's VPN function, but only on the phone itself: browsers, Discord (voice too), Roblox and other games all go through the same engine, with no modes to turn on and no server in between.

What it cannot do

• It does not hide your address. Shroudly is not a VPN. A service that refuses users from your country on its own (because of its own rules or sanctions) still refuses you. Shroudly tells you when a site turns you away itself, so you do not keep trying.
• It cannot reach an address that is blocked outright. If the network blocks the site's IP address itself, rather than its name, only a VPN or a similar tunnel gets through. When a network blocks an app's server addresses themselves, not just recognises its traffic, Shroudly says so in one line: the app's own proxy setting or a VPN is the way then, because Shroudly is not a VPN.
• It cannot bring back a connection that is cut. When only the country's own network works, Shroudly says so; Internet shutdowns: what still works explains what can still help.

Download and install

These links always download the newest version:

System	Intel / AMD (x64)	ARM
Windows 10 or newer	Installer (.exe)	Installer (.exe)
macOS 12 or newer	Intel Mac (.dmg)	Apple Silicon (.dmg)
Debian / Ubuntu / Mint	.deb	AppImage
Arch / Manjaro	.pacman	AppImage
Fedora / openSUSE / RHEL	.rpm	AppImage
Any Linux	AppImage	AppImage
Android 8 or newer	APK	APK

• Windows: run the installer. The first time, if Windows shows "Windows protected your PC", choose More info → Run anyway.
• macOS: open the .dmg and drag Shroudly into Applications. The first time, if macOS will not open it, try once, then go to System Settings → Privacy & Security and choose Open Anyway.
• Debian / Ubuntu: sudo apt install ./Shroudly-*-Linux-amd64.deb
• Arch: sudo pacman -U Shroudly-*-Linux-x64.pacman
• Fedora / RHEL: sudo dnf install ./Shroudly-*-Linux-x86_64.rpm
• openSUSE: sudo zypper install ./Shroudly-*-Linux-x86_64.rpm
• AppImage: chmod +x Shroudly-*.AppImage, then run it.
• Android: see the Android section below.

The first-install steps on Windows and macOS are needed only once. How the releases are signed is described in the code signing policy.

Linux needs glibc 2.28 or newer (Debian 10, Ubuntu 18.04, Fedora 29 or later). No administrator rights are needed, except for Advanced mode.

Updates install themselves. Shroudly checks for a new version when it starts and every half hour, downloads it in the background and installs it the next time it restarts. If a game or Discord call is going through Shroudly, it waits until they are closed.

Android

Shroudly for Android needs Android 8 or newer and no root. One APK of about 1 MB fits every phone and tablet (ARM 64-bit, ARM 32-bit and x86_64). It is not on Google Play yet: this link always gives the newest APK.

1. Open the link on your phone and open the downloaded Shroudly-…-Android.apk.
2. The first time, Android asks you to allow installs from this source (your browser). Allow it once, go back and tap Install.
3. Open Shroudly and tap the big Start protection button.
4. Android asks whether Shroudly may set up a VPN connection. Allow it: this is the only way Android lets an app carry other apps' connections. The VPN stays on the phone; nothing goes through a server.

• Every app goes through Shroudly: browsers, Discord (voice too), Roblox and other games. There are no separate modes; the same automatic techniques and encrypted DNS as on the computer are used, and the plain DNS lookups that apps make themselves are encrypted too.
• Quick Settings tile: add the Shroudly tile to the panel you pull down from the top of the screen, to turn protection on and off without opening the app. Press and hold the tile to open Shroudly. Settings → Quick Settings tile adds it for you (with one tap on Android 13 and later).
• Always-on VPN: in Android's VPN settings, open Shroudly and turn on Always-on VPN; protection then comes back by itself after the phone restarts.
• Settings (the gear at the top of the main screen): Language (the phone's, or any of Shroudly's 31), Accent colour, Apps that skip Shroudly (or the other way round: only the apps you choose go through Shroudly), Quick Settings tile, Start when the phone starts, Count me in the live total and Block ads and trackers. The mode, the technique (automatic by default), the DNS server, QUIC and IPv6, and automation apps are under Advanced, which opens by itself when something there is set.
• Proxy only (Settings → Advanced → Mode): instead of the VPN, Shroudly runs as a proxy on 127.0.0.1:10808 (SOCKS5 and HTTP), so another VPN app can stay connected. Only apps set to use it go through Shroudly: set the Wi-Fi network's proxy to manual with host 127.0.0.1 and port 10808, or use an app's own proxy setting. No VPN permission is asked for.
• Allow automation apps (Settings → Advanced, off by default): Tasker, MacroDroid and similar apps can turn protection on and off, for example on when a game opens and off when it closes. They send a broadcast to the package me.codeshare.shroudly with the action me.codeshare.shroudly.action.START, STOP or TOGGLE. If Android does not let protection start from the background, a notification turns it on with one tap; with Shroudly's battery use set to unrestricted it starts without the tap.
• It tells you when protection stops: if another VPN app or Android turns it off, or an error stops it, a notification says so, so you know your apps are connecting directly.
• Updates: the APK from GitHub tells you once when a new version is out. Tap Download and install: Shroudly downloads it, checks that it is signed with the project's own key, and Android asks you to confirm; the first time, Android asks you to let Shroudly install apps. The certificate's SHA-256 is 23:AC:01:4B:72:26:34:3B:74:C7:C9:C0:A4:FD:6F:1D:ED:97:51:8A:3B:FD:35:BC:DE:65:B6:C1:EC:A8:BD:76. A copy from Google Play is updated by Play.
• What it cannot do on Android: Advanced mode is not available (it would need root). Android allows only one VPN at a time, so Shroudly and another VPN app cannot be on together. With Proxy only (see above), Shroudly leaves the VPN to the other app.
• From 2.6.52: a home-screen widget, and Help through this device in Settings: Shroudly helps people in censored countries while protection is on and the phone charges on Wi-Fi.

Android TV and Google TV

The same APK runs on Android TV and Google TV (Android 8 or newer, from Shroudly 2.6.50) and covers every app on the TV: YouTube, browsers, streaming apps. Put the APK on the TV with a file manager app or "Send files to TV", open it and allow the install; Shroudly is then in the TV's row of apps. Use it with the remote: the arrows move a ring to the round switch and OK turns protection on. Android asks once to allow the VPN: press down, then move to OK.

iPhone, iPad, Mac and Apple TV

Shroudly runs on iPhone and iPad (iOS 16 or newer), the Mac (macOS 13 or newer) and Apple TV (tvOS 17 or newer), and is on its way to the App Store. Until then each release carries Shroudly-…-iOS.ipa for iPhone and iPad: install it with TrollStore or sign it with a paid Apple developer account (a free Apple ID removes its VPN permission).

1. Open Shroudly and tap the big button (on Apple TV, press it with the remote).
2. Allow the VPN configuration the system asks for: the VPN stays on the device, and nothing goes through a server of ours.

• Every app goes through Shroudly, with live stats on the main screen.
• Settings: the technique, the accent colour, QUIC and IPv6 off, Keep protection on, Count me in the live total, Block ads and trackers, your own DNS server and Your own server.
• Widgets on the Home Screen, Lock Screen and Mac desktop, a Control Center switch (iOS 18) and Shortcuts to start and stop.
• About → Help through this device: while the app is open (on a Mac, while it runs), Shroudly helps people in censored countries through Tor's Snowflake.
• Not possible on Apple devices: Advanced mode and sending only some apps through Shroudly.

First start

1. Open Shroudly and press Start protection.
2. Open the site that was blocked. The first time, Shroudly may need a moment to find the technique your network needs; after that, the site opens at once.
3. If Shroudly shows a short line about something it turned on or restarted, that was the fix: nothing else to do.
4. To stop, press Stop protection. Everything is put back as it was.

Shroudly keeps running in the background when you close its window, with an icon in the notification area (the menu bar on macOS). It remembers whether you left protection on, so it comes back the same way after a restart. Start at sign-in starts it with your computer.

The settings

Settings has four tabs: General, Connection, Server and sharing and Application.

• Language: the app follows your system language and can be changed here.
• Bypass strategy (Connection → DPI bypass): Auto (recommended) finds a working technique for each blocked site by itself; leave it so. Choosing a fixed technique turns that off. The last one, Off (encrypted DNS only), leaves every connection as the app sent it and only encrypts DNS.
• DNS anti-poisoning: looks names up over encrypted DNS, so false answers from your network do not reach you. Leave it on.
• DNS server: Automatic uses Shroudly's encrypted DNS. To use a server of your own, choose its kind (DNS over HTTPS, DNS over TLS, DNS over TCP or plain DNS), type its address and press Use: Shroudly asks it once and shows the answer. DNS over TCP helps where a network blocks or forges UDP port 53. If your server stops answering, Shroudly's encrypted DNS answers until it is back. On Android it is under Settings → Advanced. With Only this server ticked, nothing else is ever asked: if your server does not answer, lookups fail until it does (to test a server, or when no one else may see your lookups).
• Routing: All sites (recommended) sends every site through Shroudly, so a blocked site works without you naming it first; sites that are not blocked are passed through untouched. Only listed sites sends only the sites on a list through Shroudly; the list is kept up to date automatically, and you can write your own.
• Discord app (Windows, macOS): the Discord app checks for updates before it opens, and that check ignores the system proxy, so on a filtered network Discord can stay on "Checking for updates". This setting takes it through Shroudly by adding one line to Discord's settings file; turning it off removes the line. Shroudly turns it on by itself when Discord is blocked on your network, and restarts a Discord that is stuck; a Discord that already works is left alone.
• Games and apps (Roblox) (Windows, macOS): some programs ignore the system proxy but follow the HTTPS_PROXY setting, Roblox, Roblox Studio and their installers among them. This setting sends them through Shroudly. Shroudly turns it on by itself when Roblox is blocked on your network, and starts the Roblox player or installer again through itself if one was opened around it. Roblox Studio is never closed by Shroudly, because it may hold unsaved work: if Shroudly asks, save your work, close Studio and open it again.
• While Games and apps (Roblox) is on, Roblox's links (the buttons on the website that start a game or Roblox Studio, also through launchers such as Bloxstrap) open their program through Shroudly, so Roblox Studio opened from the website goes through it too; on Windows they are put back as they were when the mode is turned off or Shroudly quits or is uninstalled. Programs that never read the system proxy, such as bots and command-line tools (Node.js ones included), go through Shroudly in this mode too: restart the ones that were already open. On a network that forges DNS answers, Shroudly turns this mode on by itself.
• On Windows, the setting that Games and apps mode makes for programs lasts only for the current Windows session: it is gone after you sign out or restart, so nothing stays behind on a shared computer (an internet cafe, a classroom) or in a disk image.
• Advanced mode (Windows x64, Linux): for networks that follow whole connections, not just how they start. It works on the packets themselves, so it also reaches programs that ignore every proxy setting. Shroudly turns it on by itself when a site needs it and tells you why first; allow it when your computer asks for administrator permission. It undoes everything when it is turned off or you quit.
• Advanced mode leaves your local network alone (the router, printers, other computers nearby). Shroudly does not turn it on by itself while a game's anti-cheat (Vanguard, Easy Anti-Cheat, BattlEye, FACEIT and similar) is running; you can still turn it on yourself. An anti-cheat counts only while its game is being played: its service that keeps running in the background with no game open (Riot Vanguard's, for example) does not keep Shroudly from turning it on.
• A switch you turn off yourself stays off for two weeks; after that, Shroudly may turn it on again if the same problem comes back.
• Test a site: enter a site's address; Shroudly tries every technique on it and tells you what blocks it, which technique works, or that the site refuses you itself.
• Install updates automatically, Show notifications, Count me in the live total (an anonymous count of running copies; see Privacy), Minimize to tray and Show icon in the notification area: when the icon is hidden, start Shroudly again to open its window.
• Block ads and trackers (off by default): names on a public ad and tracker list (StevenBlack/hosts) get no answer, in every app that goes through Shroudly. The list is downloaded through Shroudly and refreshed weekly. If a site breaks, add it to Sites never to block. The number of blocked lookups is shown with the stats; nothing about them is logged or sent.
• Your own server (Server and sharing; on Android, Settings → Advanced): every site goes through a server you name, given as a socks5://, http:// or Shadowsocks ss:// link. Shroudly opens a site through it before using it and says why if it does not work; the main window says so if it stops working. In a shutdown, a server inside the country that still reaches the world is a way out. The server sees which sites you open: use only one you trust. DNS lookups go through it too, so your provider sees none of them, and the main window shows the address sites see.
• Share my connection (Server and sharing, computer; off until you turn it on): people you give its link to use your internet through Shroudly, from Your own server or any Shadowsocks app, on the same network at once, over the internet where your router opens a way in. They can reach only sites, never your computer or home network; what they open goes out from your connection, so give the link only to people you trust. New link ends the old link at once.
• Share Shroudly (Android, About; the APK from GitHub): sends the app itself to another phone through Bluetooth, a nearby-share app or a messenger, for when its download page cannot be reached.
• Help people in censored countries (Server and sharing): While this is on, people in countries that censor the internet use a little of this computer's connection to get past the blocks. It is safe for you: they cannot reach this computer or your network, what they open stays encrypted, and the sites they open never see your address. Nothing is recorded, and your connection is used only while someone is being helped. How it works: they come through the Tor network's Snowflake, so what they open leaves from Tor's servers, not from yours.
• Help people in censored countries (Android, iPhone, iPad: About): People in countries that censor the internet can use a little of this phone's connection to get past the blocks. On a phone, a free app made for it does this, and you turn it on and off there: Psiphon's Conduit, or Orbot's Kindness Mode. It is safe for you: they cannot reach your phone or your network, and the sites they open never see your address.
• Quit Shroudly: stops protection and puts every setting back.
• On Android, in Settings: Count me in the live total (see Privacy) and Block ads and trackers (not in the Google Play copy); the rest is described in the Android section above. The app follows the phone's language (on Android 13 and later you can also choose a language for Shroudly alone in the system settings).

When something does not open

Go through these in order; most problems end at one of them.

1. Update. Compare the version on the About page with the latest release.
2. Use one tool at a time. Other bypass tools and VPNs (GoodbyeDPI, zapret, SplitWire, WARP, VPN apps) change the same connections or the system proxy. Shroudly writes in Logs when it sees one. Close the others, then press Start protection again.
3. Leave protection on. Each stop and start interrupts the apps that are connected.
4. Let Shroudly finish. It turns on what is needed by itself, for Discord, Roblox and Roblox Studio too, and says so in one line. If your computer asks for permission for Advanced mode, allow it. If Shroudly asks you to reopen Roblox Studio, save your work first.
5. A program ignores every proxy setting: turn on Advanced mode (Windows x64, Linux). With DNS anti-poisoning on, Advanced mode also answers that program's DNS with encrypted DNS, so names blocked in DNS open too. Since 2.6.16 Shroudly notices by itself when your network stops such a program (a Discord bot, for example) and turns Advanced mode on for it, naming the program in one line.
6. One browser opens the site and another does not: that browser goes around Shroudly, usually because of a proxy or VPN setting of its own or an extension. Shroudly names the browser in one line; turn that setting or extension off, or use another browser. If Firefox is set not to use the system proxy, Shroudly sets it back once you close Firefox.
7. Still nothing: use Test a site. Its answer says what the problem is.

On Android:

• Make sure no other VPN app is on. Android allows one VPN at a time, and turning another one on stops Shroudly. To keep another VPN app on, choose Proxy only in Settings → Mode.
• If protection stopped, a notification says why. Open Shroudly and tap Start protection. With Always-on VPN turned on, it comes back by itself after a restart. If the phone ended Shroudly (while the screen was locked, for example), it comes back by itself as soon as a network is there; it stays off only when you turned it off.
• Some phones close apps in the background to save battery. If protection keeps stopping, let Shroudly run in the background without battery restrictions (the setting's name differs between phones).
• An app that was already connected before you started protection may need to be closed and opened again.

What the messages mean

Message	Meaning
blocked here, opened with …	The site is blocked on your network and Shroudly found the technique that opens it. Nothing to do.
… the browser refused the certificate the server sent after …	Some protection services in front of sites (DDoS-Guard, for one) misread a technique and answer with a certificate that is not the site's, so the browser shows a certificate error. Shroudly has already moved that site to another technique: reload the page once.
Discord is blocked on this network … / Roblox is blocked on this network …	Shroudly turned on what that app needs by itself. Nothing to do.
Roblox was not getting through …	Shroudly restarted Roblox through itself. Join your game again.
Roblox Studio was opened before Shroudly could take it through …	Save your work, close Roblox Studio and open it again.
… needs Advanced mode on this network …	Allow it when your computer asks for permission.
would not open with any method	Every technique was refused. Advanced mode usually helps on networks that filter this deeply.
connects, then the network cuts it	The network lets the connection start and then stops it. Advanced mode may help. If the site's address itself is blocked, only a VPN gets through.
… servers do not answer on this network at all	The network blocks that service's servers by their address (Roblox's, on some networks). No technique on your computer gets past that; only a VPN does.
does not answer, while the rest of the site works through Shroudly	One address of a site that otherwise works (an API, a tracker) does not answer. Not a block; nothing to do.
the server refused the connection itself	The site, not the network, turned the connection down. Not a block.
Also running: …	Another bypass tool or VPN is running at the same time. Close one of them.
Another program changed the system proxy	A VPN or another tool took over the system proxy. Close it, or press the button that sets Shroudly again.
Encrypted DNS is blocked on this network	Shroudly keeps trying other routes on its own; until one gets through, some sites may be slow.
Your DNS server … does not answer …	The DNS server you chose in Settings does not answer; Shroudly's encrypted DNS answers meanwhile. Check its address, or set DNS server back to Automatic.
… where nothing is running	A proxy tool that is no longer running (ByeDPI, an old VPN) left a setting pointing at it. Shroudly fixes what it can by itself (it moves Discord Drover's files aside and restarts Discord); for another program, remove the proxy from its settings or start that tool again. If Shroudly offers to clear Windows' WinHTTP proxy, allow it.
… is not going through Shroudly: a proxy or VPN setting of its own, or an extension, is in the way …	That browser goes around Shroudly. Turn off its own proxy or VPN setting, or the extension, or use another browser.
Firefox is set not to use the system proxy, so it does not go through Shroudly …	Close Firefox; Shroudly sets it back to use the system proxy. A proxy you entered yourself is never changed.
Protection was switched off by Android, usually because another VPN app was turned on (Android)	Turn the other VPN app off, then open Shroudly and tap Start protection.
Protection stopped because of an error, so your apps are connecting directly … (Android)	Open Shroudly and tap Start protection again. Until then your apps connect directly.
Leftover proxy in Wi-Fi settings (Android)	Your Wi-Fi network's proxy points at an app that is no longer running. In Wi-Fi settings, open the network and set Proxy to None.

Privacy

Shroudly does not collect personal data and has no account. The only things it contacts are:

• The live count, only if Count me in the live total is on and only while protection is on: a random number that changes every time protection starts (in Settings, on a computer and on Android). No address or other detail is stored.
• GitHub, for updates and for the list of blocked sites. With Block ads and trackers on, also the ad and tracker list, once a week.
• Encrypted DNS resolvers (such as Cloudflare, Google and Quad9) to look names up, while DNS anti-poisoning is on. Or the server you chose under DNS server. Your system's own DNS is asked only about a name these do not know (an intranet name, for example). It is also asked about a site whose addresses from encrypted DNS get nowhere at all, since its cache inside your country may get through; never with Only this server.
• Discord's update servers, only with Discord app on, asking exactly what Discord itself would ask.
• The site itself, once, when you use Test a site or when a site keeps being cut off: one ordinary request for its front page, to see whether the site turns you away itself.
• Discord or Roblox, only while protection is on and only if that app is installed, at most every six hours: a name lookup and a connection to their server, the same ones the app itself makes, to learn whether your network blocks them. Nothing about you is sent.
• Your own server, if you set one: every site goes through that server, so it sees which sites you open (what you read on them stays encrypted).
• Your router, only while Share my connection is on: asked (UPnP) to forward one port to your computer, and to stop when sharing stops. Shroudly keeps no record of the people who connect or of what they open, only how many are connected now.

Which technique opened which blocked site is remembered on your computer only, for a limited time, and never sent anywhere. The full description, with links to each service's privacy policy, is in the README.

The Android app collects nothing either. It is counted in the same live count in exactly the same way (only while protection is on, through the protected connection; turn it off under Settings → Count me in the live total), and otherwise contacts only the sites and apps you use, the encrypted DNS resolvers and, at most every six hours, GitHub, to see whether a newer version is out (in the version installed from the APK; it never downloads or installs anything by itself). Nothing of it is backed up or copied to another device, because its data includes which blocked sites were opened. With Block ads and trackers on, it also downloads the ad and tracker list from GitHub once a week.

The App Store app (iPhone, iPad, Mac, Apple TV) collects nothing either. It is counted in the same way when Count me in the live total is on, downloads the ad list once a week only with Block ads and trackers on, and contacts Tor's Snowflake only with Help through this device on. The full policy: codeshare.me/projects/shroudly/privacy.

Reporting a problem

1. Make sure you have the newest version and that no other bypass tool or VPN is running.
2. Make the problem happen, then open Logs and press Copy logs (it is also in the menu of the icon in the notification area): your version, your system and the newest part of the log go to the clipboard, short enough for one message. Save logs saves the whole log as a text file in your Downloads folder, to attach to an issue. On Android, open About and tap Share logs. Nothing is sent anywhere by itself.
3. Open an issue at https://github.com/umutxyp/Shroudly/issues/new. Write which site or program fails, your operating system and your internet provider, and paste the log. The log contains the names of the sites you opened; remove any you do not want to share.

Security problems (anything that could harm users) should not be reported in public. Report them privately at https://github.com/umutxyp/Shroudly/security/advisories/new.

Safety and official sources

Shroudly is published only on this project's Releases page and at https://shroudly.codeshare.me. Every release is built from the public source code by GitHub Actions, and every package is installed and started on its own system before it is published. Never download Shroudly from anywhere else. Nobody from the project will ever ask you for a password, a token, or to run a file they send you.

The Android APK is always signed with the same project key; its fingerprint is in the Android section above, and the code signing policy describes how releases are signed.

About

Shroudly is made by Codeshare (Codeshare Technology Ltd), which builds software for online communities and keeps the core of it free. It is developed by Umut Bayraktar. The source is under the MIT license.

Its engine, shroudly-core, is written from scratch in C. Its techniques draw on the public research behind GoodbyeDPI and zapret, reimplemented independently, and it recognises censors' block pages from OONI's open data. The project page is at https://codeshare.me/projects/shroudly.

Shroudly — Unseen. Unstoppable.