Shadowrocket Setup Guide
Import an existing configuration, choose a routing mode, connect, then test with an actual page. This guide walks through a first-time setup on iPhone or iPad. Start by getting one connection working before organizing additional servers.
1. Add Server / Subscribe: Import an Existing Configuration
First identify what you have, then choose the right import method. A link beginning with https:// that retrieves a group of servers is usually a subscription link. A link beginning with ss://, vmess://, vless://, or trojan:// is usually a single-server share link. If the address, port, password, and protocol settings are provided separately, add the server manually. A link’s prefix alone cannot confirm that it is valid; check it against the original configuration details.
Import a Subscription with Subscribe
Open Shadowrocket and go to Home. Tap the add button in the upper-right corner to open Add Server. Tap Type and select Subscribe, then enter your full subscription link in URL. Add a recognizable name in the notes field if available. Confirm, save, and return to Home while the subscription contents load. Layouts may vary slightly; look for the interface labels Type, Subscribe, and URL.
When pasting, include more than just the domain. The link path and parameters after the question mark may be needed to identify the subscription; leaving out part of the link can prevent updates. Don’t include the webpage title, explanatory text, or quotation marks around the link. The example below is for format only and cannot be used to connect. Don’t copy it into the app:
https://example.com/sub?token=xxxxBack in Home, check whether server entries appear in the subscription group. Saving a subscription link is not the same as successfully retrieving the server list. If you see only a group name and no selectable servers, resolve the retrieval issue before trying to connect. For your first import, keep the original group and server names so you can compare them with the source details. Reorder or rename entries after testing the connection.
Add a Server Manually with Add Server
If you have complete server details, open Add Server and select the Type that matches them. Then enter the server address, port, and authentication details. Shadowsocks, VMess, VLESS, Trojan, and other protocols require different fields; don’t put a password or identifier for one protocol into another. The address field is generally for a hostname or IP address, with the port entered separately. Don’t paste a partially split share link into the address field.
Compare the existing details to check the encryption method, TLS, Server Name, transport, and related paths. Fill in only the fields required by the selected protocol. In particular, distinguish the server address used to connect from the name used for TLS verification; they may differ, but don’t guess. If a required field is unclear, check the original configuration instead of changing several settings through trial and error. Save, return to Home, and confirm the new entry appears.
If you have a QR code, use Scan QR Code to read it. For a single-server share link, follow the clipboard import prompt if the app displays one, and allow camera or paste access when needed. After importing, open the entry to check its protocol and key fields. Scanning or pasting only provides a way to enter details; it doesn’t verify that the remote service is available. For multiple subscriptions, share-link fields, and backups, see the Subscription and Server Management Guide.
Step complete: The expected servers appear in Home, and you can select an individual server. If the subscription group contains multiple entries, select one to test. Don’t mistake the group name for a selected server. Keep this server selected as you move on to Global Routing.
2. Global Routing: Choose a Routing Mode
Find and open Global Routing in Home. This setting determines how requests are routed; it isn’t where you change the server password or switch subscriptions. For your first setup, distinguish among the three modes: Config, Proxy, and Direct. After choosing one, return to Home and check the displayed Global Routing value before connecting.
| Mode | How it works | When to use it |
|---|---|---|
| Config | Routes requests according to the rules and policies in the current configuration. | You have a specific rules configuration and need to route traffic by destination. |
| Proxy | Sends regular proxy traffic through the selected server, subject to system and app-level routing limits. | Test a server for the first time or compare it with Config. |
| Direct | Connects directly without sending the request through the selected proxy server. | Check your underlying network or confirm how direct access behaves. |
To check whether a newly imported server works, start with Proxy to reduce the impact of routing rules during troubleshooting. This is a test method, not a recommendation to use this mode in every situation. If you have specific routing needs, switch back to Config after confirming the connection and make sure the expected configuration is selected on the Config page.
The server list in Home and the rules in Config serve different purposes: the former provides servers to connect to, while the latter determines which requests use DIRECT, PROXY, or another defined policy. Importing a subscription doesn’t automatically select the right rules for your needs. In Config, a page may load because its request matched DIRECT; that alone doesn’t prove the proxy server works.
Direct is also worth understanding. It’s a routing mode, not a way to delete servers or clear app data. Use it to compare routing behavior during troubleshooting, but if a request is supposed to go through a proxy, Direct won’t provide the expected route. An enabled connection switch does not mean every request is going through the selected server.
Step complete: You know which routing mode is active and why you chose it. For an initial test, note the combination of server name and Proxy. Next, turn on the connection without also changing the configuration or server.
3. Home: Connect and Approve the System Prompt
Return to Home and check the selected server and Global Routing mode once more. If everything looks right, turn on the connection switch at the top. When connecting for the first time, the system may ask permission for Shadowrocket to add a VPN configuration. Read the prompt, confirm it was triggered by your action, and complete device authentication with your passcode or biometrics as required. This permission establishes a system network connection; it isn’t another app purchase.
If you previously denied permission, the connection may not proceed. Turn off the switch and try again, watching for the system prompt. If needed, search for VPN in the device’s Settings and check the configuration status for Shadowrocket. Don’t delete unfamiliar device management items just to retry. If the device is managed by an organization and you can’t change the relevant settings, check for management restrictions rather than repeatedly resetting network settings.
After granting permission, return to Home and check whether the connection switch stays on and whether the app displays an error. The VPN status may appear in the status bar or Control Center, depending on the device layout. This indicator can help confirm the system connection is active, but it doesn’t confirm remote authentication, DNS resolution, or access to every page. Complete the checks in the next step.
Avoid enabling another system VPN connection during testing. If On Demand is already configured, its automatic triggers may restart a connection you manually turned off. Note your existing settings and reduce automatic triggers during initial troubleshooting. After basic testing, configure On Demand for your network as needed so you can distinguish changes caused by manual actions from those caused by automatic connections.
If the switch immediately turns off, note the error and when it occurs: does it happen before system authorization, or does the connection fail after authorization? For the former, check permission status first. For the latter, also check the server details and current network. Don’t rush to reimport the entire subscription or change multiple protocol fields at once; keeping the original entry makes it easier to compare settings.
Step complete: The connection switch stays on, system authorization is complete, and the app hasn’t immediately reported a connection error. Keep the current settings and use a test and real-world access to check whether the connection meets your needs.
4. Connectivity Test: Check the Connection
Check three things: the device’s underlying network, the test result for the selected server, and access to the actual destination. First, make sure your Wi-Fi or cellular connection works. If Wi-Fi requires a browser sign-in, complete that process first. Without a working network, subscription updates and server connections may fail; changing app settings alone usually won’t fix the problem.
Return to Shadowrocket and find Connectivity Test in Home. Run the test for the selected server. Test methods and displayed results depend on the current app interface. Treat any result next to a server as an indication of reachability under that particular test—not as a complete check of every website or protocol behavior. A successful test doesn’t guarantee that a specific page will load; if it fails, consider the result alongside your real-world access test in the next step.
Keep the connection on, switch to your browser, and open a page you’re authorized to access and can normally use. Reload it if needed so cached page content isn’t mistaken for a new request. Then check the app or page you actually want to use and see whether it loads fully, not just whether the homepage text appears. If only one destination has a problem, rule out an issue with that destination before blaming the entire connection.
If you’re using Config, check the request log or diagnostic information visible in the app, if available, to review the destination domain, matching rule, and final policy. The available details depend on your settings. A DIRECT match means the request went directly; a PROXY match means you should also check the relevant server. Don’t overlook routing rules just because the connection switch is on.
To compare modes, keep the same server selected. Try the destination in Proxy, then switch to Config and repeat the same test. If Proxy works but Config doesn’t, check the active configuration, rule order, and DNS before changing servers. If both modes fail, check the server details and network. After each switch, make a fresh request and keep other conditions as consistent as possible.
There’s no need to chase a particular test score. A result depends on the test method, current network, and remote response, so it can’t establish long-term performance. For your first setup, focus on confirming that you can connect, access the destination, and use the intended route. Test links, subscription contents, and diagnostic logs may include personal configuration details. When reporting an issue, hide the full subscription URL, authentication details, and any unnecessary browsing records.
Step complete: The destination loads as expected, and the current routing mode matches your needs. To organize multiple subscriptions, see server management. If the test didn’t pass, troubleshoot by the stage where it failed below.
5. Common Issues: Troubleshoot by Step
First identify where the failure occurred, then address the relevant setting. Labeling the issue as “import failed,” “connection not established,” or “access failed after connecting” is usually more useful than refreshing a subscription, switching servers, and changing rules all at once. Change one setting at a time and repeat the same test. Once it works, restore your usual settings one by one.
Import Failed: Check the Full Link and Content Type
If no servers appear after saving a subscription, check that the URL is complete and contains no extra spaces or line breaks. Confirm that it retrieves subscription contents rather than opening an account page or instructions. Check the status of your existing subscription to see whether the link is still valid. Refreshing retrieves the remote contents again; it can’t fix an expired link. If the error concerns the format, check whether Subscribe can recognize the content instead of changing authentication settings.
If a single-server share link won’t import, check that you copied the entire link and that it wasn’t cut off by chat text or a line break. If a manually added entry saves but won’t connect, compare its Type, address, port, and authentication details with the original information. Saving confirms that the entry was added to the app; it doesn’t confirm that the remote connection works.
Connection Failed: Check Authorization, Settings, and Network
If system authorization isn’t complete, respond to the VPN configuration prompt first. If a configuration already exists but the switch won’t stay on, note the error from the app, then check the protocol and its fields. Address resolution, port reachability, authentication mismatches, and TLS name mismatches can fail at different stages; reinstalling the app isn’t a universal fix. Don’t lower certificate verification requirements to dismiss a prompt. First correct any settings that don’t match the original configuration.
If the connection fails on Wi-Fi, switch to cellular if available and allowed, then test with the same server and routing mode; you can also compare in the other direction. If the issue occurs on only one network, first check its sign-in requirements, connection restrictions, or DNS behavior. This comparison helps narrow down the cause, but one test can’t establish the long-term status of a remote service.
Connected but Can’t Access Pages: Check Routing and DNS
Return to Home and confirm that the expected server is selected. Then check whether Global Routing was left on Direct by mistake. If Proxy works but Config doesn’t, open Config, verify the selected configuration, and check whether the destination matched the expected rule. DNS results, rule order, and the final policy can all affect behavior. Don’t change the entire configuration at once; first reproduce the issue with the same destination.
If only one app has a problem while the same destination works in a browser, consider that app’s cache, session, or reused connection. End the app’s current task and try again before clearing Shadowrocket data. If behavior doesn’t change immediately after switching modes, wait for the old connection to close or initiate a new request before drawing conclusions.
Keep a Record of Troubleshooting Results
Note the device’s network type, current routing mode, your custom server name, the step where the failure occurred, and a redacted version of the error text. Don’t share subscription links or passwords publicly, or post a full configuration as an ordinary screenshot. If the original entry still works, keep a backup before deleting or reimporting it so troubleshooting doesn’t cause you to lose information you need.
For purchase restoration, permissions, and rules, see the FAQ. For subscription updates, managing multiple subscriptions, latency tests, and backups, continue with the Subscription and Server Management Guide. Once you’ve confirmed a repeatable successful connection, add servers or configure automatic connections one at a time, testing access after each change. This makes it easier to trace any later issues.