Shadowrocket Setup Guide

Add Server: Add a Server or Import a Subscription

Open Shadowrocket and go to Home. This is where you check the server list, select the current server, and control the connection. If the list is empty, do not start by changing Config or DNS; first add your existing subscription or server details. A subscription link and an individual server share link serve different purposes: the former usually maintains a group of servers, while the latter adds one specific entry. Identify which type of link you have before choosing an option, so you do not paste a subscription URL into a server address field.

For a subscription link: select Subscribe

On Home, tap the add button in the upper-right corner to open Add Server. Open Type and select Subscribe. Paste your complete subscription link into the URL field, add a note to identify it, and save. Check that the beginning and end of the link are intact and that no chat text, line breaks, or extra spaces were included. Query parameters used to identify the subscription are part of the URL; do not remove them just to shorten what is displayed.

After saving, return to Home and wait for the subscription to load. When successful, the list should show the corresponding entries or group, not just a saved subscription URL. If you see a group name but no servers inside it, first check whether the update has completed, then confirm the link is still valid. Adding the same link again usually will not fix the issue and can make later identification and removal more difficult. For details on updating, groups, and organizing multiple subscriptions, see the Subscription and Server Management Guide.

For individual server details: enter them according to the protocol

If you have a server address, port, and authentication details, select the specified protocol under Type in Add Server, such as Shadowsocks, VMess, VLESS, or Trojan, and fill in the fields. Enter the server domain or address in Address and the port in Port. Fill in the password, UUID, encryption method, and other options according to your original details. Required fields vary by protocol; do not assume that similar names mean the fields are interchangeable, and do not paste an entire web address into a field that only accepts a server domain.

If your details include TLS, SNI, a transport method, or a path, check those parameters too; entering only the address and port is not enough. If you are unsure about a field, check the original details rather than repeatedly guessing values. If you have a QR code, use Scan QR Code. If you have an individual server share link, follow the app's prompts to import it from the clipboard. Whichever method you use, open the entry after importing to check the protocol and key parameters; scanning or pasting does not guarantee that all details are complete.

Step complete when: Home shows at least one identifiable server entry and the one you plan to use is selected. Add a note you can recognize to avoid confusing test entries. Subscription links, passwords, and complete share links may contain access credentials; do not include them in public screenshots or questions. Next, choose how traffic is handled, then turn on the connection.

Global Routing: Choose a Traffic Handling Mode

After selecting a server, open Global Routing from Home. This determines how connections are handled; it does not add a server or automatically fix incorrect authentication details. First, distinguish the three common modes: Config, Proxy, and Direct. These are not speed settings. Choose based on whether you need rule-based routing and whether you are setting up for daily use or troubleshooting a connection.

Config: Use the selected configuration

Config matches rules in the currently enabled configuration file. If you have a trusted configuration file, first open Config and confirm that the file has been downloaded locally and is selected. Then return to Home and set Global Routing to Config. Adding a remote configuration URL without completing its download or enabling it does not mean its rules are in use. A server subscription and a configuration file are different types of content; importing a server list does not also import a complete set of routing rules.

With Config, different requests on the same device may use different policies. Requests matching DIRECT do not go through a selected server just because one is selected; only requests matching PROXY are handled by the corresponding policy. So, opening one webpage does not prove that all requests went through the selected server. See the Glossary for terms such as DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL. This tutorial focuses on establishing a connection; do not rewrite an entire ruleset during initial setup.

Proxy and Direct: Make a clear comparison

Proxy sends applicable traffic through the proxy path and can be used temporarily to check the selected server during initial setup. If you do not have a configuration file yet, you can use Proxy for the connection test below, then switch back to Config according to your needs. The goal is to reduce the number of rule-related variables, not to guarantee that every app and all system traffic follow exactly the same path.

Direct does not forward the corresponding traffic through the selected proxy server, so it is useful for checking the underlying network or making a temporary direct-connection comparison. If you want to test a proxy server but leave Global Routing set to Direct, an enabled connection switch does not show that the server is working. After changing modes, return to Home and confirm the displayed value so you know the selection was applied.

Step complete when: You can say whether the current mode is Config, Proxy, or Direct and know which path the test is expected to use. With Config, you should also know the name of the currently enabled configuration file. Note this state; the next step covers only the connection switch and system authorization, without changing the server or rules.

Home: Turn On the Connection and Allow the VPN Configuration

Return to Home and check that the selected server and Global Routing mode are still set as confirmed in the previous steps. Then turn on the connection switch at the top. On the first connection, iPhone / iPad may show a system prompt to add a VPN configuration. This authorizes the app to create a local VPN configuration; it is not a subscription import step and does not create a remote server for you. Check which app initiated the prompt before continuing, and only proceed if you just turned on the connection yourself.

After confirming the request came from Shadowrocket, choose Allow and complete password or biometric authentication as prompted by the system. The method depends on your device settings. Then return to Shadowrocket and check whether the connection switch stays on. System authorization means only that the client has permission to establish this connection; the server's availability, authentication details, and routing rules still need to be checked separately.

If you accidentally tapped Don't Allow, return to Home and try turning on the connection again; watch for the system prompt to reappear. If you still cannot proceed, check the VPN page in system settings for existing configurations, then return to the app and try again. Settings may be organized differently across system versions; search for VPN in Settings. Do not make resetting all network settings your first response. Check the specific prompt and configuration status first to avoid affecting other network features that are working normally.

If the device already has another VPN connection, disconnect the one you are not using before turning on Shadowrocket. If the device is managed by a workplace or school, its policies may restrict VPN configurations; follow the device management requirements instead of repeatedly changing the subscription. While troubleshooting, do not enable or change On Demand yet, as on-demand conditions can alter the switch status and complicate your assessment of this manual connection.

Step complete when: System authorization is complete and the connection switch on Home stays on instead of immediately turning off. If it switches off as soon as you turn it on, note the system prompt and check the authorization and configuration steps in step five. If it stays on but webpages do not load, do not keep toggling it; continue to the actual access test.

Connectivity Test: Test the Server, Then Verify Access

Once the connection switch stays on, run Connectivity Test for the server you plan to use. The result indicates whether the server responds under the relevant test method; it does not verify every webpage, app, or rule. If the group contains multiple servers, make sure the test target matches the one currently selected on Home. Do not treat a successful test for another entry as evidence for the current connection.

Next, open a browser and visit a page you normally use that can refresh its content. Check at least one page that should be accessible on your underlying network and one target that should use a proxy according to your current configuration. With Config, they may follow different policies. When using Proxy as a temporary comparison, focus on whether the selected server can complete an actual request. Keep the test targets consistent so you can compare results after making changes.

Do not rely only on a page that has already loaded or on app cache. Open a new page or reload the content you want to check, and confirm that a new request is actually made. If the browser works but one app fails, first narrow the issue down to that app's requests, rules, or network behavior rather than assuming the entire connection is down. Likewise, an error from one website may be caused by the service itself; check another target for comparison.

To check the path further, open Data and review related connection records, using the target domain, time, and policy to guide your assessment. First make a clear new request, then look for its record rather than guessing based on a large amount of history. Logs may contain domains and other personal browsing details, so remove sensitive information before sharing troubleshooting material. Do not publish complete logs.

If Connectivity Test gets no response but webpages load, first check whether the test and the pages use the same server and path. Do not delete all entries based only on the test result. Conversely, a response in the test does not prove the connection is fully working: DNS, TLS, rule matches, or the target service may still cause failures. Record the initial response, system connection status, and end-to-end access separately.

Step complete when: You have verified an actual page with a new request and confirmed that the result matches the current Global Routing mode. If you temporarily switched to Proxy to test the server, you can now restore Config and test the same target again. Daily routing setup is complete only when the result after restoring the original mode also matches your expectations.

Connection Issues: Check One Variable at a Time

When something fails, note the current server, Global Routing mode, configuration file, and network first, then check the items below in order. Do not change the server, DNS, and rules and reinstall the app all at once; even if the issue is resolved, you will not know which change helped. Change one item at a time, reconnect, test the same page used in step four, and keep the original settings so you can restore them.

First check the underlying network and server details

Turn off the Shadowrocket connection and confirm the device can use its current Wi-Fi or Cellular connection normally. If Wi-Fi requires a sign-in page, complete that first; resolve network access issues before troubleshooting the app. Then return to Home, check the selected entry, and see whether the subscription can update and the server details are still valid. For manually entered entries, compare the protocol, address, port, authentication details, and TLS-related fields; do not check only the note.

If one entry in the same subscription fails while others work, keep the failed entry for comparison and temporarily select an entry that has been verified to work. If all entries fail, contact the provider of your existing information to confirm its status. A subscription URL opening or updating successfully only means the list was retrieved; it does not mean every server in it can establish a connection.

Then check Global Routing and Config

Check whether Global Routing was inadvertently left on Direct or whether a different configuration file is selected than expected. If Config fails, temporarily switch to Proxy and test the same target again. If Proxy works but Config does not, check the rule match and policy first; there is no need to re-enter all server details immediately. Restore the original settings after comparing results so you do not mistake a temporary troubleshooting mode for your normal configuration.

In a configuration, FINAL handles connections that do not match earlier rules, while an overly broad rule near the top may also change where a target goes. First check what the target actually matched, then decide whether to make an adjustment. Do not delete all rules just to make one page load. See the Glossary for rule order and matching behavior. For organizing and backing up subscription entries, continue with the Server Management Guide.

Finally check DNS and system connection status

If the server responds but domain requests keep failing, check the DNS settings in the current configuration. Prefer restoring settings that you already know work, and confirm whether the configuration specifies additional DNS behavior. Do not enter an unfamiliar address just because you see a “resolution failed” message. Consider both the path used by DNS requests and the policy used by the target connection; changing one address may not solve the problem.

If the connection switch will not stay on, rather than webpages failing to load, return to step three and check system VPN authorization, existing connections, and device management restrictions. For more help with “connected but unable to access” issues, see Troubleshooting Servers, Global Routing, DNS, and Rules. When describing the problem, include the step where it occurred, the current mode, and a redacted error message. Do not share subscription credentials or passwords.

Final check: Restore any temporary changes you no longer need, keep the server and configuration you are using, and verify actual access once more. When changing only a subscription or server later, start again at step one. When changing only rules, verify again from steps two and four; there is no need to repeat system authorization that is already complete.