Shadowrocket Setup Guide

With a subscription link: select Subscribe

Open Home, tap the add button to open Add Server, then select Subscribe under Type. Paste the complete subscription link obtained from your service provider into the URL field, add a note to help identify it, then save. Check for spaces, line breaks, or extra text added by a messaging app. Query parameters are part of the link, so do not remove them without a reason.

After saving, wait for the subscription to load, then return to Home and check whether server entries appear in the SERVER area. An entry means the details were imported; it does not guarantee that every server can connect. Tap the entry you want to use to select it. Adding a subscription to the list without selecting a server does not complete the connection setup. If the list is empty after import, first check whether the subscription returned valid content; do not immediately change Config rules.

To refresh a subscription later, use the action menu for that subscription entry and run an update, then wait for the result. An update retrieves server details from the remote source, so entry names or parameters may change. Confirm your current selection again after updating. Subscription links often contain access credentials; when sharing a troubleshooting screenshot, hide the entire link and its authentication parameters, not just the note.

With individual server details: check Type and authentication fields

If you have the details for a single server, choose the matching protocol under Type in Add Server, then enter Host and Port. Host is the server address; do not include a port, webpage path, or complete subscription link. Enter the Port number provided by your service provider. Password, Method, and other protocol-specific fields must match the server settings. The screenshot shows fields for a specific protocol; available fields vary when you change Type, so do not try to fill in every field shown there.

For protocols such as Trojan that use TLS, also check the SNI and TLS settings provided by your service provider. Do not weaken certificate verification at random to bypass an error. If you have a QR code, use Scan QR Code to import it. For a single share link, use the corresponding import option. Import from Cloud JSON is for the relevant file format, not a general-purpose option for every link. After saving, return to Home, select the entry you added, and continue to the next step.

Common manual-entry mistakes include choosing the wrong Type, omitting a digit in Port, or copying extra characters. Check each field against the original details instead of trying different protocols one after another. For the difference between share links, Subscribe, and Config, see the terminology guide.

After adding and selecting a server, return to Home and tap Global Routing. The three basic modes are Config, Proxy, and Direct. Do not confuse the mode selector on Home with the configuration-file manager in the bottom Config tab just because both use the word Config: the former determines whether rules are applied, while the latter is used to select and edit a specific configuration.

Config: route traffic according to the current configuration

Choose Config for rule-based routing in everyday use. Then open Config, confirm that the configuration file you want to use is selected, and check its Rule section. Rules are matched in order, and the matching rule determines the policy. PROXY uses a proxy policy, DIRECT connects directly, and REJECT blocks the request. If the configuration references a policy group, also check which option is selected within that group. Having an entry in the server list does not guarantee that a rule will use it.

Here is a minimal syntax example for routing a specified domain and its subdomains through the proxy while connecting directly to everything else. It explains the relationship between rules; you do not need to replace your existing configuration with it for initial setup. example.com is a demonstration domain. In actual use, replace it with the destination you need to handle. Keep a copy of the original configuration before editing, so a successful subscription import is not followed by new issues caused by overwritten rules.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

The first rule matches example.com and its subdomains. FINAL handles requests that did not match earlier rules. If FINAL appears before a specific domain rule, that later rule cannot work as intended. The General, Rule, Hosts, URL Rewrite, and other sections shown in the screenshot serve different purposes. You do not need to edit them all to verify your first connection. For step-by-step rule editing, see the Rule reference.

Proxy and Direct: use them to isolate issues

Proxy is useful for temporarily testing the proxy path of the selected server while troubleshooting, reducing variables introduced by rule-based routing. It does not mean that all system traffic will always follow the same path under every network condition. Direct sends requests without forwarding them through a proxy server, and can show whether a destination is accessible directly on the current network. It does not prove that the server connection works.

For an initial test, try Proxy to check proxy access, then switch back to Config to verify the rules. After switching modes, make a new request and, if needed, close and reopen the test page to avoid reusing an old connection. Once the mode and Config are set, turn on the switch at the top of Home.

Return to Home. In the SERVER area, confirm that the server you just imported or entered is selected, then check the Global Routing value. If the top of the screen shows Not Connected, the current connection has not been established. Turn on the switch at the top. The first time you connect, the system will usually ask to add a VPN configuration. Allow it as prompted, then complete the password or biometric verification on your device. Do not enter your device passcode in the Password field in Add Server; they serve different purposes.

After authorization, return to Shadowrocket and wait for the status on Home to change. The system VPN configuration lets the device hand relevant network requests to the app; it does not mean that the remote server is reachable. Even if the switch stays on, verify access in the next step. If system authorization has been revoked, the app may not be able to maintain a connection. Resolve the authorization issue rather than repeatedly refreshing the subscription.

If the switch turns off again immediately, check whether another VPN connection is active, whether device management policies apply, and whether the Shadowrocket VPN configuration is disabled. For troubleshooting, stop conflicting connections first and try again. On managed devices, follow your organization’s requirements and do not attempt to bypass restrictions. If a specific error appears, note its exact text and the steps that triggered it, then address the relevant part of the process.

To disconnect normally, turn off the switch at the top of Home. If the connection later starts again automatically, review On Demand and its trigger conditions in Settings rather than deleting the server. Keep one manual connection active for now, complete the verification below, then decide whether to enable automatic connections.

Import failed: check the link and data format

If a subscription will not update or the list is empty, first confirm that you are using the subscription address, not your provider’s management page. Check that the copied content is complete, the subscription is still valid, and the current network can retrieve its contents. Some update requests depend on specific network conditions; ask your service provider for details. Do not confuse a failed subscription update with a failed server connection. If the server appears in the list but cannot be used, move on to checking its parameters and connection.

Connection failed: check the server and test method

Compare Type, Host, Port, Password, and protocol-specific fields with the original details. For TLS-related errors, check the device time and confirm that the name matches the server requirements. Do not simply loosen verification settings. In Settings, review Test Method to understand how Connectivity Test currently works. Results from different methods are not directly comparable, and a single response time does not guarantee stable performance.

If one server fails while others in the same subscription work, note the failed entry and error, then check that server’s status with your service provider. If all servers fail only on one network, first check that network’s authentication, connection conditions, and name resolution. Do not delete every entry because of one failed test; keeping them lets you compare the results.

Connected, but traffic is routed incorrectly: revisit Global Routing

Check whether Direct was selected by mistake, whether a different Config is in use, or whether an earlier rule matched the destination first. To inspect the rules, keep one clear test destination and check each rule from the specific domain rule through FINAL. DNS, URL Rewrite, HTTPS Decryption, and other settings each have specific use cases. Do not enable them all when troubleshooting an initial connection. For more on syntax and priority, see the rule reference.

Automatic connections and diagnostics: adjust these last

On Demand triggers connections under specified conditions; it does not correct invalid server details. First confirm that a manual connection works, then check the On Demand conditions and expected behavior in Settings. If the connection starts again automatically after you disconnect manually, review this setting. Proxy, TCP, UDP, and other items in Settings are more detailed network options. Leave them unchanged until you have identified the issue, so you do not introduce more variables.

To investigate further, use the relevant tools in Diagnostics and note the network type, destination, and sequence of actions when the error occurred. Diagnostic records may contain domains, server addresses, or authentication details. Review and hide sensitive information before sharing them. After troubleshooting, restore any temporary mode or test-setting changes, then repeat “connect—visit—check rules” to confirm the result. For more common scenarios, see Frequently Asked Questions. Look up unfamiliar fields in the terminology guide.