Shadowrocket Getting Started Guide
Using the iPhone / iPad interface, import your details, choose routing, connect, and verify the setup. Complete the manual connection steps before adjusting automatic settings.
The steps below check separately whether your details were imported, whether the server can connect, and whether requests are handled according to the rules. Avoid changing DNS, rules, and On Demand all at once. Even if the issue is resolved, you would not know which change helped. Use the protocol type and parameters that match your own details. Fields vary by type, so do not fill them in just to match an example.
01 · Add Server: Add a server or import a subscription
Open Shadowrocket and go to Home. First, identify whether you have a subscription link or parameters for a single server. A subscription link is usually used to retrieve and update a group of servers; a single server has a specific address, port, protocol, and authentication details. These are entered differently. Do not enter a subscription link as a server address or treat shared details for one server as a subscription update URL.
Have a subscription link? Choose Subscribe
On Home, tap the add button in the upper-right corner to open Add Server, then open Type and choose Subscribe. Paste your complete subscription link into URL, add a note to help identify it if needed, and save. Before and after pasting, check that a messaging app has not truncated the link, that there are no extra spaces at either end, and that all query parameters are present. Subscription links may contain access credentials. Do not post them in public comments or put them in publicly accessible notes.
After saving, return to Home and wait for the subscription content to load. Check whether server entries appear under the subscription group. If you see the group name but no entries, first check whether it is still loading, then update that subscription. If the update reports an error, keep the error message and confirm that the device's current network can access the subscription URL. Repeatedly deleting and re-adding the same link usually will not fix an expired link or content that cannot be parsed.
Have details for a single server? Fill in the matching Type
If you have manual parameters, choose the Type that matches your details in Add Server, then enter Address, Port, and the authentication fields required by that protocol. Shadowsocks, VMess, VLESS, Trojan, and other protocols require different parameters; do not guess based only on a port or name. Keep TLS, server name, and transport parameters consistent with the original details. The Address and the name used for TLS are not necessarily the same value.
After saving, return to Home, tap the server you want to use, and confirm that the selection marker is on the intended entry. A successful import only means the app has read the details; it does not guarantee that the remote service is available. Do not adjust advanced parameters yet. Continue to the next step and choose Global Routing. If you are unsure what a protocol field means, see the protocol reference. Do not troubleshoot by changing the protocol type.
02 · Global Routing: Choose a routing mode
Open Global Routing from Home. This setting determines how connections are handled; it does not change the server address or password. The three modes are Config, Proxy, and Direct. Understand their purposes, then choose the one that matches your current test. An enabled connection switch does not mean that every request goes through a proxy.
Config: Apply the rules in the active configuration
Choose Config for everyday use with an existing routing configuration. Then open Config and confirm that the expected file is active, rather than merely added to the list. Rules in a configuration are generally matched from top to bottom, and the matching rule determines the policy. If a rule sends a destination to DIRECT, direct access is expected. If a rule specifies PROXY, also confirm that the correct server is selected for that policy.
The following is only an example of rule order; it is not a recommendation to replace your current configuration. The first rule sends the example domain to PROXY, the second sends the specified private IP range to DIRECT, and FINAL handles requests that did not match earlier rules. This arrangement is not suitable for every use case. When getting started, first understand the configuration you are already using.
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,DIRECT
Proxy and Direct: Use for a specific purpose or comparison
Proxy sends requests handled by the app through the proxy path. It can help you temporarily check whether an issue is related to routing rules, but it will not fix incorrect server parameters and does not mean that all system traffic on the device must use the same path. Direct uses a direct connection and is useful for checking how a destination behaves on the underlying network. It does not automatically disconnect the system's VPN configuration.
For initial setup, start with Config. If only a specific destination has an issue, temporarily switch modes to compare results, then restore the original setting after testing. Note the setting before switching; otherwise, troubleshooting could leave a configuration that does not suit your everyday needs. If the active file or rule order is still unclear, first read the routing section in the FAQ. You do not need to rewrite the entire configuration when getting started.
03 · Home: Turn on the connection and authorize it
Return to Home and check the selected server and Global Routing once more. When ready, turn on the connection switch on the page. The first time you enable it, the system displays a prompt to authorize adding a VPN configuration. Read and approve the prompt, then complete device authentication as requested. This authorizes a system network configuration; it is not a request for your server password. Enter server authentication details earlier in Add Server.
After completing the system prompt, return to Shadowrocket and check whether the switch stays on or a connection error appears. If the switch immediately turns off, note the prompt text and avoid tapping repeatedly. You can check whether the VPN configuration was created in system Settings. Behavior may differ if the device is managed by an organization, subject to system restrictions, or already using another VPN connection. First confirm that the device permits adding and enabling this configuration.
For your first verification, temporarily turn off On Demand and complete one repeatable manual connection. On Demand can trigger connections based on conditions. During manual testing, this may turn the connection back on and make it seem as though it reconnects automatically after being turned off. Once the manual process works, configure the on-demand conditions separately. Do not use automatic triggers to address a server that cannot connect.
Once the connection stays on, there is no need to keep toggling the switch. A VPN status indicator only shows that the related network configuration is connected; it does not prove that every server in a subscription or every target website is available. Check both server connectivity and actual access results to determine whether setup is complete.
04 · Connectivity Test: Verify the connection
Use Connectivity Test on Home to check server connectivity. Before testing, confirm the selected test method and repeat the same check for the same server on the same network. Different methods test different things. A returned result does not guarantee that every request to a target service will succeed; likewise, a timeout from one probe does not prove that all access is failing.
Next, open a browser and visit a service you are authorized to access and know should normally load. Do not rely on an already-loaded page; refresh it and wait for the new request to finish. Test an ordinary page first, then try the feature you actually need, such as a page that requires login or a file request. If the page body loads but images, login, or other features fail, they may use different domains and need to be checked separately.
If you use Config, check the active configuration to see which rule and policy should match the destination. One destination using DIRECT and another using PROXY may be expected. If needed, review the connection records in the app, find requests for the target domain, and check the matched rule and handling policy. Do not conclude that no rules are working just because the apparent exit address has not changed.
For a comparison, change only one thing at a time: keep the same destination and server, temporarily switch to Proxy, and try again. Then restore Config. If Proxy works but Config does not, first check the active configuration and policy selection. If both modes fail, continue checking the server and underlying network. Record the results of a Direct comparison too, to help distinguish an unavailable destination from an issue with the proxy path.
Traffic readings in Data can help confirm data activity, but the measurement scope, app cache, and background requests can all affect them. Do not treat a momentary number as the sole measure of success. After a successful check, note the working server, mode, and network environment. There is no need to keep changing settings just to get a lower test value.
05 · Common failures: Troubleshoot from the network up
When something goes wrong, first identify the layer where the failure occurs: the subscription will not load, the server test fails, the switch will not stay on, or only a specific destination cannot be reached. Classifying the issue before taking action is more useful than updating the subscription, changing DNS, and editing rules all at once. Check the following in order, from broadest to narrowest impact.
First, confirm the device itself is online
Temporarily turn off the connection switch. If On Demand is enabled, pause it as well, then check whether Wi-Fi or cellular data is working. Public Wi-Fi may require you to sign in to the network first. If the underlying network is unavailable, subscription retrieval and server tests may both fail. You can repeat the same test on another available network, but do not change server parameters at the same time or you will not be able to compare the results.
Distinguish a subscription update failure from a server connection failure
If a subscription update fails, check that the link is complete, still valid, and returning content. If needed, confirm the original details with your service provider. If the subscription updates but the server does not connect, check the specific selected entry and verify Address, Port, authentication details, TLS, and transport fields. The server list may change after an update, so confirm the selected entry again. Do not assume the selection is unchanged just because the group name is the same.
If one server keeps timing out while other existing servers work, the issue is likely isolated; resetting the entire app is not appropriate. If all entries fail, check the current network, device time, and system permissions. Test results help narrow down the cause, but do not replace checking the actual parameters and remote service status.
Handle switch problems and partial access failures separately
If the switch turns off immediately after you turn it on, first check whether system authorization is complete, whether the VPN configuration is allowed to run, and whether another network configuration is conflicting. If the switch stays on but only some destinations fail, first check Global Routing, the active file in Config, rule order, and the relevant policies. Do not start by deleting all configurations. Keep the original file before making changes so you can restore it.
If the error mentions name resolution or certificates, check DNS settings and system time. A noticeably incorrect device date can affect TLS verification. Do not disable verification to hide a certificate error. Set the time correctly, confirm fields such as the server name, and test again. For more detail on parameters, see the protocol reference. For common connection issues, see the connection troubleshooting FAQ.
The getting-started process is complete when an existing server can reach the target, routing under Config behaves as expected, and the underlying network recovers after disconnecting. You can then configure On Demand or organize multiple configurations as needed. These tasks should build on a verified manual connection; they do not all need to be completed the first time you use the app.