Step 01 · Add a server entry

Add Server / Subscribe: Import existing details

Open Shadowrocket and go to Home. Check whether the server list already has an entry before choosing how to add one. A subscription link retrieves a set of servers and provides subsequent updates; a single server link or manually entered parameters describe one specific connection. They serve different purposes. Don't assume a string is a subscription just because it looks like a URL.

Use Subscribe for an existing subscription link

On Home, tap the add button in the top-right corner to open Add Server. Choose Subscribe from the type list, then enter your complete subscription link in URL. If a name is required, use a label that's easy to recognize. Check the beginning and end of the pasted link, and remove any accidental spaces, line breaks, or explanatory text. Don't edit the link's parameters.

Save and return to Home, then wait for the subscription to load. After a successful import, the server entries from the subscription should appear in the list. A label helps identify the source but does not determine whether the connection works. If the list is empty and only the subscription name was saved, check for a retrieval or parsing error before turning on the connection.

A subscription link may contain private parameters that identify your account. Don't post the full link in public forums, include it in screenshots, or enter it on someone else's device. Use the same subscription for future updates to avoid duplicate entries. For update instructions and managing multiple subscriptions, see the Server Management Manual.

Use Add Server when you have individual server details

On Home, open Add Server again and select the protocol specified in your server details. Enter the server address, port, and authentication details required by that protocol. Shadowsocks, VMess, VLESS, Trojan, and WireGuard use different fields; don't copy a password or identifier from one protocol into another protocol's form.

If your server details also include TLS, Server Name, a transport method, or a path, check each value against the source. The server address and the name used for TLS verification may be different. Don't disable a required verification setting to reduce the number of fields. If a field is unclear, check the Protocol and Networking Terms, then ask the provider of your server details to confirm the required parameters.

If you have a recognizable server share link, use the corresponding import option. To scan a QR code, use Scan QR Code. Before scanning, make sure the code contains your own server details, then grant camera access if prompted. Whichever method you use, return to Home after saving and check that the entry is complete. A link being recognized does not mean the connection is working.

At the end of this step, the list should contain a recognizable server entry, with one server selected. Next, choose how traffic is handled, then connect.

Step 02 · Choose how traffic is handled

Global Routing: Choose a routing mode

On Home, open Global Routing and check the current selection. The three modes are Config, Proxy, and Direct. They determine how traffic is routed; they don't fill in missing server details or fix invalid authentication information.

Mode	How it handles traffic	What to check during your first test
Config	Uses the rules in the currently active configuration to determine how traffic is handled.	Confirm which configuration is active and which rule matches the test destination.
Proxy	Sends traffic covered by proxy handling through the proxy.	Check whether the selected server can complete the request.
Direct	Uses a direct connection.	Useful for checking direct access on the current network.

To use rules for everyday traffic, choose Config, then open Config to check which configuration file is active. The Config page manages configuration files, while the Config option in Global Routing routes traffic according to the active configuration. They are related, but they're not the same action. Importing a file into the list does not make it active.

If your first goal is to check the server connection, temporarily choose Proxy, run the test, then switch back to Config. This reduces the effect of rule-based routing on your initial check, but it does not guarantee that every request from every app on the device will use the same route. System network behavior and other settings can affect the result, so check the actual request logs.

Direct cannot confirm that a server is working. A site may open in this mode simply because the current network can reach it directly. Conversely, if a site still connects directly in Config mode, that doesn't necessarily mean the configuration is broken—it may have matched a DIRECT rule.

For your first test, note the selected mode. If you choose Config, note the active configuration name too. Leave your existing DNS and other advanced settings as they are; there's no need to copy rules you don't understand. For more on PROXY, DIRECT, REJECT, and rule matching order, see the Quick Reference. Once you've chosen a mode, return to Home and continue to the connection step.

Step 03 · Establish the system connection

Home: Connect and authorize

Return to Home, check that the server is still selected, and confirm that Global Routing is set as in the previous step. Then turn on the connection switch at the top of the screen. The first time you connect, the system may ask permission to let Shadowrocket add a VPN configuration. This authorization lets the app use the system network extension to handle connections; it is separate from importing a subscription.

Read the system prompt and confirm that the request is for Shadowrocket, then follow the instructions to allow the configuration to be added. The system may ask for your device passcode or authentication. When you return to the app, check that the connection status stays on. If you already approved a configuration, the same prompt may not appear again. Its absence doesn't indicate a connection problem.

If you denied the request, return to Shadowrocket and try connecting again. Check whether the system is still waiting for your approval. Don't tap the switch repeatedly; wait for the current action to finish before checking the result. Device management policies may prevent an iPhone or iPad from adding a VPN configuration. If so, confirm that the device allows this system feature.

For a clear first test, check whether another VPN connection is active on the device. Network configurations can interfere with one another, so keep only the connection you need while troubleshooting. Leave On Demand off for now so that automatic connection conditions don't change alongside your manual actions. Set up on-demand connections separately once manual connection is stable.

A switch that stays on and a VPN status shown by the system indicate that the system connection is established or running; they don't prove that the selected server can reach every destination. The system network extension may start even if the remote server rejects authentication. At this step, success means that authorization is complete and the connection status is stable. Continue to the next step to test the actual connection.

When you're done testing, return to Home and turn off the switch at the top. During your first test, don't delete the system configuration to disconnect. You may need to authorize a new configuration the next time you connect, and deleting it adds more variables to troubleshoot.

Step 04 · Verify with real requests

Connectivity Test: Check that it works

Once the connection status is stable, run Connectivity Test and check whether it completes or reports an error. The test location and available options depend on the current app interface. Keep the results and note the server, Global Routing mode, and network used so you can retry with the same conditions if it fails.

Next, open a browser, visit a specific test destination, and reload the page. First make sure the destination is responding normally, then check whether the new request completes. Don't rely on a page that's already open; cached content can still appear when the network is unavailable. When comparing settings, test the same destination each time.

A latency result is not the same as a successful request

Latency tests in the server list can help you shortlist entries, but they don't work exactly like real requests. A latency result doesn't confirm that authentication, TLS, and access to a destination all succeed. Likewise, a probe that gets no response does not by itself prove that the server is unusable. Check both Connectivity Test and an actual page request.

Check the routing policy in Config mode

In Config mode, check the app's connection logs for the request you just made. Confirm the destination domain and the policy actually used. A DIRECT match means the request connected directly according to the rules; a PROXY match means the rules sent it through the proxy. If the configuration uses a policy group, check which server the group selected—don't rely only on the default entry shown on Home.

Don't assume that an unchanged exit IP means the connection switch had no effect. The test destination may match a direct-connection rule, or the request may be reusing an existing connection. Make sure it's a new request, then check the matching rule and policy. To isolate the server connection from rule behavior, temporarily switch to Proxy and repeat the same test. Record the result, then restore the original mode.

Your first connection is verified when Connectivity Test, actual access, and the expected policy all agree. Keep this working setup, then try configuration changes one at a time. Save a restorable copy of the configuration before making changes. Don't change DNS, rules, and servers all at once after confirming a working connection, or it will be difficult to identify the cause of any problem.

Step 05 · Narrow down the failure

First connection failed: Check each step

First identify where the failure occurs: the subscription didn't import, the connection switch won't stay on, the connection is established but the test fails, or only some destinations are unreachable. Each issue calls for a different check. Change one setting at a time and repeat the same test instead of reinstalling repeatedly or changing multiple parameters at once.

No servers appear after saving a Subscribe link

Check that the URL is complete and that you entered your own subscription link—not an informational webpage or an individual server link. Check whether the error indicates a retrieval or parsing failure. For a retrieval failure, first confirm that your current network has internet access. For a parsing failure, verify the type and validity of the information. A subscription may contain expired authentication parameters; changing Global Routing won't fix that.

If the subscription imported successfully before but now fails to update, keep the existing entries instead of clearing the list. Note the update error, then check the status of your subscription. For help with duplicate entries, labels, or backups, see the Server Management Manual so you don't lose information that may still be useful while troubleshooting.

The switch turns off or authorization is incomplete

Check whether you denied the system authorization and whether the device restricts adding VPN configurations. Make sure another connection isn't repeatedly taking over the system network state. If you enabled On Demand, check its trigger conditions; for initial troubleshooting, switch to manual connection temporarily. Server and rule tests are meaningful only when the system connection stays up.

Connected, but Connectivity Test fails

First confirm that the server selected on Home is the one you intended to test. For a manually added entry, check the protocol, address, port, authentication fields, and TLS parameters again. Pay particular attention to accidental spaces and differences in capitalization. Changing the label or reordering entries won't fix connection parameters.

If you have another valid server entry, compare it while keeping the same mode and test destination. You can also compare Wi-Fi with cellular data, but reconnect and run the test again after switching networks. Use the results to narrow down the issue; they don't guarantee that a particular network or server will work in every situation.

Proxy works, but Config doesn't

First check which file is active in Config and which rule matches the test request. The configuration may route the destination to DIRECT, REJECT, or a policy group with no usable members. The server itself may be fine. Restore the last working configuration, then adjust the relevant rules one at a time. For rule keyword definitions, see the Quick Reference.

Only some domains fail

Check the logs for resolution errors, connection timeouts, or TLS verification errors. A DNS resolution failure is not the same as a server authentication failure, and one unavailable site does not mean all traffic is affected. Test other destinations first, then check the DNS settings in the active configuration. Don't try multiple DNS addresses from unknown sources at once, or disable certificate verification to hide a hostname or certificate problem.

If you need help, note the failure stage, exact error message, protocol, routing mode, and network type. Before sharing logs, remove subscription links, passwords, user identifiers, and other authentication details. Describing exactly which step succeeded and which failed is usually more useful than simply saying it doesn't work.

Shadowrocket Setup Guide