Official Guide First-time setup / 5 steps

Shadowrocket Setup GuideImport, connect, and verify.

Follow the iPhone / iPad interface, starting with details you already have. First confirm that the server connects, then check whether rules handle requests as expected. If something goes wrong, review the steps in the same order.

§ 01ADD SERVER / SUBSCRIBE

Add a server or import a subscription.Start by adding the details to the list.

Open Shadowrocket and go to Home. First identify the type of details you have: a complete link used to retrieve a server list is usually imported as a subscription; individual server addresses, ports, protocols, and authentication parameters are suitable for manual entry. Choose one method; there is no need to add the same details twice. A successful import only means the app has read the details—it does not confirm that the server is usable.

Existing subscription link: choose Subscribe in Add Server

On Home, tap Add Server, open Type, and choose Subscribe. Paste your complete subscription link into the URL field. Check that it has no leading or trailing spaces, quotation marks, or line breaks, then enter a name you can recognize and save. Links may contain long query parameters. Do not remove anything after the question mark just to shorten the display, and do not use a service provider's sign-in page URL as the subscription link.

After saving, return to Home and wait for the subscription details to load. Check whether the corresponding group and server entries appear in the SERVER section. If you see a group name but no selectable entries, check the subscription address and your current network first; do not immediately add the same link again. To refresh an existing group, use its update action. If the update fails, keep the existing entries so you can still refer to them.

Existing server details: fill in the fields for the selected Type

If you have details for a single server, open Add Server and choose the protocol specified in your details under Type. For Shadowsocks, for example, enter Host, Port, Password, and Method as provided. Host is the server address and usually does not need a webpage path. Enter the exact Port and select the specified Method; do not guess based on similar names.

The authentication fields vary by Type. Check each required identifier, TLS setting, transport option, or other field against your details. Do not enter a password for one protocol into a field for another. If you have a QR code, use Scan QR Code, then check the Type and address after importing. Import from Cloud JSON is for data in a compatible format; it is not a general-purpose field for pasting subscription links.

After saving, return to Home, tap the server you plan to use, and confirm that the selection indicator has moved to that entry. You have now added the details and selected a server. Next, choose how requests should be handled. For more on managing subscriptions and duplicate entries, see Frequently Asked Questions. You do not need to organize every group before your first connection.

Shadowrocket Add Server page with Type, Host, Port, Password, Method, and QR code import options
Add Server: fields vary by Type; use your own server details.
§ 02GLOBAL ROUTING / CONFIG

Choose a Global Routing mode.Understand the difference between servers and rules.

The server determines which destination handles a proxy connection. Global Routing determines how requests are handled. These are separate settings. On Home, tap Global Routing and check the selected mode: Config, Proxy, or Direct. If the connection switch is on but some requests still connect directly, check this setting before importing the subscription again.

Config: apply the rules in the current configuration

To route traffic according to rules in everyday use, select Config. Then switch to the Config tab at the bottom and confirm that the configuration you want to use is present and selected. The Config page and the Config mode in Global Routing are related but have different roles: the former manages configurations, while the latter applies rules to connections. Selecting the mode does not automatically import a remote rule set.

In the configuration editor, you can see sections such as General, Rule, Hosts, URL Rewrite, and HTTPS Decryption. For your first setup, check the Rule section; there is no need to change every section just to establish a connection. Add Rule adds a rule. Keep a copy of the original configuration and note its rule order before making changes. If you are unsure about the source or purpose of an additional setting, leave it unchanged for now to avoid mixing connection and configuration issues.

Rules are matched in order. Once an earlier rule matches, later rules usually do not determine the result for that same request. The two lines below only illustrate the rule structure: the first sends local network addresses to DIRECT, and the second is the final match. This is not a server configuration or a complete configuration to replace your existing file with. Interpret PROXY according to the policy defined in your actual configuration.

IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

Proxy and Direct: choose a route or compare behavior

Proxy routes requests that can normally be handled through a proxy. You can use it temporarily to check whether an issue is related to rule selection, but it does not mean that every app or all system traffic will necessarily pass through the server. Direct provides a direct-connection comparison. If Direct is selected, an enabled connection switch alone does not mean requests are using the selected server.

For an initial check, compare the server connection with Proxy, then switch back to Config to review everyday rule behavior. Keep track of the current mode each time you switch. Do not replace a server, edit rules, and change networks all at once. See Frequently Asked Questions for more on rule keywords and configuration management, or the App Store guide for store access and account questions.

Shadowrocket Config editor showing General, Rule, Hosts, URL Rewrite, HTTPS Decryption, and Add Rule
Config: confirm the active configuration, then check Rule. Keep a copy before editing.
§ 03HOME / VPN

Turn on the connection.Check the status after system authorization.

Return to Home. First check the selected server in SERVER, then check that Global Routing is set to the mode you chose. Not Connected in the screenshot indicates that no connection had been established at the time. It shows where to find the switch; your device does not need to display exactly the same list.

Turn on the connection switch at the top of Home. The first time you do this, the system may ask to allow a VPN configuration to be added. Read the prompt, confirm that Shadowrocket initiated the request, and complete device verification as instructed. This authorizes a network connection configuration on your device; it does not ask you to enter your server password in a system account verification field. Once authorized, return to the app and wait for the connection status to change. Do not repeatedly tap the switch while the prompt is still open.

If you just denied authorization, return to the app and try connecting again, then check whether the system displays a new prompt. If the connection still cannot be established, check whether device management policies apply or another VPN connection is running. Do not delete system configurations you do not recognize. On a managed device, confirm that you are authorized to use the connection and follow your organization's requirements.

Proceed to verification only after the switch remains on and the app status changes. A changed status means the local connection process has progressed; by itself, it does not confirm successful remote server authentication, access to a target website, or correct behavior of every rule. If the switch immediately turns off again, you do not need to repurchase or reinstall the app. Note the system prompt and check authorization and configuration first.

For the first connection, keep your current Wi-Fi or cellular network unchanged and do not enable new On Demand conditions yet. First complete one manual connection and disconnection, then consider automatic connection triggers. This makes it easier to tell whether an issue comes from manual connection or repeated changes caused by automatic conditions.

Shadowrocket Home page with a Not Connected switch at the top, followed by Global Routing, Connectivity Test, SERVER, and Add Server
Home: check the server, Global Routing, and connection status at the top in order.
§ 04CONNECTIVITY TEST / VERIFY

Verify that the connection is working.Separate test results from real-world access.

Start by checking your basic network, not by comparing numbers. If needed, disconnect Shadowrocket and open a page you can normally access directly to confirm that Wi-Fi or cellular data is working. If the network is waiting for a sign-in page, the signal is interrupted, or the system restricts app access, server tests may fail too. Restore the basic connection first.

Return to Home and use Connectivity Test to check candidate servers. The test uses the current Test Method, so its result reflects reachability under specific test conditions. A response value does not mean that a target website, video, or other service is working. A timeout does not prove that the server details are permanently invalid. Check the test method, then test again under the same conditions.

Next, leave the connection on and open a page you actually need to use. Check whether it loads successfully. Seeing content that was already open in a browser is not enough; it may be cached. Reload the page or open another page on the same service. If only one app has an issue, narrow it down to that app, the target address, or the relevant rules instead of assuming the entire connection has failed.

Then check Global Routing. In Config mode, a destination may match DIRECT, PROXY, or another defined policy. A page loading successfully does not necessarily mean it used a proxy. To compare routes, keep the server and network unchanged, temporarily switch to Proxy, and test the same destination. Then restore Config. If Proxy works but Config does not, check the rules and configuration first. If both fail, check the server details, authentication, and basic network.

Once verification succeeds, keep the settings you confirmed as working. If a later rule or On Demand change causes a problem, return to these baseline conditions for comparison. For subscription updates, connection timeouts, and rule issues, search Frequently Asked Questions by symptom. You do not need to change every setting during your first connection.

§ 05SETTINGS / DIAGNOSTICS

Troubleshoot common issues.Check each item, from connection details to the network.

The list is empty after import, or the number of servers suddenly drops

First check that you imported a complete subscription link, not an introduction page or account page. Then confirm that your current network can retrieve a subscription response and that your service allows the content to be retrieved. Subscription updates can change the number and names of servers; this is separate from the app's connection switch. Keep the existing group, check with your service provider that the link is valid, and then update it. Do not try to fix the same address by repeatedly creating new groups.

Servers appear, but the connection keeps failing

Open the entry's edit page and check Type, Host, Port, and authentication fields one by one. Look for spaces, incorrect capitalization, or missing additional parameters introduced or omitted when copying. Return to Home and confirm that the entry you just checked is selected, not a server with the same name in another group. If the issue only occurs on one network, compare Wi-Fi and cellular data when available, but do not change the configuration at the same time or you may lose a clear point of comparison.

The test responds, but the page still will not open

Open Settings and check Test Method to understand which test you ran. A test response does not confirm that the full protocol handshake, DNS resolution, and access to the target service are all working. Test another known destination to see whether the issue is limited to one site or is more widespread. Then check the rules in Config and the current Global Routing mode. If Proxy works temporarily but Config does not, check rule order and the final match first. Do not change every DNS or TLS setting at once.

The connection keeps changing, or issues occur only after switching networks

Check whether On Demand is enabled and whether other device settings may affect the VPN connection. To rule out automatic triggers, note the original values, temporarily disable On Demand, and test the manual connection process again. Record interruptions after switching from Wi-Fi to cellular separately from the previous state. A successful reconnection does not by itself prove that the original rules were incorrect.

For further checks, use Diagnostics

Diagnostics in Settings can help with further troubleshooting. Note the time, destination, and status when the error occurs before reviewing the relevant diagnostic information. There is no need to change Proxy, TCP, UDP, and other settings all at once for a “complete check.” When describing the issue to others, share only the necessary error text and steps, and hide sensitive information such as subscription URLs, passwords, and authentication identifiers. Review diagnostic information before sharing it too.

If you still cannot connect after these checks, write down a reproducible sequence: the network type, selected Type, step where it fails, any system or app prompt, and the comparison results for Direct, Proxy, and Config. Check server authentication or subscription details with your own service provider. For app access and recovery, see the App Store guide; for other operation questions, visit Frequently Asked Questions. These details are more useful for finding the cause than saying only that it “doesn't work.”

Shadowrocket Settings page with Language, Test Method, On Demand, Diagnostics, Proxy, TCP, and UDP settings
Settings: check Test Method and Diagnostics first, and note original values before changing anything.
Download Shadowrocket