Official Guide · Quick Start

Shadowrocket Guide:
Import, Route, and Verify Connections

Follow the steps for a complete connection: prepare a working server entry, choose Global Routing, then verify with an actual access test. For your first setup, establish one connection before changing multiple configurations.

Example interface: iPhone / iPad Steps: Details → Routing → Connection → Verification Prerequisite: Your own connection details

STEP 01 / INPUT

Add Server: Add a server or import a subscription

First identify which type of details you have: a server address, port, and authentication parameters, or a subscription link that retrieves multiple entries. These use different import methods. Do not enter a subscription URL as a Host or use an ordinary web page address as a subscription. If your details are incomplete, check them with the original service provider rather than repeatedly changing Type.

Enter a server manually

  1. Open Shadowrocket and find Add Server in the SERVER area of Home. Tap Type and choose the protocol specified in your details, such as Shadowsocks or Trojan. The page displays the corresponding fields.
  2. Enter the Host and Port from your details, then enter the Password and any other parameters required by that protocol. Host is usually a domain name or IP address; enter the port as a number. Do not paste a full web URL with its path into Host.
  3. If the selected protocol shows Method, it must match the server configuration. Check TLS, SNI, and other transport parameters against the original details as well. Do not disable certificate verification just to make a test pass.
  4. Review the fields, save, and return to Home. Confirm that the new entry appears under SERVER, then select it as the server to use for the connection.

The official screenshot on the right shows an Add Server page with Type, Host, Port, Password, and Method. Not every protocol uses the same fields. Follow the selected Type and your server details. A descriptive name can help you identify an entry, but changing its name will not fix an incorrect address, port, or authentication parameter.

Import an existing subscription with Subscribe

If you have a complete subscription link, choose Subscribe from Type in Add Server, paste it into the URL field, then save and return to Home. Copy the entire address, including parameters after the question mark. Check that there are no extra spaces, line breaks, or punctuation at either end. A subscription URL may contain personal access credentials; do not post it in a public discussion or include it in a screenshot.

After saving, wait for the content to load, then check the relevant group and entries in Home. If the group name appears but has no server entries, first check whether the subscription update succeeded. Saving the URL alone does not provide a connectable server. To update an existing subscription, use the update action for its group instead of repeatedly adding the same URL. See the FAQ section on subscriptions and importing server entries for tips on organizing multiple subscriptions.

Add Server also shows Scan QR Code and Import from Cloud JSON at the bottom. Use these only if you already have the corresponding QR code or required details. Check the source before scanning, and review the protocol and address after importing. To complete this step, Home must show a server with complete parameters that you can select—not just a name.

Shadowrocket Add Server page showing Type, Host, Port, Password, Method, and import options at the bottom
Add Server: Choose Type first, then enter the fields required by the protocol.

STEP 02 / ROUTING

Global Routing: Choose Config, Proxy, or Direct

Once the server entry is ready, return to Home and open Global Routing. This determines the routing mode used after a connection is established. Selecting a server answers “which entry to use when a proxy is needed”; Global Routing answers “how to route each connection.” Check these two settings separately.

  • Config: Routes connections according to the rules in the current configuration file, which can direct different requests to PROXY, DIRECT, or other defined policies. Use this mode for rule-based routing, after checking the configuration.
  • Proxy: Sends connections handled by the client through the proxy path. This can help you check whether a server works while troubleshooting. It does not guarantee access to every app, protocol, or destination.
  • Direct: Sends connections handled by the client directly, so you can compare access over your local network. An active switch does not mean the current request is going through the selected server.

Check Config before using Config

If you choose Config, open Config at the bottom and confirm which configuration is currently active. Open the relevant file and check its Rule section. In the official screenshot, General, Rule, Hosts, URL Rewrite, and HTTPS Decryption are configuration sections; Add Rule is where you add a rule. For a quick start, review the existing rules first. You do not need to edit every section or enable HTTPS Decryption for an ordinary connection.

The two lines below illustrate rule syntax; they are not instructions to overwrite your current configuration. The first routes requests matching the specified domain suffix through the proxy. The second uses the proxy path when none of the earlier rules match. Rules are evaluated from top to bottom, so order matters. Interpret an individual line in the context of the full configuration.

DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

If you do not have a trusted configuration or do not yet understand the current rules, you can first use Proxy to test a server entry, then return to Config to review routing. Do not assume that access working in Proxy means the issue is fully resolved: the server may be working while the original rules, policy selection, or DNS settings still need attention. For detailed configuration questions, see the FAQ on rule-based routing and troubleshooting. This page focuses on completing a repeatable connection process.

Shadowrocket Config editor showing sections such as General, Rule, and Hosts, plus the Add Rule option
Config: Review the Rule section in the active configuration. This is not the Global Routing selection page.

STEP 03 / CONNECT

Home: Turn on the switch and check the connection status

After choosing a routing mode, return to Home and check which entry is selected under SERVER. The selected entry may have changed after updating a subscription, deleting an entry, or switching groups; do not assume it is the first name in the list. If you plan to switch servers, note the current entry so you can compare under the same conditions later.

  1. Find the connection switch at the top of Home. When disconnected, Not Connected is displayed. Turn on the switch to establish a connection.
  2. The first time you connect, the system may ask permission to add a VPN configuration. Read the system prompt, confirm that it was triggered by opening Shadowrocket, then allow the configuration and complete authorization with your device passcode or verification method.
  3. Return to Home and wait for the status to change. Confirm that the switch stays on rather than turning off immediately. If Not Connected is still displayed, stop the access test and use the troubleshooting steps on this page to find the cause.

Allowing a VPN configuration lets the client handle connections through network capabilities provided by the system. It does not verify that the servers in a subscription are available. A switch that stays on does not mean every destination is accessible. This step confirms only that the system connection is active; continue with the next step to check web access and routing.

If another VPN connection is active on the device, or the network configuration is managed by your organization, first check which connection is in use and review device management requirements. Do not run multiple competing connections at once for testing, and do not delete managed configurations whose purpose you do not understand. If you cancel a system authorization prompt, return to Home and try again to see whether it reappears. If the issue persists, check the VPN configuration status in the system settings.

During the initial test, leave the On Demand setting unchanged and note whether it was enabled. Changing On Demand before you understand its automatic connection conditions may cause the switch to turn back on after a network change, complicating troubleshooting. After testing and confirming stable manual connections, decide whether you need on-demand connections.

Shadowrocket Home page showing the Not Connected switch, Global Routing, Connectivity Test, and SERVER group
Home: Check the selected entry and Global Routing, then turn on the connection switch at the top.

STEP 04 / CHECK

Connectivity Test: Compare test results with real-world access

Once the switch stays on, use Connectivity Test from Home to check existing entries, then open a browser and visit a page you know is available. The first gives you a connectivity indicator under test conditions; the second checks whether a real request completes. Consider both results together: a low latency value does not guarantee successful web resolution, TLS negotiation, data transfer, or access from other apps.

  1. Record a baseline. Note the local network, selected server, and Global Routing mode, then visit the same page once. Do not switch between Wi-Fi and cellular while also changing servers; otherwise, you will not know which change affected the result.
  2. Check the actual path. To verify routing, find the relevant request in the connection records or Data view, if available, and check its matched rule and actual path. An increase in total traffic alone does not prove that a specific request used the proxy.
  3. Change one condition at a time. If access fails in Config, keep the same server and temporarily switch to Proxy for another test. To check the local network itself, compare with Direct. Record each result and restore your intended mode after testing.

If access works in Proxy but fails in Config, first check the matching rules, active policy, and DNS-related settings in the current configuration. If both modes fail, check the server parameters and local network. If only one app fails while the browser works, the cause may be that app's connection method, cache, or protocol requirements. Reopen the app and repeat the same action before clearing the entire configuration.

Verification is complete when the intended task works consistently and the route matches expectations—not simply when an icon appears or every test entry has a latency value. Repeat the same check on your usual network. If the result changes, note which network, mode, and entry failed; this is more useful for troubleshooting than simply saying “it won't connect.”

STEP 05 / DIAGNOSE

Settings: Check the failed stage instead of resetting everything

Start troubleshooting at the earliest point of failure. If entries were not retrieved, fix the import first. If an entry is present but the connection will not establish, check the server. If the connection is stable but access is unexpected, then check the rules. Breaking the issue into stages helps avoid repeatedly changing DNS before a subscription has loaded or changing passwords when system authorization was canceled.

No entries after import, or subscription update fails

Recheck the complete subscription URL, confirm it is still valid and includes all parameters, and check whether the current network can reach the server hosting it. Retrieving a subscription and connecting to a server are separate processes: existing entries may still connect while the subscription server is temporarily unreachable; conversely, successfully retrieving entries does not mean every server is available. Do not repeatedly add the same subscription. Keep the original group and investigate the actual update error.

An entry is present, but tests fail or the switch will not stay on

For a manually entered server, check Type, Host, Port, Password, and protocol-specific Method, TLS, or transport settings. Watch for capitalization and leading or trailing spaces when copying parameters. An incorrect system time may also affect certificate-related connections. If the switch will not stay on, first check system VPN authorization and other active connections. If it stays on but the server test fails, focus on the server details and reachability.

Tests return results, but web pages or apps still do not open

Open Test Method in Settings to confirm the current test method before interpreting Connectivity Test results; different methods cover different checks. Then compare Config and Proxy as described above. If only rule-based routing fails, check the matched rules. If only a specific app fails, note the exact action and symptoms instead of attributing an issue with one app to the entire connection.

Connections start automatically after a network change, or you need more diagnostics

Check the existing On Demand settings in Settings and confirm whether automatic connection behavior matches the current network conditions. For a manual comparison, note the original settings, temporarily disable them, and restore them after testing. Settings also includes Diagnostics, Proxy, TCP, and UDP options. Do not change all of them just because they relate to networking; adjust an item only when the error message or your connection details point to it.

If you need Diagnostics or connection records to investigate further, reproduce the issue once and keep only the information related to that action. Before sharing, hide the complete subscription URL, authentication parameters, server passwords, and personally identifiable information. A useful issue report includes the failed stage, Global Routing mode, network type, and the individual comparisons already performed. There is no need to publish the parameters themselves.

If you still cannot identify the cause, find the relevant category in the FAQ. For App Store purchases, store region, switching devices, or restoring a purchase, see the installation guide. These are acquisition issues and do not require changing Add Server or Config. When troubleshooting is complete, remove temporary test entries, restore your intended Global Routing mode, and confirm that access works again on your usual network.

Shadowrocket Settings page showing Test Method, On Demand, Diagnostics, Proxy, TCP, UDP, and other options
Settings: Check the items related to the symptoms and change one condition at a time.