Shadowrocket Setup Guide
Follow five steps—add, choose a mode, connect, test, and troubleshoot. First establish a repeatable connection, then adjust rules and automatic connection settings as needed.
These screenshots are official App Store images, provided to help identify screens and fields—not as configurations to copy. The actual menus and fields may vary; use what’s shown in the app on your device.
Add Server: Add a server or import an existing subscription
First, check whether you have details for a single server or a subscription link that returns a server list. Both start from the add screen, but they use different Type options.
Have server details? Enter them for the correct protocol
On Home, find Add Server and tap it. Check Type first. Choose the protocol specified in your details, then enter the Host, Port, and any authentication fields required by that protocol. Don’t choose a different type just because some fields look similar. Even if the details save, a protocol mismatch can prevent the connection from working.
For example, with Shadowsocks, Host is the server address, Port is the port number, and Password and Method must match the server exactly. Other protocols may use different authentication or require additional parameters, such as TLS or a transport setting. Enter each value according to the details you have. Host is generally just a hostname or address—don’t paste a full subscription link into it or add a path that wasn’t provided.
When you’re done, use the page’s save option. Return to Home and confirm the new entry appears in the SERVER list. A name is just a label to help identify the entry; it does not replace the address or port. If you add several entries, use labels that distinguish their purpose so you don’t select the wrong one during testing.
Have a subscription link? Choose Subscribe
In Add Server, choose Subscribe under Type. On the page that opens, enter your complete subscription link in URL, add a label you can recognize, and save. The path and query parameters may be needed to identify the subscription, so copy the entire link. Check that it hasn’t been cut off at the end or copied with spaces or line breaks.
Return to Home and check whether the subscription group has loaded server entries. If the list is missing, look for an update error and retry using the update option for that subscription group. A successful import only means the list was retrieved; test each server separately to confirm it works. Updating a subscription does not replace the rules file active in Config.
For a single share link or QR code, use the corresponding import option supported by the app. Scan QR Code is for scanning an existing QR code; Import from Cloud JSON is for the corresponding Cloud JSON data. Neither is a universal way to import any subscription. After importing, open the entry to check its Type and key settings, then continue to choosing a routing mode.
Global Routing: Choose Config, Proxy, or Direct
Global Routing determines how requests are handled; it does not fill in missing server details. Understand the selected mode before connecting.
On Home, open Global Routing and check the current selection. The three basic modes are Config, Proxy, and Direct. After choosing one, return to Home and confirm the expected value appears next to Global Routing. Don’t rely on what you remember using last time; it may have changed during troubleshooting.
Config: Route requests according to the active configuration
Config is for setups that use rule-based routing. Rules and other settings in the active configuration determine whether requests use PROXY, DIRECT, or another defined policy. To use this mode, open Config at the bottom and check which configuration is active and what its Rule entries specify. Importing a subscription on Home does not mean the rules are set up as expected.
The official Config editor screenshot shows sections for General, Rule, Hosts, URL Rewrite, and HTTPS Decryption. To get started, just check the active configuration and Rule; you don’t need to change every section to connect. Add Rule opens the rule editor. If you’re unsure what a rule matches or what its policy does, keep the existing configuration for now so you don’t mix up import issues with rule issues.
Proxy: Use for a brief comparison
Proxy routes general requests through the selected proxy path, making it useful for a brief comparison with Config during troubleshooting. If a destination works in Proxy but fails in Config, check which rules match and the related settings before rebuilding the server entry. Proxy does not guarantee how all system traffic or every app behaves. After testing, restore the mode that fits your needs.
Direct: Distinguish basic network issues from proxy-path issues
Direct connects to the destination directly; it is not a button for changing servers. If you want to test the selected server, don’t leave Direct enabled and use that result to judge the server. Direct is more useful for distinguishing basic network problems from proxy-path problems. After choosing a mode, return to Home, select a server, and connect.
You don’t need to master rule keywords, protocol parameters, or performance trade-offs before your first connection. To check the fields for a selected Type, read the protocol reference. For the difference between routing modes and On Demand, see the settings guide.
Home: Select a server and connect
A server appearing in the list doesn’t mean it’s selected or in use. Select it, turn on the switch at the top, then check system permission and connection status.
Return to Home and tap the server you want in the SERVER list. Check that the selection indicator is on the correct entry. If the list includes multiple subscription groups, verify the group name and label; a change in list order doesn’t mean the server has changed. Then check Global Routing again to make sure it still matches your choice in the previous step.
Turn on the connection switch at the top of Home. When disconnected, the screen may show Not Connected. After switching it on, wait for the status to change rather than toggling it repeatedly. The first time you connect, the system may ask to add a VPN configuration. Confirm the prompt is from the Shadowrocket action you just started, follow the system instructions to allow it, complete device verification if requested, and return to the app to check the status.
VPN configuration permission allows the app to handle traffic through the system network extension. It is not a subscription login and does not create a server for you. If you denied permission, return to the app and try connecting again to handle the prompt. If your device is managed by an organization, restricted by system settings, or has another VPN configuration, first check whether its policies allow this type of connection. Don’t repeatedly delete configurations and try again without checking.
A change in connection status only shows that the connection process has progressed; it does not prove that the remote server works or that all requests are routed as expected. Keep the current server and mode, then continue to the next test. If the switch turns off immediately or an error appears, note the exact error and when it occurred, then go to Troubleshoot issues. Avoid changing several settings at once, or you may not be able to restore the original setup.
Connectivity Test: Check the connection and real-world access
Test in two ways: server tests provide clues, while real requests show whether it works for your use. Consider both results together.
On Home, tap Connectivity Test and wait for the results in the list to update. The test method affects what the results mean; check the current method under Settings → Test Method. A result for one entry only shows that the selected method completed a test at that time. A timeout doesn’t necessarily mean the server is unusable for every purpose, so check it against a real request as well.
Next, keep the connection active and open a webpage you normally use for testing in your browser. First make sure the page loads, then check the specific destination you need to verify. Use a new request if possible rather than relying on a cached page. If only one app has a problem while the browser works, don’t assume the whole connection has failed; note which app and destination behave differently.
To check rule-based routing, compare Config and Proxy using the same network, server, and destination. Change only Global Routing between tests. If the results differ, return to Config and review Rule and related settings. Rules are generally evaluated in order, so an earlier match may determine the route. Seeing a rule in the configuration does not prove that the request matched it.
Changes in traffic under Data can help indicate request activity, but total traffic alone can’t show which route a webpage used. After testing, restore the mode you intend to use and note the selected server, configuration name, and test destination. If a problem occurs later, retest under those same conditions; this makes it easier to identify what changed than switching entries repeatedly.
Settings: Troubleshoot common issues in order
Start with the basic network, then check the server, mode, DNS, and rules. Change one thing at a time, and note the original value before each change.
Layer 1: Check the network, subscription, and server
Temporarily disconnect Shadowrocket and check that your device’s basic network works, especially whether the current Wi-Fi requires you to sign in first. If the network itself is unavailable, fix that before changing proxy protocols or rules; they can’t repair a network connection that hasn’t been established.
If the subscription hasn’t loaded any entries, check the saved URL for completeness, review any update notice, and make sure the link is still valid. If entries are present but connection fails, open the server and check Type, Host, Port, and authentication fields. Also check whether the subscription details have changed. Confirm that your own connection details are still valid before deciding to update the subscription; not every failure requires importing it again.
Layer 2: Compare routing modes, then check DNS and Rule
On Home → Global Routing, make sure Direct hasn’t been selected by mistake and that the selected server is the one you just checked. Briefly compare with Proxy. If the same destination works, focus on Config; if it still fails, check the server details, basic network, and destination. Don’t switch networks and servers during the comparison, or you won’t know which change affected the result.
DNS is one thing to check when domain names fail, but it isn’t the only possible cause. Note the DNS settings and any related messages in the current configuration, then check for typos or conflicts. Don’t repeatedly apply configurations you don’t understand or assume one fixed address will fix every network. If Proxy works but Config doesn’t, check Rule order, what the rules match, and the final policy.
Layer 3: Check On Demand and Diagnostics
If the connection turns back on by itself after you disconnect, open Settings → On Demand and check whether any triggers are enabled. On Demand controls when a connection starts; Global Routing controls how requests are handled. They are separate settings. For initial troubleshooting, note the original On Demand settings and, if needed, temporarily disable them to reduce variables. Once a manual connection is stable, restore them.
For further diagnosis, check Settings → Diagnostics and note the exact error, when it occurred, network type, and steps to reproduce it. Don’t change Proxy, TCP, or UDP options you don’t understand just to try a fix. Before sharing diagnostic details, redact your subscription URL, server authentication information, and anything else sensitive. The protocol type and stage where the error occurred are usually enough to help narrow down the cause.
If the issue occurs with only one protocol, check its required fields and transport conditions in the protocol reference. To review the setup steps, return to this page’s add and import instructions and check each item against valid details you already have. After troubleshooting, restore temporary changes so you don’t leave Proxy enabled or automatic connection conditions disabled by mistake.
