Official Manual · First connection

Shadowrocket Setup Guide

Follow the steps in order: import, choose a mode, connect, and test. First establish a connection you can verify, then adjust rules and On Demand settings.

Keep the original details before you begin, and confirm that the subscription URL is complete and the server details are still valid. For the initial setup, leave On Demand disabled. After testing the connection, review its usage conditions to avoid automatic connections interfering with manual troubleshooting.

Step 01 · Home / Add Server

Add a server or import an existing subscription

First, confirm whether you have a subscription link or connection details for an individual server. Either can create a selectable server entry in Home, but the entry process differs. Subscriptions are generally used to update a group of servers together; an individual server requires you to enter its parameters according to the protocol. Do not identify the type solely by whether the link contains a particular English word; refer to the instructions from your existing service provider.

For a subscription link: choose Subscribe

Open Shadowrocket, go to Home, tap the plus sign in the upper-right corner, and open Add Server. Choose Subscribe in Type, paste the complete subscription link into URL, and add an optional note to help identify it. Then save. When copying, do not include quotation marks, spaces, or line breaks before or after the link, and do not remove parameters after the question mark; they may be required to identify the subscription.

After saving, wait for the subscription to finish loading, then return to Home to check the result. The correct checkpoint is that a subscription group and server entries appear in the list, not just that the edit screen has closed. If you only see the subscription name and no servers, first check whether the current network can access the subscription URL and whether the link has expired. Do not repeatedly create the same subscription, or it may become difficult to tell which set of details is in use.

Updating a subscription and connecting to a VPN are separate actions. An update retrieves changes to entries published by your service provider; it does not mean that a server is selected or a connection has been established. After a successful import, tap a server entry to make it the current selection. Then continue to mode selection and connection.

For an individual server: enter the parameters for its protocol

In Type under Add Server, choose the protocol specified in your details, such as Shadowsocks, VMess, VLESS, or Trojan. Then fill in the address, port, and authentication information shown by the interface. Different protocols require different fields; do not reuse a password, identifier, or transport parameter from one protocol for another. For fields such as TLS, server name, and path, check each value against the original details rather than guessing.

If your details are provided as a QR code, use Scan QR Code to read it, then check the parsed protocol and key fields. A QR code is an input method, not proof that the details are valid. Before saving, check for missing fields; after saving, return to Home and select the server. If you are unsure about a protocol name or parameter, consult the glossary, but use your server details as the final reference.

Completion check: A selectable server is listed in Home, and the server you intend to test is selected. Do not rush to connect yet; in the next step, confirm how requests will be handled.

Step 02 · Global Routing

Choose how requests are handled overall

Global Routing determines the overall handling mode; it does not fill in missing server parameters. Tap Global Routing in Home and check the current selection. The three modes are Config, Proxy, and Direct. For your first test, note the current selection and change only this setting during testing. This helps avoid mistaking differences between modes for an unreliable server.

Config: follow the active configuration

Config handles requests according to the active configuration, whose rules may send different destinations to DIRECT, PROXY, or another defined policy. Before using it, open Config and check which file is active. Make sure it is the configuration you intend to use. A server subscription and a Config file are different types of details: the former mainly manages servers, while the latter concerns rules and related settings. Importing a subscription does not also import a set of routing rules.

If you have a trusted configuration whose purpose you understand, enable it according to its instructions and then return to Home. Do not overwrite an existing Config just to complete this guide. Rule matching and DNS settings are covered in later setup topics; after testing the connection, consult the settings manual. For now, confirm which file is active and which route the target request is expected to take.

Proxy: check the route through the selected server

Proxy is useful for checking requests through the selected server during an initial test, with less influence from routing rules. It does not guarantee that every service will be reachable, nor does it fix authentication, TLS, or remote server problems automatically. If access still fails in this mode, check the server and network first rather than adding more rules. After comparing results, decide whether to switch back to Config based on your routing needs.

Direct: compare against the local network

Direct handles requests through a direct route and can help compare local network performance with the proxy route. If a page opens in this mode, that only shows that the relevant direct access works; it does not prove the selected server is working. Direct also does not mean turning off the system VPN switch. The mode selection and connection switch are separate controls.

Completion check: You know which mode is selected and what it does. If Config is selected, you should also know which configuration file is active. Note this state before moving on to connection authorization.

Step 03 · Home

Enable the connection and authorize the system

The system must allow a VPN configuration for the connection to work. Return to Home, check the selected server, confirm that Global Routing matches the selection you noted in the previous step, and then turn on the connection switch at the top. On the first connection, the system may ask to add a VPN configuration. Check that the request is for Shadowrocket, choose Allow, and follow the system prompts to enter a passcode or authenticate your device. The prompts depend on the device system.

If you canceled authorization, try connecting again from the app and follow the system request that appears. Do not repeatedly toggle the connection just because a web page does not change immediately. First check whether the connection switch stays on and whether a clear error appears. If the system still asks for confirmation, complete that process before checking the status in Home.

During testing, if another VPN app or an existing VPN configuration is connected, disconnect it and try again to avoid interference between connection states. Organization-managed devices may restrict VPN configurations; check the device management requirements rather than repeatedly deleting the app. If the device cannot complete system authorization, see the FAQ for help with installation and first launch.

A VPN status shown by the system means the corresponding system connection has been established or is in use; it does not confirm remote server authentication, domain resolution, or access to every destination. Conversely, if an indicator does not remain in the status bar, do not assume that alone means the connection has failed. Check the app switch and system VPN status together. The next step is to test an actual request.

Completion check: You have completed the required system authorization, and the app's connection switch stays on. Keep the current server and mode for now. Do not rush to change DNS, On Demand, or other advanced settings; run a test with fixed conditions first.

Step 04 · Connectivity Test

Test the server and actual access separately

Interpret test results in layers: server test results, web access, and expected rule behavior are not the same conclusion. First, use Connectivity Test in Home to check the server entry, then select the server you intend to use. The test method affects what the result means. A value only reflects conditions during that test; it is not the same as web page loading speed, and there is no need to keep switching servers to get a lower number.

Next, open a browser and visit a familiar page that normally works. Check whether it loads and responds to further interaction. Use a newly opened page if possible; do not treat cached text or images as proof that a new request succeeded. If only one app has a problem, visit the same service in a browser for comparison. This can help determine whether the issue is limited to that app before you change the whole configuration.

In Config mode, a page may open because a rule selected DIRECT. To verify the proxy route, first understand the expected policy for the destination in the active configuration. If needed, temporarily switch to Proxy and visit the same destination using the same server and network. Restore the mode you need after comparing. Do not switch Wi-Fi, the server, and the mode all at once; otherwise, it will be difficult to tell which change affected the result.

If Connectivity Test returns a result but web pages do not load, check the protocol used for actual requests, authentication, DNS, or the destination service. If the test fails but web pages work, first confirm the test method and whether the request actually used the proxy route. No single test is conclusive; consider the server test, browser access, and current routing selection together.

For further checks, view the Log in the app for the request and inspect its destination, connection errors, and handling route. Logs may contain browsing records and server details; keep them secure and do not publish them in full. For help reading DNS and Log information, see the DNS settings reference and the settings manual.

Completion check: You can identify the server, Global Routing mode, and network used for the test, and say whether the page worked. After verification, add any needed rules or On Demand settings one at a time, repeating the same test after each change.

Step 05 · Check each layer

Find common failures by checking the import first

Start troubleshooting at the earliest incomplete step, not by reinstalling. First identify whether the failure occurred during import, selection, authorization, or access. Change one item at a time, then repeat the same test with the same server and destination page. Keep the previous value so you retain a working baseline if there is one.

The subscription saved, but no servers appear in the list

First check whether the URL is complete, whether you copied a regular web page address instead of a subscription URL, and whether a line break cut off the link. Then confirm that the current network can retrieve the subscription and check the link status and format with your existing service provider. Subscription links contain sensitive credentials; do not paste them into public discussions, and do not create subscriptions repeatedly instead of checking the import error. If you already have working entries, keep them while resolving update issues.

The server appears, but both the test and access fail

For a manually added server, open its entry under Add Server and check the protocol, address, port, and authentication fields in turn, followed by TLS and transport parameters. For a subscription entry, first confirm that the subscription details are still valid, then update it. If just one entry fails, compare it with other entries you already have. If all entries fail, check whether the local network is working and whether the remote service has a general outage.

The connection switch will not stay on

First check that system VPN configuration authorization is complete, then check for another VPN connection or device management restrictions. Retry after confirming there are no pending system prompts. If the switch turns back on automatically after you turn it off, check whether On Demand is enabled. Temporarily pause automatic connection conditions and test manually to avoid mistaking automatic behavior for a faulty switch. Do not delete other configurations on the device without understanding the consequences.

The connection is on, but some pages have problems

Compare results in Proxy and Config first. If Proxy works but Config does not, focus on the active Config, rule order, and related DNS settings. If both fail, check the server and network again. Also confirm that the destination service itself is working, so a problem with one website is not mistaken for an app-wide issue. DNS should not be the default first setting to change; adjust it only when there is evidence of a resolution issue, and record the original value first.

Prepare a minimal reproduction record before reporting an issue

Record the device system, import method, protocol name, Global Routing selection, whether you used Wi-Fi or cellular data, and the exact step and prompt where the issue occurred. If you quote Log entries, include only the relevant error excerpts and remove subscription links, authentication details, passwords, and other private information. Do not share a complete configuration or QR code, or send credentials that could be used to access a service.

Once the basic connection works, the steps on this page are complete. See the FAQ for common questions and the glossary for protocols and rule keywords. To understand DNS, On Demand, Connectivity Test, and other settings in detail, continue to the settings manual; there is no need to change every option during the first connection.