Step 1: Add a Server or Import with Subscribe

After opening Shadowrocket, go to Home. Here you can view your servers, select the one to use, and control the connection. First, identify which details you have: a subscription URL that updates a server list, or server details containing a protocol, address, port, and authentication fields. These go in different places. Don’t enter a subscription URL as a server address or paste a regular webpage URL into Subscribe.

Have a Subscription? Select Subscribe and Enter the Full URL

In Home, tap the add button in the upper-right corner to open Add Server. Under Type, select Subscribe. On the form, paste the full subscription link provided by your own service provider into the URL field. Add a note to help identify it, such as a name you’ll recognize. Before saving, check that the URL is complete from beginning to end. Don’t omit parameters after the question mark or include spaces, line breaks, or explanatory text from a chat message.

The address below shows the format of a URL only; it cannot be used to import a working server. Real subscription URLs often contain access credentials and should be treated like passwords. Don’t include them in public screenshots, group chats, or support requests.

https://example.com/sub?token=xxxx

After saving, return to Home and wait for the subscription to load. Then check whether server entries appear in the relevant group. Saving a subscription doesn’t mean the server list was successfully retrieved. If the group is still empty, check that the URL points to subscription content, that the subscription is valid, and that your local network can access it. To refresh an existing group, use its update option, then check for changes. Don’t repeatedly add the same subscription; duplicate groups can make it hard to tell which one you’re using.

Have Server Details? Enter Each Field for the Selected Protocol

If you have details for a single server, select its protocol under Type in Add Server, then fill in the corresponding fields. Authentication methods vary across protocols such as Shadowsocks, VMess, VLESS, and Trojan. Use your original server details as the source of truth; don’t guess at values for blank fields. The address field usually takes a hostname or IP, with the port entered separately. The password, UUID, encryption method, transport, and TLS settings must match the server.

For fields such as SNI, Host, or a transport path, check each value against the information you were given. These may differ from the connection address, so don’t copy the same domain into every field. Don’t weaken certificate checks just to clear an error. Once you’ve entered the details, save and return to Home to confirm the server appears, then select it. If you have a server sharing link, use the app’s link import option. You can scan a QR code with Scan QR Code; check the imported fields afterward.

At this point, you should see the subscription group and its servers in Home, or the server entry you added manually. For now, avoid renaming entries in bulk, merging groups, or setting up automatic switching. Keep one server with clear details for testing. For protocol definitions, see the Quick Reference. A subscription retrieves and updates server details; Config controls connection policies. They serve different purposes.

Step 2: Choose a Global Routing Mode

After saving a server, open Global Routing in Home. This setting determines how connections are handled. The selected server alone doesn’t determine where every request goes. The three modes are Config, Proxy, and Direct. Confirm your selection before connecting so you have a clear basis for testing.

Config: Rules in the active configuration determine which policy handles each request. Different requests may match PROXY, DIRECT, or REJECT. Selecting a server doesn’t mean every request will use it.
Proxy: Sends requests through the current proxy policy. Use it to temporarily check whether the selected server can provide access. It doesn’t replace testing how rules match.
Direct: Connects directly. Even with the connection toggle on, requests aren’t necessarily going through the selected server.

If you plan to use rules, open the Config page first. Check which configuration files are available and which one is active. Adding a file to the list isn’t enough; make sure it’s selected. Before using a configuration, understand its purpose and source. Don’t import an entire configuration you can’t assess just to get a first connection working. Policies referenced in the configuration must also match your server or policy settings. Otherwise, even correctly written rules may not produce the expected result.

For a newly imported server, note your current Global Routing mode, then temporarily switch to Proxy for a basic connectivity test. If you need rule-based routing, switch back to Config afterward and retest the target request. This separates server connectivity from rule behavior, making it easier to troubleshoot each issue on its own.

This page doesn’t cover complete rule syntax. The key idea is that Global Routing sets the mode, while rules in Config apply within that mode. To use DOMAIN-SUFFIX, IP-CIDR, or FINAL, see the Rules Manual. Start by learning how rules are matched from top to bottom, then edit your configuration. Keep a copy of the original before making changes, and avoid changing the server, rules, and DNS all at once during your first test.

Step 3: Turn on the Connection in Home

Return to Home and check the selected server and the Global Routing mode you chose. A subscription may contain several similarly named entries. Select the one you want to test before turning on the connection. If your configuration uses policy-based selection, also check which target the policy points to; don’t rely on the server name in the list alone.

The first time you connect, your iPhone or iPad may show a system prompt to add a VPN configuration. This is the authorization needed for the app to establish a connection through iOS; it isn’t a subscription account sign-in page. Confirm that the prompt is for Shadowrocket, then allow it as requested and authenticate your device if needed. Authorization happens in the system interface. Don’t enter your device passcode in a server password or subscription URL field.

After authorization, return to Shadowrocket and check that the connection toggle and status remain on. If you previously canceled the authorization, turn on the connection again and follow the prompt. If device management restrictions apply, iOS won’t allow the configuration, or another VPN connection is active, check the system prompt and identify the source of the restriction. Don’t rapidly toggle the connection to try to hide the issue.

A VPN Connected status in iOS only means the connection was established; it doesn’t guarantee that the target server or every website is reachable. The status icon may appear in a different place depending on your device, so check the app and make a real request next. During your first test, keep the connection manual and leave On Demand unchanged so automatic behavior during network changes doesn’t interfere. Once the basic connection works, configure on-demand connections to suit your needs.

Step 4: Run Connectivity Test and Check Real Web Access

Once connected, use Connectivity Test in Home to check whether the server you plan to use is reachable. Make sure the test is for the current entry, not another group or an old record. The result can help narrow down the issue, but the test doesn’t work exactly like a real webpage request. A single successful test doesn’t prove all access is working, and latency alone doesn’t determine the quality of your experience.

Next, open your browser and visit a familiar webpage whose content you can verify. Refresh it and open another page on the site. A page that was already loaded may be cached, so don’t rely on it as your only test. Start with a few reliable sites, rather than opening many apps and generating extra requests. If only one site fails, keep the results from other sites in mind; don’t assume the entire connection is down.

In Config mode, also check whether the request used the expected policy. Return to Shadowrocket and open Data to review available connection records. Compare the request domain, time, and any policy details shown. Make a specific request first, then check its record. This is easier than trying to identify it among a large number of background requests. The available record fields depend on the current app interface.

If a request matches DIRECT, a webpage loading doesn’t prove the proxy server works. If it matches REJECT, a failed page doesn’t by itself mean the server details are wrong. To test the proxy itself, temporarily switch to Proxy and retest the same target, then restore the original mode. If it works in Proxy but not Config, check the configuration and rules first instead of repeatedly importing the subscription.

Finish with a repeatable test: check your local network with the connection off, then turn it back on and test the same server, mode, and webpage. Note any differences. Don’t rely solely on account sign-in status, content region, or a message on one page; these can also be affected by your account or cached data. This test is complete when you can state what was selected, which policy the request matched, and what happened when you tried to access the page.

Step 5: Troubleshoot One Failure at a Time

When a connection fails, first identify where it gets stuck: the subscription wasn’t imported, the server test failed, the system connection wasn’t established, or a request failed after connecting. Change one condition at a time and retest immediately. Changing the network, server, and configuration all at once makes the result difficult to interpret. Check the following items in order, from the most immediate to the least. Once you find the cause, there’s no need to change anything else.

Check Your Local Network and Subscription First

Temporarily turn off the Shadowrocket connection and use a browser to check that your local network works. Public Wi-Fi may require you to sign in first. If the results differ on another network, note the difference, then test the same server again. Don’t keep refreshing the subscription while your local network is unavailable.

If no entries appear after saving in Subscribe, check that the URL is complete, that you haven’t entered an account page URL by mistake, and that the subscription is still valid. If a list is already present but an update fails, keep the existing entries and check the update error before deleting the group. Updating a subscription retrieves server details; it doesn’t prove that every server is reachable or automatically select a different server for use.

Check Protocol Details and System Time

If Connectivity Test keeps failing, compare Type, address, port, and authentication fields one by one, then check TLS, SNI, and transport settings. Refer to your original server details rather than guessing the protocol from the server name. If problems persist after a subscription update, confirm that you’ve selected an updated entry. Don’t randomly change the port, password, or certificate settings in an attempt to fix the issue.

Check that your device’s system time is accurate. If needed, confirm the date and time settings in iOS. An incorrect time can affect certificate validity checks and some authentication flows. A timeout may also be caused by the network route to the server or the server’s status. One test alone can’t identify the cause. Retesting with the same details on another available network can help narrow it down.

If Connected, Check the Mode and Active Configuration

If the toggle stays on but webpages don’t behave as expected, check Global Routing first. Make sure the mode isn’t Direct and that you haven’t forgotten to switch back to Config after a temporary test. Then go to Config, check the active file, and see which policy the request matched. If only certain domains are affected, check the rules and domain resolution rather than resetting all settings.

If you suspect a configuration issue, keep the original file and compare it with a configuration you understand or a temporary Proxy mode test. Use the same server and target for comparison, then restore the original settings. For configuration examples, policy definitions, and rule priority, see Shadowrocket Rules and Configuration Reference. For the differences between Subscribe, Config, and Connectivity Test, see the Quick Reference.

Record the Results Before Making More Changes

If you still can’t identify the cause, note the exact steps that failed, your network type, the Global Routing mode, the test target, and any visible error message. When checking server status with your own service provider, share only what’s needed to investigate, and hide credentials in the subscription URL, passwords, and personal information. Don’t post a complete subscription link in a public support request.

Once you have a stable connection, add your own rules, subscription update routine, and On Demand settings one at a time. Keep a restorable copy of your configuration before each change and retest the same target. If an issue comes up later, retrace the steps in this guide—import, mode, connect, verify. That usually makes it easier to pinpoint what changed than deleting every entry and starting over.

Shadowrocket Setup Guide