Shadowrocket Setup Guide
Import an existing setup → choose Global Routing → connect for the first time → verify and troubleshoot
This guide follows the steps used on iPhone and iPad. First, connect using an existing configuration; then consider adjusting rules or setting up on-demand connections. Protocol explanations and parameter references are in the technical guide, not in the first-use steps.
Interface labels are shown in English. Menu locations may vary slightly by device, so look for the named item. This guide does not use app interface screenshots.
Add Server: Add a server or import a subscription
Open Shadowrocket and stay on Home. Don’t turn on the connection switch yet. Check which type of information you have: a subscription link used to update a server list, or a set of server details that specifies a protocol, address, port, and authentication information. These use different entry points. A subscription link cannot be entered as a server address, and a single server’s share details may not be a subscription.
Have a Subscription Link? Choose Subscribe
On Home, tap the add button in the top-right corner to open Add Server. Select Subscribe, then paste your full subscription link into the URL field. Add a name you’ll recognize and save. Check that the link has no extra spaces or line breaks, especially around the query parameters after the question mark. Those parameters may identify the subscription, and removing any part of the link can cause retrieval to fail.
After saving, return to Home and wait for the subscription to load. When successful, you should see a subscription group and its server entries. Seeing only a subscription name does not mean that a usable server has been retrieved. If the list is empty, an error appears, or nothing loads, check the retrieval result first rather than repeatedly toggling the connection switch. The network you’re using must also be able to reach the subscription URL.
Treat subscription links as sensitive information. Don’t post them in public comments or include them in screenshots. Refreshing a subscription retrieves the remote list again and may add, remove, or replace entries. Before changing a server parameter, check whether the subscription manages it; a manual edit may be overwritten on the next update.
Have Server Details? Choose the Matching Protocol
If you have a set of individual server parameters, open Add Server and select the protocol specified in your details, such as Shadowsocks, Trojan, or WireGuard. Enter the server address and port in the corresponding fields, then provide the password, identifier, or key required by that protocol. Authentication fields aren’t interchangeable between protocols; don’t choose a different protocol just because the address is the same.
If your details also specify TLS, SNI, or transport fields, enter them exactly as provided. The server address is used to establish the connection, while SNI identifies the service name during TLS; these can differ in some configurations, so don’t change them to match. If you’re unsure about a field, check the protocol technical reference instead of guessing.
After saving and returning to Home, select the intended entry in the SERVER list and confirm that the selection indicator is on the right server. Similar names don’t mean the entries use the same parameters. You can use custom names to tell them apart, but don’t include passwords in a name. The server details are now ready; next, choose how traffic should be routed.
Global Routing: Choose a routing mode
On Home, find and open Global Routing. This guide covers three basic modes: Config, Proxy, and Direct. They determine how requests are handled and are separate from whether a server has been imported. Having a server in the list doesn’t mean every request will use it.
| Mode | What it does | When to use it |
|---|---|---|
| Config | Applies the policy specified by the currently selected configuration’s rules. | You have a rules configuration ready and understand how it works. |
| Proxy | Typically sends requests through the current proxy policy. | First, check whether an existing server can handle requests. |
| Direct | Uses a direct connection policy. | Check the direct connection path or temporarily restore direct access. |
If this is your first time connecting and you don’t have a rules configuration ready, you can start with Proxy to focus the test on the current server and local network. Proxy isn’t required for ongoing use, and it doesn’t mean all system traffic will always go through a proxy. After choosing it, return to Home and confirm the selected server again so you don’t test a different entry by mistake.
Before using Config, open the Config page, confirm that the intended configuration is available, and select it. Then return to Global Routing and choose Config. The Config page is for managing configuration files; choosing Config under Global Routing means applying the configuration’s rules to traffic. The names are related, but having a file and actively using it are not the same thing.
Keep server subscriptions and rules configurations separate. Content imported through Subscribe typically maintains the server list; it doesn’t mean routing rules are ready. If your information contains only connection parameters, first test the connection with Proxy, then set up rules. If an existing configuration refers to policy names, make sure each name matches a policy that’s actually available.
Direct can be useful as a comparison during troubleshooting, but it doesn’t prove that a proxy server works. If a page loads after switching to Direct, that only confirms the direct connection succeeded for that test. For more on rule order, final policies, and scene settings, see Proxy Mode. Look up unfamiliar terms in the glossary.
Home: Turn on the connection and approve the prompt
Return to Home. Before turning on the connection switch at the top, quickly check the selected server, Global Routing, and your current network. If you’re still entering a password or editing parameters, save your changes and leave the edit screen first. For the initial test, stay on the same network. Switching between Wi-Fi and cellular while connecting makes it harder to tell what caused a failure.
When you turn on the connection, iOS may ask to add a VPN configuration the first time. This is Apple’s authorization process for setting up the corresponding network configuration. Confirm that Shadowrocket initiated the request, then follow the system prompt to allow it and complete any required device authentication. System authorization and subscription server authentication are separate; approving the system prompt doesn’t confirm that the server details are correct.
If you canceled the system prompt, you don’t need to import the server again. Return to the app, turn on the connection manually, and follow the system prompt. On a device managed by an organization, permissions may be restricted by its management policy. Check the device’s management requirements; don’t try to fix the issue by deleting management configurations you don’t recognize. Being unable to add a VPN configuration is a system-permission issue and should be investigated separately from a server timeout.
After approval, return to Home and check whether the connection stays active. If the switch turns off immediately, an error appears, or the status remains unstable, note the message and avoid toggling it repeatedly. The VPN indicator’s appearance varies by device and system. Even when it appears, it only indicates that the network configuration is connected; you still need to verify actual access in the next step.
To make the first test repeatable, leave the On Demand settings unchanged for now and complete one cycle of turning the connection on, testing access, and turning it off. If On Demand was already enabled, the connection may start again after you turn it off if its conditions are met. If that happens, check the On Demand settings before assuming the switch is malfunctioning. Adjust automatic connection conditions after you’ve verified the basic connection.
On iPad, follow the same order: confirm the selected server and routing mode, then approve the system prompt. A split view or landscape layout may move items around, but the steps remain the same. Now that the connection is established, check whether requests complete and whether they follow the selected policy.
Connectivity Test: Check that the connection works
On Home, find and run Connectivity Test, then review the result for the current server. Results depend on the test method, destination, and network at the time. A reachable result doesn’t mean every website will load, and a single timeout doesn’t mean all requests will fail. Use the test as an initial clue, not as the only basis for a conclusion.
Next, open a browser and visit an HTTPS page you know and are authorized to access. Make a new request rather than relying on a cached page: refresh it or open another page, and check whether both text and images load. If only some resources fail, distinguish that from the entire page being unavailable. Don’t immediately change all your connection parameters.
With Proxy selected, first confirm that the server you chose is still in use, then assess the connection alongside the access result. With Config selected, prepare at least two test destinations: one that your rules should send direct and one that should use a proxy. If both load, that’s only an initial check; also verify that each used the expected policy.
Check the app’s connection or request log for the test destination’s domain, matched policy, and any error details. If the interface shows the matching rule, check that too. Rules generally depend on match order and the final policy. A rule’s presence in the configuration doesn’t mean it matched this request; logs can confirm routing more reliably than simply seeing that a page loads.
Change one condition at a time during testing. For example, keep the server and destination the same and switch only the routing mode, or keep the mode and destination the same and switch only the local network. Record the results before and after so you can identify what affected the connection. Changing the server, network, and configuration all at once makes the outcome hard to interpret, even if access is restored.
To understand DOMAIN-SUFFIX, GEOIP, or FINAL, start with the rule keywords and interface terms. You don’t need to write rules when getting started. Keep a working basic configuration and add requirements one at a time to make it easier to maintain.
Common Issues: Narrow Down the Cause in Order
When something goes wrong, first identify whether the failure occurs during import, authorization, connection, or access. Don’t delete all your configurations right away or assume every failure is a server issue. Keep a recoverable copy of your current details, note the network type, routing mode, test destination, and error message, then check the following in order.
Subscription Won’t Load or the Imported List Is Empty
First check that your local network is working, then confirm that the subscription link is complete and still valid. A server may return a sign-in page, an error, or an ordinary web page; being able to open the URL doesn’t mean its content can be imported. Ask your own service provider to confirm what the link is for and whether it’s valid. Don’t share the link or remove authentication parameters. If your existing list still works, keep it so you don’t lose all your entries if the subscription can’t be retrieved again.
Server Appears, but Connection Times Out or Authentication Fails
Reopen the entry’s edit screen and compare its protocol, address, port, and authentication fields with the original details. Ports aren’t universal, and password capitalization or extra spaces can affect authentication. For configurations using TLS, check SNI, certificate verification, and the device’s date and time; an incorrect time can affect certificate validity checks. Don’t disable certificate verification as a default fix. If you’re unsure about a parameter, check the original details.
If the same configuration fails on only one local network, try another network if available, keeping the server and routing mode unchanged. The result shows a difference between those network conditions; use the error message to investigate further. If authentication keeps failing or the server refuses the connection, ask your own service provider to check the server status. Repeatedly saving the configuration in the app won’t usually fix a server-side issue.
Connected, but Websites Don’t Load as Expected
First check Global Routing. If Direct is selected, the request wasn’t handled by a proxy policy. If Config is selected, check that the intended configuration is active and review the policy matched by the request. If access works with Proxy but fails with Config, first check the rules, policy references, and related DNS settings rather than replacing all server parameters.
If all destinations fail, start by checking the basic network and server connection. If only one destination fails, check its matching rule, name resolution, and service status. If you’ve set custom DNS options, record the original values and test them one at a time; don’t add multiple configurations from unknown sources at once. For more on the relationship between domain resolution and connection paths, see the protocol parameters and technical reference. This guide keeps troubleshooting focused on the basics.
How to Keep a Troubleshooting Record
Record the symptoms and essential conditions, such as: “On Wi-Fi with Proxy selected, the page content won’t load and Connectivity Test times out.” Before sharing, hide subscription links, passwords, keys, and other authentication details. Restore the last working settings before retrying one change at a time. If you can’t determine what a change affects, stop adding more configuration.
After completing this guide, you should be able to identify what you imported, which server is selected, which routing mode is active, and how to verify a request. For routing rules, read Proxy Mode; for protocol fields, see the technical reference. Keeping connection checks separate from advanced settings makes it easier to follow the same troubleshooting steps when updating a subscription or switching devices.