Shadowrocket User Manual
For your first connection, follow the quick-start steps in the setup guide. This manual is a reference for the full workflow: each chapter explains what to do, how to confirm it worked, and where to resume if something goes wrong. Installation instructions cover all platforms; subsequent app steps use iPhone and iPad as examples.
- 01–03 · Get started
- 04–06 · Routing & testing
- 07–08 · Settings & maintenance
Get and install Shadowrocket for your device
Check your device and download source before dealing with system prompts. Get the iPhone and iPad app from the App Store for a one-time $2.99 purchase in the US storefront; check the App Store listing for system requirements. The Mac versions (Apple silicon and Intel), Windows, Android, and Linux versions are free. Get the appropriate installer from the platform cards on our all-platform downloads page; files are served from /dl/shadowrocket/ on this site. A one-time app purchase is not a subscription to a server service. We do not provide, sell, or recommend servers or subscriptions; Chapter 3 covers importing server details or a subscription you already have.
Verify the listing and purchase account in the App Store
Open the App Store listing and check three details: the developer is Shadow Launch Technology Limited, the app ID in the product URL is 932747118, and the app icon matches the official icon in this site's header. The name or search-result thumbnail alone is not enough; another listing with the same name may appear first. Verify the listing before purchasing. The final price and currency are shown at checkout in your account's storefront.
Purchases can be used on supported iPhones and iPads signed in to the same purchasing account. If a new device shows a purchase button, first check that its App Store account is the one used for the original purchase; the name shown in system settings is not enough to confirm this. If you can't find the app, see storefront and account region details to distinguish between a listing unavailable in that storefront, a device that doesn't meet system requirements, and an account that differs from the original purchase account. Each has a different solution; searching again won't fix an account mismatch.
Choose the right installer and handle system prompts
On Mac, open About This Mac. Choose the Apple silicon version if it shows a chip name under “Chip,” or the Intel version if it shows an Intel processor. Both are DMG files. On Windows, check your system type and use the matching 64-bit installer. On Android, confirm that your device supports arm64. On Linux, check your distribution and package format: use the matching DEB or RPM package where applicable, or choose AppImage to run a standalone file. Similar-looking filenames or icons do not guarantee architecture compatibility.
| Platform | Installation steps | If you see a prompt |
|---|---|---|
| Mac | Open the matching DMG, move the app to Applications, then launch it from there. | If you have confirmed the file came from this site and the system only says it cannot verify the developer, go to Privacy & Security and select “Open Anyway” for the app. |
| Windows | Run the installer for your system architecture, then open the app from the Start menu. | If SmartScreen only says the publisher is unknown and you have verified the source and file, select “More info” → “Run anyway.” |
| Android | Open the downloaded file to start installation and confirm that the prompt is for Shadowrocket. | Follow the system prompt to allow the browser or file manager used to open the file to install unknown apps. Turn off this permission when installation is complete. |
| Linux | Open the matching DEB or RPM package with your system's software installer. For AppImage, grant execute permission in the file properties, then run it. | If the system reports an architecture or dependency mismatch, return to the downloads page and check the package format and system environment. Do not force installation past a dependency check. |
Desktop and Android installers are not code-signed, so the system may ask you to confirm their source. Whether an option to proceed is available depends on the OS version and management policy. On Mac, if you keep launching the app from the mounted disk image, the option may stop working after you eject it; first confirm that the app was copied. On Windows, if the installation window doesn’t open, check that the download completed and whether the system explicitly blocked the file. On Android, if you cancel before installation finishes, reopen the original file from your downloads list; there is no need to allow installation for multiple apps.
Installation is complete when you can launch the app through the normal system entry point. This does not yet verify the server or traffic path. If your old device has a configuration but the list is empty on the new one, that does not mean the installer is faulty. Purchase history, the app, and your configuration data are handled separately. Once the app launches, continue to the next chapter for iPhone and iPad system permissions.
First launch and system permissions
Seeing Home means the app has launched; Shadowrocket also needs a VPN configuration before the system can route connections through it. On the first connection attempt, the system may ask to add a VPN configuration. Confirm that the request came from the Shadowrocket you just opened, then allow it if you want to connect. If prompted to unlock or authenticate your device, follow the system instructions. Do not enter your screen passcode in the app's server fields. If the list is empty and the switch asks you to select a server first, complete Chapter 3 and respond to the permission prompt when you connect in Chapter 5.
VPN configuration, rule files, and server details are different
The system VPN configuration determines whether the app can receive traffic through the system's VPN mechanism. Rule files in the app's Config determine how traffic is handled after it reaches the app. Server entries store the address, protocol, and authentication details needed to connect to a remote server. These are separate layers, and each affects a different part of the process. Deleting a server does not remove the system VPN configuration. Removing a VPN entry in system settings does not also clear the rule files in Config. When you see “configuration” in an item name, check what the item actually controls before changing it.
Allowing permission only means the system can create or use that configuration. It does not confirm that the selected server is reachable or that a test request matched the expected rule. If you deny permission, the app can usually still open and imported details may remain in the list, but that attempt cannot enable the corresponding system connection. To try again, return to Home, check the selected server, and initiate a new connection. Before deleting entries, check whether the system displayed the relevant confirmation prompt.
Find the active VPN in system settings
On iPhone or iPad, search for VPN in system settings, or look under General for VPN and device management options. The menu layout varies by system version, so use the path shown on your device. Check which VPN is currently connected, then return to Home and compare it with the app's switch. A VPN indicator in the system status area means a system VPN connection is active; it does not, by itself, confirm that Shadowrocket owns that connection or that a particular request went through a remote server.
If your phone already has a work VPN or another configuration provided by your organization, don't delete it as a troubleshooting step. Note which entry is connected, whether it is managed by your organization, and whether automatic connection is enabled. If you are allowed to switch connections, temporarily disconnect one, test Shadowrocket, then restore the previous work setup. If system settings say the device is managed or changes are restricted, ask your administrator instead of repeatedly removing existing entries or changing device restrictions.
Grant import permissions only when needed
When you use Scan QR Code, the system may ask for camera access so the app can read the code. If you don't want to scan, enter the details manually or use another import method available in the current interface. If the system asks you to confirm a paste, allow it only when you are importing and know the clipboard contains your own link. Denying camera or paste access affects that import method, not VPN permission. Subscription URLs and QR codes may contain access credentials; don't photograph them and send them to other tools for identification.
If you need to recreate a system entry, disconnect first, note the current selection, and back up your local data. In system settings, confirm that the removable entry belongs to Shadowrocket, remove it, then return to the app and try again. Do not remove an organization profile with a similar name. For permission prompts and troubleshooting steps, see troubleshooting VPN configuration prompts. Before continuing, distinguish these three states: the app opens; system permission is still pending or has been granted; server details have not yet been imported or are ready.
Add servers and import subscriptions
Use Add Server for a single server entry and Subscribe to manage a group of entries from a subscription URL. Both options require details you already have. If you received a single import link or QR code, choose an import method based on its actual type. A URL or scannable code is not necessarily a subscription. Before adding it, verify the protocol, server address, port, and authentication details separately. Ask the provider of the details about unclear fields rather than guessing by trying different protocols.
Enter server details in Add Server
- From
Home, open the add menu and selectAdd Server. Choose the protocol that matches your details to display the relevant fields. After changing protocols, review the fields you entered; they are not necessarily converted to equivalent settings. - Enter the server address and port. The address field usually takes a hostname or address, not a full subscription URL, path, or port separator. Enter the port separately as provided. After pasting, check for spaces at either end and for unintended digits, letters, or full-width characters.
- Enter the required authentication and additional protocol parameters. Match any specified transport, path, TLS, or SNI settings to the corresponding fields. Do not copy optional settings from a different server when they were not provided for this one. Finally, give the entry a descriptive name that does not contain credentials.
- After saving, return to
Homeand check that the entry appears underSERVER. Make sure the selected entry is the one you just verified. An entry in the list does not mean the system connection is established. For the first test, check just this one entry to avoid switching repeatedly between similarly named servers.
How common protocols differ in their fields
| Protocol | Check first | Common confusion |
|---|---|---|
| Shadowsocks | Address, port, encryption method, and password. | A correct password does not mean the encryption method is interchangeable. |
| VMess / VLESS | Identify which of the two protocols you have, then check the protocol label, transport, and required TLS parameters. | Both protocols may use a UUID, but the same UUID does not make them interchangeable. |
| Trojan | Address, port, password, and TLS-related parameters. | SNI sets the server name used in the TLS handshake. It is not a label for the entry and may differ from the connection address. |
| HTTP / SOCKS5 | Protocol, address, port, and any required authentication details. | Using the same host does not mean the services use the same port or accept the same protocol. |
If a connection fails, compare each field with the original details. Do not use the display name as the hostname or a subscription password as a server's authentication value. For a TLS entry with a name or certificate error, first check the device's time and confirm that SNI, the destination address, and the server details match. Disabling certificate verification is not a routine fix. For a field-by-field explanation of TLS parameters, see the Trojan parameter guide.
Check the list and selection after a subscription update
After choosing Subscribe, paste the full subscription URL you already have, save it, and wait for the app to load the list. Keep the URL's query string; don't remove characters that look unnecessary. If import fails, identify which stage failed: the URL was entered incorrectly, the request did not get a usable response, or a response arrived but was not recognized as a server list. If your network is working, check whether the subscription changed or expired and whether the response is a sign-in page. Do not paste a full URL containing credentials into an online testing service.
Once the list appears, note the subscription name and selected entry, then use the update action available in the current interface. An update may change names, parameters, or the number of entries. An entry with the same name may not have the same configuration, and the previously selected entry may no longer exist. Select a clearly usable entry before testing further. If the old list still works but an update fails, keep the old details for now. Removing and re-adding the subscription can erase useful clues and may also remove entries that still work.
Global Routing modes and rule order
Global Routing determines how traffic paths are selected. For everyday rule-based routing, choose the configuration mode (Config). To temporarily test the proxy path, choose proxy (Proxy). To compare with a direct path after traffic is handled by the app, choose direct (Direct). Note the original mode before switching and restore it after the comparison. These instructions apply to connections handled by the app and covered by the selected mode; differences caused by system traffic exceptions, local network settings, or other configurations do not necessarily mean the rules failed.
When to use each mode
| Mode | How the path is chosen | When to use it |
|---|---|---|
| Config | Matches rules in the active configuration and applies the action for the matching rule. | Before checking the route for a specific domain, confirm which configuration is active. |
| Proxy | Uses the proxy path instead of choosing DIRECT or PROXY rule by rule from the configuration file. | Use it temporarily to compare proxy availability, then restore the original mode. |
| Direct | Handles applicable traffic directly instead of forwarding it to the selected proxy server. | Use it as a path comparison; it is not an off switch for the connection. |
There are two Config labels to distinguish: one is a mode in Global Routing, and the other is the interface for managing and selecting configuration files. The first means to apply rules; the second determines which file is used. Save an edited copy and confirm that it is selected. Updating a remote configuration may overwrite its contents. To keep local changes, save a separate copy and confirm which file you use for everyday connections.
Read rule snippets from top to bottom
This .conf snippet illustrates rule order; it is not a complete everyday configuration. Compare it with your existing configuration, but do not overwrite your rule file. example.com is used only as an example. Applicable rules are evaluated in order, and usually the first matching rule determines the action. Put specific exceptions before broader matches. Traffic that matches no earlier rule is handled by the final FINAL rule.
[Rule]
DOMAIN,docs.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
The first rule matches only docs.example.com, so that specific host connects directly. Other names under example.com may be routed through the proxy by the next suffix rule. If the suffix rule comes first, it will match the documentation host before the specific exception can take effect. GEOIP uses a geographic database to classify the destination IP; it does not refer to the domain suffix, the user's location, or where content was published. FINAL is the default action; requests already matched by earlier rules do not reach it.
Use DOMAIN for a single full hostname and DOMAIN-SUFFIX for a group of related domains. DOMAIN-KEYWORD matches when a keyword appears in the hostname; short keywords can match unrelated hosts. IP-CIDR and IP-CIDR6 describe IPv4 and IPv6 address ranges, respectively. Whether the app has the destination domain and needs to resolve the destination address affects whether a condition can match. Domain rules and IP address rules are not two spellings for the same information.
Check the action before interpreting the result
PROXY sends matching traffic through the proxy path, DIRECT bypasses the remote proxy, and REJECT blocks the connection. A rejection does not mean the remote server is down, and a direct connection does not guarantee the destination is reachable. A page may request content from multiple hosts. If the main content loads but images or sign-in fail, check the actual failing destination rather than only the main domain in the address bar. Test with a new request: existing connections may keep using their previous path and do not show that a new rule failed to take effect.
Connect and test in stages
Connection testing should answer three questions: Is the system routing traffic through the app? Is the selected path available? Is the destination being handled as expected? Return to Home and confirm that the selected entry under SERVER matches the details you just checked, then review Global Routing. Turn on the connection switch. If the system asks to add a VPN configuration for the first time, follow Chapter 2. Wait for the system status to settle before testing. If the switch turns itself off, note any prompt shown between tapping it and the shutdown. Avoid tapping repeatedly, which can make the first failure difficult to identify.
Check the underlying network before testing the server
Temporarily disconnect and open a site you can normally access directly on the same Wi-Fi or cellular network. Use it as a baseline. If Wi-Fi requires you to confirm connectivity in system settings, do that first. If the direct baseline also fails, resolve the device's network connection before testing servers; switching servers cannot prove that the underlying network is working. Keep the device, network, and destination the same for the comparison, and complete it in one session if possible so a network change is not mistaken for an app setting effect.
Once the underlying network works, use Connectivity Test to check the selected server. One successful test only confirms that probe and its destination worked at that time; it does not mean every app request will work. A timeout may mean the test target is unreachable or the network is unstable. Note the time, server name, and network type, then test once more after a short interval. If only this entry keeps failing, compare its address, port, protocol, and authentication details with the original. If several entries fail, check whether they share a source, host, or network before editing them individually.
Compare three outcomes using the same destination
- With the original
Configmode selected, make a new request and note the actual failing domain or visible error. If the main page loads, check whether the failure is with a resource or a sign-in action. - If the destination is suitable for and permitted to use a proxy path, switch briefly to
Proxywithout changing the server. If the same destination works in this mode but fails inConfig, first check the active configuration and rule order rather than changing the server. - If the destination can be accessed directly, compare it using
Director by turning off the connection switch, and note the difference. Do not use a destination that requires a particular route to judge whether the underlying network works. Restore the original mode afterward and make a new request to verify the path you actually need.
Start from a new page or app session where possible so cached content, a live background connection, or restored browser content is not mistaken for a new successful request. To compare networks, finish the test on the first network before switching to the second, then repeat the baseline checks. Do not change the network, server, and rules at the same time; even if the issue clears, you will not know which change made the difference.
Narrow down the cause by symptom
| Symptom | Check first | Next step |
|---|---|---|
| The connection switch won't stay on | VPN permission, selected server, and other system VPN entries. | First establish the system connection; don't edit rules yet. |
| The switch is on, but tests keep timing out | Underlying network, server port, and protocol settings. | Keep other conditions unchanged and compare with another verified entry. |
| The test passes, but one destination fails | Destination resolution, matching rule action, and the app's error. | Compare modes for the same destination, then decide whether to check rules or the server. |
If the visible error points to DNS, first identify whether the failed lookup is for the server hostname or the destination hostname. A server hostname failure may prevent the remote connection from starting; a destination lookup failure may affect only certain sites or services. An authentication error points to a different issue: return to Chapter 3 and check the parameters instead of changing rules in bulk. If only a particular service reports an account or session error, check the service's own message rather than treating every error as a network problem.
View and interpret traffic in Data
Data shows traffic recorded by the app. It can help determine whether an action generated traffic or which change needs a closer look, but it cannot identify all traffic used by a specific app or replace your carrier bill or server-side subscription usage. Before comparing values, check whether the interface shows a cumulative total, a time period, or a category. If categories are available, compare the same range, direction, and unit. Do not infer dimensions that the interface does not show from the total alone.
Set a short baseline
- Note the start time, network type, selected server, and
Global Routingmode. OpenDataand record the relevant readings. Don't clear all statistics right away; earlier readings may help explain what changes. - Observe for a short period without actively browsing and check whether the values keep increasing. Sync, push notifications, and background activity can all contribute. If the baseline is already growing, you cannot attribute the entire later difference to a page you opened manually.
- Perform one small, repeatable action, such as reopening a simple document page. Wait for the request to finish, then return to
Data. Subtract the start reading from the end reading using the same measurement range, and note the difference for that interval. If the interface has not refreshed, wait and check again. - To compare another mode, first return to a stable state, then repeat a similar action. Caching, connectivity checks, and existing connections can make the two requests different. Use the difference to help narrow down an issue, not as a precise byte-for-byte measurement.
If a page appears to load but the reading does not change, check whether it was served from cache, whether the current connection is included in the statistics, and whether the reading has refreshed. If upload and download are shown separately, a small request may only cause a noticeable change in one direction. A zero reading does not prove the destination used a direct path or that the device is offline. To confirm the route, check Global Routing, the active rules, and the connection records.
Client, system, and server-side measurements differ
The app records traffic it can observe or assign to a category. System cellular usage follows the device's own measurement and may include connections the app did not handle. Server-side subscription usage depends on how the provider measures and refreshes its figures. The three sources may use different starting points, time boundaries, network types, and upload/download directions. Before comparing them, align the time periods and units, check whether upload and download were added together, and confirm whether you are looking at cellular data only. Different totals alone do not prove duplicate billing or missing traffic.
For example, after switching from Wi-Fi to cellular, the cumulative value in Data may keep growing while system cellular statistics cover only the second part of the session. Or, if the same account is in use on another device, the server-side total may be higher than the amount shown on this device. To check a bill, keep the date range, relevant readings, and network type, then ask the appropriate provider. Changing the range shown in the app cannot change how an existing bill was measured.
Ongoing growth, stalled readings, and clearing data
If readings keep increasing when you are not actively using the device, check for downloads, media playback, sync, or background refresh. Pause one at a time and allow enough time to observe the result. Don't disable all background features at once; even if the number drops, you won't know which activity caused it. If growth appears only after switching networks, return to the connection testing chapter and check whether retries or automatic reconnection occurred when the network came back. Traffic changes can suggest what to investigate, but they cannot identify a specific app on their own.
If readings stop changing, first confirm that the system connection is still active, that the page has not returned to an old session, and that your test generated a new request. Before clearing history, save the time points and totals needed for comparison, then use the clearing option in the current interface. Clearing app records does not remove the system VPN configuration or reset carrier or server-side usage. Before sharing troubleshooting details, hide destination domains, unnecessary access-time information, and server details. In most cases, an interval difference and a description of the connection issue are enough.
Common Settings and what they affect
Before opening Settings, make sure a manual connection works on a network you use regularly. Automatic triggers, test parameters, and import preferences should be configured from this reproducible baseline. Note the original value, change one item at a time, and verify the result while keeping a way to restore the previous setting. If an option is not available in the current interface, use what your device actually provides. Do not copy the exact menu path from another device or clear a working configuration just to find a switch.
On Demand controls when to connect, not how traffic is routed
On Demand lets the system initiate a connection when its conditions are met. It has a different role from Global Routing: the former determines whether the system attempts to establish a VPN connection, while the latter determines the path for traffic after it is handled by the app. Enabling On Demand does not switch Direct to Config or make an unavailable server reachable. Before configuring it, decide which network conditions should trigger a connection and which should leave the current state unchanged, then check whether the interface can express those conditions.
After making changes, test both a scenario where you expect a connection and one where you do not. After switching networks, wait for the system's network status to settle before checking VPN status and Home; a brief delay during network handoff does not mean the trigger failed. If the connection returns after you close the app or disconnect manually, check whether the On Demand conditions are met or another system configuration is connecting automatically. To troubleshoot manual connections, you can temporarily disable On Demand. Note the original settings and restore them after the manual path works.
Check the test target to distinguish a connection failure from a probe failure
When using Connectivity Test, keep the test target the same when comparing servers. If the current interface lets you change the target, choose one you are authorized to access that responds reliably, and first confirm that it works on the relevant network. Don't judge a server from a single response time or repeated test values alone; the target, wireless signal, and request type all affect results. When an actual service fails, reproduce the service request itself; a successful probe is not a substitute.
For a timeout, check the target and underlying network first. Increasing the wait time may only delay the failure message; it won't fix an incorrect address, failed name resolution, or mismatched authentication. If the interface offers diagnostic logs, filter them by the time of a single attempt. Compare the first error with later retries rather than treating the last line as the root cause. For example, a DNS error followed by a timeout may be a chain reaction; changing the default action at the end of the rules may not help.
Decide whether to change Settings or Config
To change the route for a domain, check the rule file in Config. To change remote server parameters, edit the corresponding entry under SERVER. To change when the system initiates a connection, check On Demand. For DNS issues, first check the active configuration and system environment; similarly named options in Settings may not control the same thing. For example, if a domain resolves but a rule rejects it, changing DNS will not change the action to direct. Conversely, if a destination has not resolved to a usable address, an expected rule match does not prove the app reached that address.
Before using import options such as Import from Cloud JSON available in the interface, confirm that you have the corresponding backup format, not an ordinary subscription URL. After importing, check the configuration file, selected server, and automatic connection conditions separately. Do not assume another device's setup is a suitable baseline for this one. If asked to overwrite or merge, check what will be affected before confirming. Backup files may contain connection credentials; store them securely rather than sharing them through a public link.
Updates, migration, and rollback
Keep app updates, subscription updates, and rule changes separate. An app update changes the client; a subscription update changes the server list from its current URL; a rule change changes how requests are matched. Before making changes, record a working baseline: configuration name, Global Routing mode, selected server, whether On Demand is enabled, and one verified destination. Make one type of change at a time and complete its checks before moving on. Otherwise, if the connection fails, you will have to investigate three sets of changes at once.
Keep recoverable data before updating
Check for app updates through the App Store on iPhone and iPad. On Mac, Windows, Android, and Linux, get the matching installer again from the all-platform downloads page. On desktop, recheck the package format and architecture even if you're using the same computer. When moving devices, especially confirm the Mac's chip type. Subscription updates do not replace app updates, and rule copies may not change when a subscription is updated. Make sure you have details you can use to restore your setup, not just a screenshot of a server list.
Keep a readable local copy of your rules, distinguishing the version you use every day from one you are testing. Store subscription access details you already have in a protected location; do not put server passwords in ordinary maintenance notes. A backup can preserve an old state, but it cannot restore credentials that the provider has disabled. After an update, start with a small check: confirm the app launches, the selected server is still usable, and the original test destination gets the expected rule action. Once verified, restore automatic connection or proceed with the next maintenance task.
Handle installation, recovery, and permissions separately when changing devices
On a new iPhone or iPad, use the original purchasing account to find the app. See how to redownload a purchased app. Restoring the app does not restore connection details or transfer the old device's system VPN configuration. Next, restore a configuration or subscription from details you saved, check the selected entry, and respond to the system permission prompt on the new device. If you still have the old device, keep its working details until the new device passes a real access test.
When moving from one device to another operating system, get Shadowrocket for that system first, then check which import methods the current interface supports. Do not assume system permissions, connection triggers, or every in-app preference transfer with a file. For testing, connect both devices to the same network where testing is allowed and start with manual connections using verified entries. Once the new device works, remove sensitive connection details from devices you no longer use or handle them according to your organization's requirements.
Roll back the most recent change when a problem appears
If a problem starts after editing rules, switch back to the last verified configuration, keep the server unchanged, and test the same destination again. If it starts after a subscription update, check whether the previously selected entry was replaced or removed before overwriting your local configuration. If it starts after changing On Demand, pause the trigger and retest with a manual connection. Do not combine switching back to an old configuration with resetting all system VPN entries. The first checks a file change; the second rebuilds permissions and adds another variable.
If you cannot restore the previous state, record the time, network type, system connection status, current mode, error message, and most recent change. For related answers, see 10 common questions for beginners. For a connection issue you can reproduce, work through the checks in the connection testing chapter. Once the connection works again, use the working settings as your new baseline. Make sure a temporary Proxy mode or disabled automatic trigger is not left in place without your knowledge.
Maintenance FAQ
What if my previously selected server disappears after a subscription update?
Check the updated list for the entry's label, protocol, and recognizable address; do not guess based on its position. Treat an entry with the same name but different parameters as a new configuration and test it again. If the original entry has been removed, select another entry you already have and have verified. The app cannot restore an entry that its provider has disabled.
Will reinstalling fix rules that don't match?
Usually, first check that Global Routing is set to Config, the intended file is active, no broader rule matches earlier, and your test uses a new connection. Reinstalling does not explain rule order and may erase the details you need for comparison. Return to the installation chapter only if you have confirmed the problem is with installing or launching the app.