Shadowrocket Setup Guide
Existing configuration → Choose a mode → Connect and verify
This guide covers only the essential steps for your first connection. First connect using an existing server configuration, then work on rules and automatic connection settings. Avoid changing several settings at once.
These steps cover iPhone and iPad. Screenshots help identify screens and fields; your list may look different. The fields required under Add Server vary by protocol, so follow the selected Type and your own configuration details.
- First, confirm your configuration is complete
- Then check the connection status
- Change one setting at a time
Add Server: Add a server or import a subscription
Choose one method based on the information you have. There’s no need to import the same details twice.
Open Shadowrocket and go to Home. Under SERVER, tap Add Server or use the add option on the screen. Start by checking Type, which determines what the following fields mean. If you have details for a single server, select the protocol specified in those details. For a subscription link, choose Subscribe. Don’t guess the protocol based on how an address looks, and don’t split a subscription link across Host and Port.
Enter server details manually
In Add Server, select the Type that matches your details, then enter Host, Port, and any other required fields. Host is usually the server’s domain or address, and Port is its port number. Enter Password, Method, and other fields only when required by the selected protocol. Authentication differs between protocols, so don’t apply one protocol’s setup to another. Set optional items such as TLS and transport options only according to the details you have; don’t switch them at random to test the connection.
Check that copied details don’t contain extra spaces, line breaks, or non-English punctuation. Make sure the port and authentication details are complete. You can add a label to identify the entry, then save and return to Home to confirm it appears under SERVER. A label helps you tell configurations apart, but changing it does not change the server settings.
Import an existing subscription link
Under Type in Add Server, choose Subscribe, paste your full subscription link into the URL field, then save and wait for the result. A subscription link may contain information that grants access to a service, so copy it in full from the original source. Don’t omit anything after the question mark or paste accompanying chat text. Saving the subscription and retrieving its server list are separate steps. Return to Home and check that selectable entries appear under SERVER.
If you have a QR code, use Scan QR Code if that matches the format you were given. Import from Cloud JSON is for a specific import format; it does not work with every subscription link. Choose the option that matches your details. If you’re unsure of the format, check with your service provider. Avoid importing the same content repeatedly through different options, as this can make selection and troubleshooting confusing.
If the list is still empty, check that the link is complete, your current network can retrieve it, and your service is active. Don’t edit rules yet; rules can’t add servers that haven’t been imported. Once entries appear, keep them as they are and move on to Global Routing. For more help, see the FAQ on importing subscriptions and server entries.
Step complete when: You can identify a server entry under SERVER on Home—not just a saved subscription.
Global Routing: Choose a routing mode
The three modes determine how routing strategies are selected. They don’t replace server details or fix incorrect settings.
Return to Home and open Global Routing. The three modes are Config, Proxy, and Direct. First decide whether you’re testing the selected server or routing traffic according to existing rules. After choosing a mode, return to Home and check the displayed Global Routing value to confirm it changed.
Config: Use the rules in the current configuration
Config uses rules in the current configuration to decide how connections are routed. The server list from a subscription and the configuration in Config serve different purposes: the former provides connection options, while the latter determines how traffic is handled. An imported subscription does not mean routing rules are ready. Before using Config, open Config to confirm which configuration is active, then review the rules and their order under Rule.
The official screenshot on the right shows the configuration editor, including General, Rule, Hosts, URL Rewrite, HTTPS Decryption, and Add Rule. You don’t need to edit each section to connect for the first time. In particular, don’t enable or change an advanced option just because it’s there. Start with a configuration you understand and trust, and leave rule changes until after you’ve verified the connection.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,DIRECTFor understanding rule syntax only: match by domain suffix or IP range, and use FINAL for traffic that doesn’t match. Don’t replace your entire configuration with this example.
Proxy and Direct: Know what you’re testing
Proxy routes connections through the proxy and can simplify initial troubleshooting by reducing variables from rule matching. It still requires a working server configuration; switching to Proxy won’t fix an incorrect Host, authentication details, or inactive service. Once the test passes, switch back to Config and verify access again if you want to route traffic by rule day to day.
Direct uses a direct connection and is useful for checking whether your basic network access works. It does not prove that a proxy server is working. If a page opens in Direct, that only confirms the direct connection worked in that instance. To test an existing server, start with Proxy, then check rule-based routing in Config.
For more on rule order, policy references, or DNS, continue to the complete manual. This guide uses one clear test mode at a time; avoid changing several settings during your first connection.
Step complete when: You can confirm the current mode on Home and know whether you’re testing the server connection or rule-based routing.
Home: Select a server and connect
Select a server under SERVER, turn on the switch at the top, then check that the connection stays on.
Return to Home and find the server you want to test under SERVER. Tap the circle beside its entry to select it as the current default server. Selecting a server is different from opening it for editing; you only need to choose which one to use. If several entries have similar labels, check their subscription group or server details to avoid testing the wrong one.
Check that Global Routing still matches your test goal, then turn on the connection switch at the top of Home. When disconnected, the status may show Not Connected. The first time you connect, the system may ask to add a VPN configuration. Confirm that the app name in the prompt matches the action you started, then follow the system steps. You may also need to authenticate on your device. This grants permission to create a system VPN configuration; it is not a screen for entering server credentials.
If you cancel the permission prompt, the connection may not complete. Return to Shadowrocket and start the connection again, then follow the system prompts. If your device is managed by an organization or has system restrictions, check which configurations are allowed instead of repeatedly changing the server password.
After granting permission, return to Home and check whether the status at the top changes from Not Connected to connected and the switch stays on. The system’s VPN status can help confirm that a tunnel was established, but you still need to test access. A connected status means the connection process completed; it doesn’t guarantee access to every destination or confirm that every rule in Config works as expected.
On iPad, check the selected server and Global Routing before handling system permissions. Even if you’ve used Shadowrocket on another device, confirm permissions and configuration details on this device too. For the next step, keep the same server and mode, then run Connectivity Test and try accessing a site so the results correspond to the same settings.
Step complete when: The selected server is clear, the connection switch stays on, and Home no longer shows Not Connected.
Connectivity Test: Check that the connection works
Consider the test result, actual access, and current mode together. One successful check isn’t enough to verify everything.
On Home, tap Connectivity Test and wait for the test to finish. Check the result for the selected server. The test shows connectivity under the current test conditions; a result does not guarantee that every app, domain, or connection method will work. A timeout alone does not prove that the server details are wrong. The test method, current network, and destination response can all affect the result, so compare it with actual access.
Next, open a browser and visit a site you know and are authorized to access. Check that the page loads fully, rather than relying on a cached title or image. Keep the server, Global Routing mode, and network unchanged, and refresh if needed. If you change networks, DNS, and servers at the same time, it’s hard to tell which change made a difference.
Then open Data and check whether traffic changes as expected during use. Data can help you understand usage, but a cumulative total does not prove that a particular page used the proxy. In Config, some requests may use DIRECT and others PROXY. Even if a page loads, check the rules to see whether it used the route you expected.
If you used Proxy temporarily to test the server, switch back to Config and test again after confirming that access works. If the same server works in Proxy but not in Config, check the active configuration and Rule before importing the subscription again. Likewise, access in Direct does not prove that the proxy connection works; assess each path separately.
After testing, note the settings that worked: selected server, current mode, active configuration, and network. If a problem comes up later, compare against these settings; that’s more useful than repeatedly toggling the connection. For more on traffic and rules, see the complete manual’s sections on connections and Data.
Step complete when: Actual access works as expected, and you can tell whether traffic is using Proxy, Direct, or rules in Config.
Settings: Troubleshoot by where the failure occurs
Identify the step that failed before deciding which screen to check.
When something goes wrong, note what happened: the list is empty, the switch won’t stay on, the test times out, or only one site fails. Each points to a different part of the setup and needs a different approach. Check the steps below in order, retrying after each one with the original settings. Keep unchanged details for comparison.
Empty list: Check the import step
First, confirm the device has a working network. Then check the full URL in Subscribe and the retrieval result. A truncated link, a change in service status, or an unparseable subscription can leave the list empty. When contacting your service provider, describe the import result and where it occurred; don’t share your full subscription link. Changing Global Routing or Rule won’t help if no servers are available to select.
Switch won’t stay on: Check permissions and server selection
Confirm that a server is selected under SERVER and that the system’s VPN configuration setup is complete. Also check for device management restrictions or another active VPN connection. Follow the system prompts to resolve the current connection state before trying again; don’t delete all your configurations. If the issue only occurs after changing networks, try again on the original network to see whether the network is involved.
Connected but can’t access sites: Check settings and rules separately
Recheck Type, Host, Port, authentication details, and any other required settings against your source information. Don’t rely on memory. Then check Global Routing. If you were using Config, try Proxy temporarily for comparison. If only Config fails, check the active configuration, rule order, and policy for the destination. If only some domains fail, include DNS and rule matching in your checks rather than switching every option.
Test and access results differ: Check the diagnostic conditions
In Settings, check the current option under Test Method. Different test methods examine different conditions, so don’t assume one result applies to all access. To investigate further, use Diagnostics and review the items it provides. Before saving or sharing diagnostic information, hide your subscription link, credentials, and any browsing records you don’t want to disclose.
During initial troubleshooting, keep the connection manual. On Demand triggers connections based on conditions and is best configured after manual connections are stable. If the switch behaves differently from manual operation, check whether On Demand is enabled. You don’t need to change every setting under Proxy, TCP, or UDP to test connectivity. Keep existing settings and adjust only those directly related to the issue.
After troubleshooting, restore your usual routing mode if you changed it temporarily, then test access again. If the issue remains, look for a matching symptom in the FAQ. For rules, DNS, and ongoing maintenance, see the complete manual. When describing a problem, include the failed step, current mode, and checks you’ve already performed; this is more useful than simply saying “it won’t connect.”
Step complete when: You’ve narrowed the issue down to importing, permissions, server settings, or rules, and have a repeatable way to test it.
