Official Manual · First Setup

Shadowrocket Setup Guide

Follow this sequence: import → choose a mode → connect → verify → troubleshoot. First confirm that the connection works consistently, then adjust rules and everyday settings.

Use this page to complete the initial setup. Interface names such as Home, Add Server, and Subscribe are kept in English so you can find them in the app; their position and layout may vary slightly with the system language. For all settings and maintenance procedures, see From Beginner to Advanced. There is no need to adjust every setting before your first connection.

Step 01

Add a server or import a subscription

First identify whether you have a subscription URL, a single share link, or server details to enter manually, then choose the appropriate option.

Have a subscription link? Use Subscribe

Open Shadowrocket, go to Home, tap the plus button in the upper-right corner, and open Add Server. Choose Subscribe from the type options, then paste the complete subscription link obtained from your service provider into URL. If a remark is required, use a name that is easy for you to recognize; remarks only help organize the list and do not determine whether the connection works.

After pasting, check the beginning and end of the URL, including its parameters, and make sure there are no spaces, line breaks, or non-English punctuation. A subscription URL generally returns a set of server entries; it is not the service provider's website login page. Save and wait for the subscription content to load, then return to Home and check the SERVER section. To refresh an existing subscription, use the update action for that entry. Avoid adding the same URL repeatedly, or it may become difficult to tell which set of entries you are using.

If saving shows only the subscription name and no selectable servers, first check whether the update succeeded. Subscription links may contain credentials; do not post the complete URL publicly or share its QR code to explain an issue. When reporting a problem, include only the error text and field details with sensitive information removed.

Have server details? Enter them manually in Add Server

From Home, tap the plus button and open Add Server. Choose the protocol specified in your details, such as Shadowsocks, VMess, VLESS, or Trojan. Enter the address, port, and authentication information required by that protocol. Required fields vary by protocol. Do not enter one protocol's password in another protocol's identifier field, or switch protocols based only on similar names.

If your details also include TLS, SNI, a transport method, or a path, keep these consistent with the original information; leaving a field blank and entering an arbitrary value are not equivalent. Ask your service provider about any fields you cannot confirm, and verify them before saving. For a single share link, use the app's link import or clipboard detection option. If a clipboard access prompt appears, allow it only when you need to import the link, then check the imported fields.

When finished, return to Home and select the actual server entry you plan to use in SERVER. Seeing a name in the list only means the details have been saved; it does not mean the server is available. Do not repeatedly toggle the connection switch yet. First choose a Global Routing mode in the next step.

Step 02

Choose a Global Routing mode

The server entry determines where to connect; Global Routing determines how connections are handled. Check both separately.

Tap Global Routing on Home and check the current option. This guide refers to the three modes as Config, Proxy, and Direct. Match those names in the actual interface. After making a selection, return to Home and confirm that the displayed mode has changed; do not assume it is active just because you tapped an option.

What each Global Routing mode does and where to check it
ModeHow connections are handledHow to use it during initial setup
ConfigRoutes connections according to the rules in the active configuration.Use for everyday rule-based routing; also check which configuration is selected in Config.
ProxySends eligible connections through the currently selected server.Useful for checking that the selected server works before troubleshooting rule differences.
DirectConnects directly to the destination without routing through the selected proxy server.Use to compare the basic network with the proxy route; this does not confirm that the proxy is working.

For initial setup, if you are unsure what the configuration contains, start with Proxy and verify a basic connection. After it works, switch to Config and check whether everyday access behaves as expected. Do not assume that Proxy handles all system traffic in exactly the same way; system behavior, connection types, and how an app implements networking can all affect the result.

To use Config, open the Config page and confirm that the configuration you intend to use is selected, rather than merely downloaded. A server subscription and a rule configuration are separate: updating a subscription refreshes server entries but does not switch to a set of rules. When troubleshooting a page, do not replace the subscription, configuration, and DNS settings all at once, or it will be difficult to tell which change made a difference.

If a destination works under Proxy but fails under Config, first check rule matching and the selected policy. For the meaning of keywords such as DOMAIN-SUFFIX and IP-CIDR, see the glossary; you do not need to edit them during initial setup. Once you have chosen a mode and confirmed the selection, continue with the connection and system authorization.

Step 03

Turn on the connection and authorize the VPN

Select a server before turning on the switch. The first prompt to add a VPN configuration is part of the system authorization flow.

Start a connection from Home

Return to Home, check the selected server under SERVER and the current mode displayed in Global Routing, then turn on the connection switch at the top. Before connecting, you may see Not Connected. On the first connection, the system asks whether to allow a VPN configuration to be added. After confirming that the prompt was triggered by Shadowrocket, choose Allow and complete device authentication as required by the system.

After authorization, return to Shadowrocket and check whether the switch stays on and the connection status changes. Seeing the corresponding VPN entry in system settings is normal. It means the configuration required for the app to establish a system network connection has been saved; it does not mean the system filled in server details or that the remote server is available.

If you denied authorization or the switch turns off immediately

If you previously tapped Deny, try connecting again from Home and follow the system prompt to authorize. Also search for VPN in system settings and check whether there is an entry for Shadowrocket. Do not delete other VPN configurations in bulk without checking what they are for, especially entries required by device management or a work environment.

If the switch still turns off immediately after authorization, note the exact error message, then check that a server is selected, all required fields are complete, and no other VPN connection is currently in use on the device. Managed devices may restrict adding or enabling VPN configurations. If so, check the device policy rather than repeatedly importing the same subscription.

During the initial check, leave the existing On Demand settings as they are and use the manual switch to observe the full connection process. If the connection starts again automatically after you turn it off, check whether On Demand is enabled and whether any conditions trigger it. Find out what is initiating the automatic connection before changing settings, so you do not mistake automatic reconnection for a faulty switch.

Step 04

Verify that the connection is working

Check the device connection status, Connectivity Test, and actual webpage access separately. Do not use one result as a substitute for all three.

First find Connectivity Test on Home and test an imported entry. The result reflects the selected test method and reachability under the network conditions at that time; it is not a guarantee for every website. If an entry fails, note the current network, selected server, and test method. Do not delete an entire subscription based on a single result.

Next, open a browser and visit an HTTPS page you are authorized to access and can normally recognize. If needed, open a new page and refresh it so browser cache is not mistaken for a successful new request. Then check the specific destination you need to use. Being able to access ordinary pages but not a particular destination is different from being unable to open any page; troubleshoot accordingly.

If the current mode is Proxy, first confirm that basic access works consistently, then switch to Config and test the same destination again. Under Config, some destinations may connect directly as a normal result of the rules; not every request has to use the proxy. To determine the route for a particular destination, use the app's connection records or logs to check the domain and policy. Before sharing records, hide sensitive information such as server addresses, account details, and subscription parameters.

You can also briefly turn off the connection without changing network conditions, test the same page for comparison, then reconnect and test again. This comparison helps narrow down the issue; a single page cannot prove the route taken by all traffic. Existing long-lived connections in apps may continue using their previous route. After switching modes, send a new request or reopen the target app if needed.

Initial setup is complete when you can repeat the sequence: select a server → turn on the connection → access the destination → disconnect and reconnect. Note the remark for a working server and the current mode. After each subscription update or configuration change, repeat the same checks. Changes in traffic under Data can help confirm connection activity, but do not by themselves prove that a destination page loaded successfully.

Step 05

Common issues and checks

First identify the step where the failure occurs. Change one thing at a time, retest the same destination, and keep settings you can restore.

The subscription was saved, but no server entries appear

Turn off the connection and confirm that the device can access the basic network. Then check that the subscription URL is complete, has no extra spaces, and is not a service provider's webpage address. Subscription updates depend on the URL being reachable, the returned content being recognized, and access still being valid. If you see an authentication error or unexpected content, ask your service provider for current valid details. Do not try to fix it by repeatedly rewriting URL parameters.

An entry is present, but Connectivity Test fails

First check that you selected an actual server entry, then verify the protocol, address, port, and authentication fields. For manual entries, check especially that TLS, SNI, path, and transport method match the original details. If you have multiple entries, test another existing entry on the same network. One failing entry and all entries failing point to different areas, such as entry details or the basic network.

The switch is on, but webpages still do not load

Confirm that the mode is not Direct and that the selected server is the same entry you just tested. First check the same HTTPS destination under Proxy. If it works there but not under Config, check the active configuration and rules. If both modes fail, recheck the server fields and network conditions. Do not reset all Settings as a first step; a reset removes context that can help identify the issue.

Only some domains fail, or problems start after switching networks

For pages that fail selectively, note the exact domain, approximate time, current mode, and steps to reproduce the issue, then check rule routing and DNS-related settings. Do not enter a DNS address unless you know what it is for. If a problem starts after switching between Wi-Fi and cellular, disconnect and reconnect manually, then retest. Also check whether the current network requires web authentication first. If the system reports a normal connection but the target app behaves unexpectedly, rule out issues with that app's own session and cache.

What to keep when continuing to troubleshoot

Keep the original error message, network type, selected protocol, Global Routing mode, and the action after which the issue occurred. Before changing a configuration, keep a recoverable copy. Do not share a complete subscription, password, or QR code in public discussions. For common symptoms, see the FAQ. For complete checks covering DNS, rule matching, and configuration maintenance, see From Beginner to Advanced.

That is enough for initial use: confirm the details are imported, the mode suits your needs, authorization is complete, and access can be verified consistently. When adjusting On Demand, rules, or configuration later, work on one topic at a time and repeat the verification steps after each change.