Home · Add Server · Subscribe

Add a server or import an existing subscription

After opening Shadowrocket, stay on Home. This page shows saved server entries, lets you select the entry to use, and controls the connection switch. If the list is empty, first enter your existing connection details into the client. There are two common methods: add one server field by field, or use Subscribe to import server details you maintain yourself. Both methods create selectable entries in Home, but their update processes differ.

Method 1: Enter details with Add Server

In Home, find the add option and open Add Server. Based on the existing server details, choose the matching type, such as Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, or Hysteria2. The protocol type must match the existing details; similar names are not interchangeable. After you choose a type, the page displays the fields required for it, usually including the address, port, authentication details, and protocol-specific parameters.

Check each field against the original details as you enter it. Put only a hostname or IP address in the address field and only digits in the port field; do not paste explanatory text, spaces, or an entire URL into these fields. For encryption, transport, TLS, SNI, path, and similar options, follow the existing server details. It is normal for some protocols not to use certain fields, so do not invent values just to fill every field. Save when finished, return to Home, and confirm that the new entry appears in the list.

If the existing details are provided as a QR code, choose Scan QR Code from the add menu. Before scanning, confirm that the QR code actually contains the server details. Camera access is managed by the system; if permission has not been granted, follow the system prompt to allow access. If you do not want to use the camera, return to Add Server and enter the details manually. Whichever method you use, check after saving that the server type, address, and port match the original details.

Method 2: Import a subscription with Subscribe

If you have your own subscription URL, choose Subscribe from the add-type menu. Give the subscription a recognizable label, then paste the complete URL into the URL field. The URL may contain parameters that identify your account, so keep it only on your own devices. Save it, return to Home, and run an update. After the client successfully reads the content, the subscription's server entries will appear in the list.

Saving a subscription record does not mean its contents have been updated. If Home shows the subscription name but no server entries, update that subscription first and check for an error message. If the update fails, do not add several identical records in succession; this creates duplicates and makes it harder to tell which entry is active. Keep one record, check that the URL is complete at both ends, and confirm that the current Wi-Fi or cellular network can reach the subscription address.

After importing, select a server entry in Home for testing. A selected entry only means it is prepared for the next connection; the system connection has not been established yet. Do not repeatedly toggle the switch. First determine the Global Routing mode, which controls whether requests are evaluated by rules, sent through the proxy policy, or kept direct.

Global Routing

Choose a Global Routing mode

Global Routing determines the overall way traffic is handled. The three modes are Config (Config), Proxy (Proxy), and Direct (Direct). This choice is not a server protocol and does not change the address or port you entered earlier; it controls how Shadowrocket decides what to do with requests after they enter the client.

Config: evaluate requests against rules

With Config selected, requests are matched from top to bottom against the rules in the current configuration. Common rule keywords include DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, GEOIP, IP-CIDR, IP-CIDR6, and USER-AGENT. After a rule matches, the request is handled by the corresponding PROXY, DIRECT, or REJECT policy. This is suitable when you have imported and checked a rule configuration and want different requests to use different policies.

Rule order directly affects the result. For example, a narrow domain rule usually needs to appear before a broader fallback rule. Once an earlier rule matches, later rules generally do not take part in the decision. Therefore, when some content works but other content does not, check the rule-matching order before changing the server protocol. When first using an existing configuration, start with Config and verify the rule results through actual access.

Proxy: apply the current proxy policy

With Proxy selected, network requests use the currently selected proxy path more consistently. This mode is useful for a short comparison test: if a request fails under Config but works under Proxy, continue by checking whether the rules assigned it an unexpected policy. Proxy is not a fix button and should not replace rule diagnosis; after the comparison, decide whether Config better fits your purpose.

Direct: bypass the current proxy path

With Direct selected, requests use a direct connection. This can help determine whether the problem occurs only on the proxy path. For example, if the same page works under Direct but fails under Proxy, focus on server reachability, parameters, or the connection path. If it also fails under Direct, check the local network, the target service, or other system network conditions.

When following this guide for the first time, remember this simple order: use Config for everyday use with an existing rule configuration; switch briefly to Proxy when checking whether rules cause a difference; switch to Direct when checking whether the local network works normally. After each switch, repeat the same test. Do not change the server, network, and Global Routing at the same time, or you will not know which change affected the result.

Home · System connection authorization

Turn on the switch and establish the connection

Return to Home and confirm again that the selected server entry and the Global Routing mode match your previous choices. Then turn on the connection switch at the top of the page. The first time you establish a connection on the device, the system asks you to confirm adding a VPN configuration; this is the system authorization flow Apple provides for network extensions. Follow the system dialog and use the device passcode, Touch ID, or Face ID as requested.

System authorization usually appears only when a configuration is added for the first time or when the system requests confirmation again. After authorization, Shadowrocket attempts to establish the connection. Wait for the status to settle instead of toggling the switch repeatedly. Establishing a connection involves server resolution, a network handshake, and protocol negotiation; on a poor network, this may take longer than usual. If the switch immediately turns off, the connection has not stayed active, so continue with the layered checks in step five.

On iPhone or iPad, the system status area may show a VPN indicator, but that indicator only means the system connection configuration is enabled; it does not by itself prove that every request is reaching its destination as expected. In Config mode especially, different requests may be handled by different rules. First confirm that the switch stays on, then use Connectivity Test and actual access results in the next step.

If the device has saved multiple VPN configurations, the connection status shown in System Settings may be affected by another configuration. During this guide, make sure the current test uses Shadowrocket and avoid changing other network configurations at the same time. If On Demand is enabled, remember that On Demand decides when to establish a connection based on preset network conditions, so the manual switch may behave according to those rules. For initial troubleshooting, review the existing On Demand conditions before deciding whether to temporarily disable automatic triggering.

On iPad, a landscape layout may show the server list and details area at the same time. iPhone usually uses a layered page layout, but the logic is the same: select an entry in Home, choose Global Routing, turn on the connection switch, and respond to the system authorization prompt. System requirements for Apple platforms and compatibility information for Mac, Apple TV, and Apple Vision are as listed on the App Store page; this guide focuses on iPhone and iPad operations.

Connectivity Test · Data

Verify that the connection works as expected

Once the connection switch is stable, use Connectivity Test to check the basic reachability of the selected server entry. The result indicates whether the client can complete the necessary communication with the server under the current network conditions. If the test times out immediately, first check the server status, address, port, protocol parameters, and local network. If the test completes but actual content still behaves unexpectedly, continue by checking Global Routing, rule matching, and DNS.

A latency number reflects the response time under one set of test conditions; it does not fully represent real-world performance. Actual access is also affected by server load, path fluctuations, protocol characteristics, target-service responses, and Wi-Fi or cellular quality. Do not switch repeatedly just because two entries differ by a small latency amount. Choose an entry with stable test results, then perform repeated access tests for the same target content.

Next, open the webpage or app content you actually need to verify. Choose a familiar target that is working normally and can be accessed repeatedly; load it once, wait briefly, and try again. With Config, remember that different domains may match different rules: one successful target does not prove that every rule is correct, and one failed target does not prove that the server is entirely unavailable. You can temporarily compare Config, Proxy, and Direct, but change only Global Routing each time.

Traffic changes in Data can provide a useful secondary signal: upload and download activity during the connection shows that requests are being processed. However, traffic counters alone do not prove success, because background requests, system services, or other apps may also generate data. Judge the result using all three indicators: whether the switch stays on, whether Connectivity Test completes, and whether the actual target responds normally under the current routing mode.

If the result is abnormal under Config but the same target works under Proxy, return to Config and inspect the rules. Rules are generally matched in configuration order, and DOMAIN, DOMAIN-SUFFIX, GEOIP, and IP-CIDR cover different scopes; a broad rule near the top may take over the request early. Also confirm that the final fallback policy is what you expect. Do not add many temporary rules at once. Start with one clearly scoped rule, verify it, and then organize the order step by step.

If both Proxy and Config fail while Direct works, the focus is usually the current server path or its parameters. If all three modes fail, turn off the connection first and check whether the local network can access basic content normally, then reopen Shadowrocket and test again. If the problem occurs only on one Wi-Fi network and disappears on cellular, check that Wi-Fi network's DNS, router restrictions, or network authentication status.

Check each layer from input to network

Common failures and the recommended check order

When a connection fails, do not rebuild the subscription, change the protocol, switch Global Routing, and adjust DNS at the same time. If several variables change together, even a temporary recovery will not reveal the real cause. A more effective approach is to check each layer in this order: input details → subscription update → server reachability → system connection → rule handling → local network. Change one condition at a time and repeat the same test.

1. No selectable server entry in Home

Return to step one and check whether the entry was saved. For manual setup, confirm that the Add Server page was saved rather than simply closed; also confirm that the protocol type, address, and port are present. With Subscribe, confirm that you ran an update after saving. If the subscription update failed, check that the URL was copied completely from beginning to end, contains no spaces or line breaks, and is reachable from the current network.

2. Connectivity Test keeps timing out

First confirm that the selected entry is the one you just checked, then verify the server address, port, and protocol type. Manual entry commonly fails because of an incorrect port, spaces around the address, missing authentication characters, or inconsistent protocol parameters. For imported subscription entries, update the subscription first and confirm that you are using its current contents. Then compare Wi-Fi and cellular once to distinguish a server-path issue from a local-network issue.

3. The switch will not stay on

Confirm that system authorization is complete and check whether the device is waiting for a system prompt. Turn off the switch, wait briefly, and turn it on once more; do not tap it repeatedly. If the device's network settings have changed significantly recently, reconnect to the current Wi-Fi and confirm that the basic network works before testing again. If it still will not stay on, record the switch behavior, network, and server type, then open the troubleshooting guide and continue with the “switch will not turn on” section.

4. Content is unreachable after the connection turns on

Use Direct first to verify the local network, then Proxy to verify the current server path, and finally return to Config to inspect the rules. If Direct also fails, stop changing server parameters and address the local network first. If Proxy works but Config does not, check the order of DOMAIN-SUFFIX, GEOIP, IP-CIDR, and the final fallback policy. If Config and Proxy fail while Direct works, focus on the server details and Connectivity Test.

5. Only some domains or app content behave unexpectedly

This usually calls for checking rule matching and DNS rather than importing every server again. Record the affected domain first and see whether an earlier rule assigns it to DIRECT, PROXY, or REJECT. If the rules appear correct, check whether DNS resolution is stable. Do not use an overly broad DOMAIN-KEYWORD rule to cover many unrelated domains, and do not place FINAL before specific rules.

6. Duplicate entries appear after a subscription update

First check whether Home contains multiple identical Subscribe records. Each record may generate its own server list, so adding the same URL repeatedly creates duplicate entries. Keep one record with a clear source that updates normally. Before deleting anything, verify its label so you do not remove a record still in use. After cleanup, run one update and check whether the list is clear again.

7. The connection is slow but does not fail

Assess speed issues layer by layer. First repeat the test with the same server, network, and Global Routing mode to rule out a short-term fluctuation. Then switch between Wi-Fi and cellular to assess the local-network impact. Only after that should you compare other server entries in your existing list. Protocol characteristics, server load, and target-service responses all affect performance; latency from a single Connectivity Test is not the same as sustained transfer performance. For a fuller layered method, read the Shadowrocket troubleshooting guide.

Basic status after setup

Home contains a server entry with a clear source and complete parameters.
You know whether the current Global Routing mode is Config, Proxy, or Direct.
The connection switch stays on and system authorization is complete.
You have completed at least one Connectivity Test and one actual access test.
When a problem occurs, you can change one condition at a time and keep a record of the test.

After completing these items, the basic Shadowrocket connection workflow is established. When adjusting custom rules, DNS, On Demand, or a complex configuration later, preserve the currently working baseline, then change and verify one item at a time.

Shadowrocket Step-by-Step Setup Guide