Shadowrocket Getting Started
Import Subscription → Global Routing → Authorize Connection → Verify Access
This guide is for iPhone and iPad and follows the steps for first-time use. Start by establishing a connection you can verify, then adjust rules and automatic connection settings. See the server management guide for organizing servers, updating subscriptions, and backups.
Add a Server or Import an Existing Subscription
Open Shadowrocket and go to Home. The SERVER section below lists saved servers. If this is your first time using the app, find Add Server. The goal isn’t simply to add any entry to the list; it’s to save your existing details using the correct type. First identify what you have: a subscription link, a server share link, or separate address, port, and authentication details. Then choose the appropriate method.
Have a Subscription Link? Use Subscribe
After opening Add Server, choose Subscribe under Type, then paste the full subscription link in the URL field. You can add a note to identify it, then save and return to Home. Wait for the subscription to load. If the entries aren’t expanded, check the corresponding subscription group. To fetch it again, use the update action on that subscription instead of adding the same link repeatedly.
Select and copy the entire link, including any trailing parameters. Watch for line breaks and extra spaces. Don’t use a sign-in page or an information page URL as a subscription link, and don’t remove parameters that look unnecessary. The example below shows only the link format. Use your own valid link; don’t copy the example.
https://example.com/sub?token=xxxxHave Server Details? Enter Them Manually by Type
If you have individual server details, choose the matching Type in Add Server, then enter the Host, Port, and authentication details required by that protocol. For example, Shadowsocks requires the correct Password and Method. Fields vary by protocol, so don’t assume they all use the same set. Enter only the required hostname or IP address in the host field, the port number in the port field, and keep authentication details exactly as provided.
For TLS or transport settings, follow your existing server details field by field. Don’t change a setting just because it appears optional. In particular, keep the specified server name, path, and transport type. If details are missing, check with your existing service provider. Saving confirms only that the entry has been added; it doesn’t verify remote authentication or establish a connection.
Have a QR Code or Share Link? Check It Before Saving
If you have a QR code, use Scan QR Code. On the first scan, follow the system prompt to allow camera access. If you have a complete server share link, copy it and return to the app. If an import prompt appears, check the parsed type, hostname, and port before confirming. Import from Cloud JSON is for the relevant JSON data; it isn’t a destination for every subscription link. Don’t choose it just because the name sounds similar.
Return to Home and check that the expected entry appears under SERVER, then select the server you want to use. If a subscription contains several entries, choose one with clear details for your first test; there’s no need to organize every name and sort order yet. For multiple subscriptions, updates, and backups before deleting entries, see Subscription and Server Management. Next, choose how traffic should be handled.
Choose a Global Routing Mode
Once you’ve saved and selected a server, open Global Routing on Home. This setting determines how requests are routed; it’s separate from the server address you just entered. Even with correct server details, an unexpected mode can make the app appear connected while access behaves differently than expected. First decide whether you’re testing the server or using your existing rules, then choose a mode.
- Config: Handle requests according to the rules in the current configuration. Requests matching a direct policy connect directly; requests matching a proxy policy use the corresponding proxy route. The selected server alone does not determine where every request goes.
- Proxy: Send requests handled by the app through the proxy policy. This can help temporarily isolate the effect of rules. You still need a working server; Proxy does not replace server authentication or fix incorrect details.
- Direct: Use the direct policy. This is useful for comparison when checking your basic network connection or whether a destination is accessible. It does not show that the proxy server is working.
To test an existing server for the first time, you can temporarily use Proxy, then switch back to the mode that fits your configuration. If you already have a specific rule file, open Config and check which configuration is selected; don’t just check whether a file appears in the list. Only rules in the active configuration affect traffic in Config mode.
What to Check on the Config Screen
Open the relevant configuration’s editor to see sections such as General, Rule, Hosts, URL Rewrite, and HTTPS Decryption. To get started, focus on Rule and policy references; you don’t need to enable these features just to connect. Use Add Rule to add a rule. If your existing configuration works, there’s no need to rewrite the entire file first.
Rules are usually matched in order, so an earlier rule may determine how a request is handled. FINAL handles requests that didn’t match an earlier rule. The snippet below demonstrates rule syntax; it isn’t a complete file to replace your current configuration. The policy referenced by PROXY must also exist in your configuration. Don’t treat the example domain as a real service to test.
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXYIf you’re unsure about the difference between a policy name and a protocol name, see Rules and Policies in the Glossary. For your first connection, just keep track of the current mode, configuration, and selected server. Once you’ve checked them, return to Home and turn on the connection.
Turn On the Connection and Authorize It in iOS
Return to Home. First check the selected server under SERVER, then check the mode shown under Global Routing. If the top of the screen shows Not Connected, the connection hasn’t been established. Tap the connection switch beside it to connect. Importing a subscription does not automatically start routing traffic.
The first time you turn on the switch, iOS may ask to let Shadowrocket add a VPN configuration. This authorization allows the app to handle device traffic using system network capabilities. It isn’t another app purchase or a step for adding a server. Check that the prompt refers to Shadowrocket, then follow the system instructions and complete any required passcode or identity verification. The system handles authorization; don’t enter your device passcode in a server field.
If you canceled the authorization prompt, return to the app and turn on the switch again to see if it reappears. Once authorization is complete, return to Home and wait for the connection status to change. The status and system VPN indicator can confirm that the system network tunnel is established, but they don’t guarantee that the selected server can reach every destination. Continue to the next step to test access.
Keep Conditions Consistent Before and After Connecting
For an initial troubleshooting check, stay on the same Wi-Fi or cellular network. Don’t change the network, server, configuration, and mode all at once. If another VPN connection is active, disconnect it before retrying Shadowrocket to avoid mistaking a system connection switch for a server problem. After each change, check the status at the top of the screen rather than relying on whether the switch was turned on.
On iPad, follow the same steps: select an entry, check the mode, turn on the switch, and complete system authorization. The layout may vary by device and display settings, but the relevant controls use the same English labels. To stop the connection, turn off the switch at the top. Disconnecting does not delete saved servers or subscriptions; you can use them again later.
If the switch turns off shortly after you turn it on, or the connection never completes, pause and note any system message. Don’t delete all your data right away. Go to Troubleshooting to distinguish an authorization issue from a remote connection issue. If the connection stays on, continue testing; “Connected” alone doesn’t mean setup is complete.
Verify the Connection and Rules
Once connected, run Connectivity Test on Home for an initial check, and wait for it to finish. The result reflects the response for a specific test method and destination; it doesn’t mean every app and website is accessible. If a server responds to the test but a page still won’t load, check actual requests rather than simply running the test again.
Check Three Layers: Connection, Access, and Policy
- Connection: Return to Home and confirm the connection is still active, the selected server hasn’t changed, and Global Routing is set to the mode you noted earlier.
- Access: Open a browser and visit a destination you’re authorized to use and can normally check. Reload the page so you aren’t seeing cached content.
- Policy: In Config mode, use available in-app request records to check which rules and policies actually matched. Requests expected to use a proxy should match the proxy route in your configuration; for requests expected to connect directly, check for DIRECT.
If a destination works in Proxy but fails in Config, first check rule order, policy references, and the selected configuration instead of immediately re-entering the server password. If it fails in both modes, check your basic network connection and server details. Direct can provide a comparison, but whether the destination allows a direct connection also affects the result. One page alone is not enough to draw a conclusion.
When comparing results, change one variable at a time: keep the destination and network the same and switch only the mode, or keep the mode the same and switch to one other existing server. After testing, restore the mode you plan to use and revisit the destination. Don’t enable several advanced features just to “see what happens”; that makes issues harder to isolate.
A successful check means the connection stays active, access to the destination behaves as expected, and rule routing in Config mode makes sense. A single latency reading is not a speed guarantee, and one failed test does not prove that the entire subscription is invalid. If only a specific destination has issues, note its domain, when the issue occurred, and the mode you used, then check the items below.
Find Common Issues by Symptom
First identify when the issue occurs: no servers appear after import, the switch won’t stay on, nothing is accessible after connecting, or only some requests behave unexpectedly. Each stage has different things to check. Keep existing data and error messages, change one thing at a time, then retest in this order: connect, run a test, and check actual access.
The List Is Empty After Import: Check the Link and Import Result
Return to the subscription entry and check that the link is complete, with no extra spaces or missing trailing parameters. Make sure it’s an existing subscription link, not an account sign-in page. If the link must be fetched over your current network, check that the network can reach it. If needed, ask your existing service provider about the subscription status and response format. Don’t add the same link repeatedly, and never post the full link in a public support request.
The Switch Won’t Stay On: Check System Authorization First
First confirm that you authorized the VPN configuration in iOS, then check for another active VPN connection. If iOS shows a specific error, record its exact wording before taking further action; don’t assume every issue is caused by the server password. Reopen the app, try connecting again, and check whether it stops at the same stage. Consider deleting a configuration or reinstalling only after you know where your data is backed up.
Connected but Can’t Access Anything: Check Server Details and Mode
Make sure the mode isn’t Direct, then check the selected server’s Type, Host, and Port, along with its authentication, TLS, and transport settings. When adding details manually, common mistakes include choosing the wrong protocol, entering the wrong port, or adding a space to the password. For an imported subscription, check the update result first rather than guessing and changing multiple fields. If your basic network connection can’t reach ordinary destinations either, troubleshoot network access first.
Only Some Requests Fail: Check Rules and Test Method
If Proxy works but Config doesn’t, return to Config and check the active configuration and rule order. If only the test result seems wrong, open Settings and check Test Method. Consider whether the selected method reflects how you’re actually testing access. Changing the test method only changes what the test measures; it won’t fix incorrect server details. Check TCP and UDP settings against the capabilities of your existing service; don’t switch everything at random when troubleshooting.
Connection Behavior Is Unexpected: Check On Demand
Open Settings and check On Demand. It controls automatic connection behavior when its conditions are met; it does not create server details. For your first working connection, connect manually and note the current settings. Once the manual process is reliable, configure automatic connection conditions one at a time. If the connection returns after you turn it off or behaves differently when the network changes, check this setting before deleting a subscription.
For further analysis, use the diagnostic information in Diagnostics and narrow the issue down to a specific reproducible action. Before sharing diagnostic material, redact subscription links, authentication details, personal addresses, and other sensitive information. Check screenshots for the same details. For more symptom-based guidance, see Frequently Asked Questions. For updating, sorting, and backups, see the Server Management Guide.
