The Complete Shadowrocket User Guide

Understand how Home and Config work together

After first launch, distinguish three things: the servers available on Home, the rules configuration used in Config, and the main switch that starts the system connection. A server determines which remote endpoint handles requests; the rules configuration determines how requests are routed; the switch determines whether the network extension is running. These are connected, but they cannot replace one another. A server in the list does not mean the rules are suitable. A rules file does not mean the server credentials are correct. Even with the switch on, you need to check the result by accessing a real destination.

The app may request permissions only when you first use the related feature, rather than showing every prompt at launch. Read the current prompt to understand what it is for before deciding whether to continue. Camera access is generally used to scan QR codes; notification permission controls app notifications; system VPN configuration authorization allows a connection to be established. If you’re importing a text link, you don’t need to enable camera access for that task. You can grant access to features you aren’t using later, when you need them, by following the system prompts.

Understand system VPN configuration authorization

The first time you try to connect, the system will usually ask to allow a VPN configuration to be added and may ask you to authenticate on the device. This registers a network extension configuration with the system. Confirm that the request comes from the Shadowrocket app you’re using, then follow the system prompt. Successful authorization means the system allows the configuration to run. It does not mean every network request will be routed or that the server can reach every destination. How requests are handled still depends on Global Routing, the rules, and the remote service.

If you dismissed the system prompt earlier, try connecting again after checking your server details, then follow the authorization flow shown. If the configuration still cannot be established, check whether the device is managed by an organization, whether a policy restricts the relevant feature, and whether another network configuration is active. Follow your organization’s requirements on managed devices; do not treat management restrictions as an ordinary connection issue. Avoid deleting multiple system configurations as a trial-and-error step. First note which app each existing configuration belongs to and what it does, so you don’t disrupt a work network.

Assess system status and app status separately

A VPN status shown by the system means the relevant network extension is connected; it does not prove that a webpage loaded successfully. Conversely, some devices have limited space in the status bar, so the absence of an icon alone does not prove that the connection dropped. Check the switch in the app, the selected server, and the actual access result together. If you disconnect from system settings and the connection starts again automatically, check triggers such as On Demand instead of assuming the system ignored your action.

After changing the server, routing mode, or rules configuration, an existing connection may still use its previous route. For the first test, stop the current activity, reconnect if needed, and reopen the destination. Don’t leave an old session running while changing multiple settings and then judge the new configuration by whether a page is still playing. For apps that require sign-in, account for cached data and session restoration; if needed, quit the target app and open it again.

Permission checks answer, “Does the system allow this feature to run?” Connectivity checks answer, “Are the current server, authentication details, rules, and destination working?” Record these as separate checkpoints.

Set a baseline you can return to

Before importing, note whether you’re using Wi-Fi or cellular data, and confirm that the underlying network works normally. If the Wi-Fi requires a web login, complete that first. During initial setup, leave automatic triggers off so you know which manual action starts each connection. If another feature on the device can change the network route, note its status too. This helps avoid attributing the result of multiple active mechanisms to one setting.

Keep a private setup note with the current server name, configuration name, Global Routing mode, and what you changed. Do not include full passwords or subscription credentials. After your first successful connection, this note becomes your rollback baseline. If you haven’t imported any service details yet, it’s normal to stop here; add your existing information in the next section. For a shorter, step-by-step walkthrough, return to the Getting Started Guide, then come back here after authorization to review the boundaries of each setting.

Separate routing modes from rule policies

Global Routing determines how requests are handled. Config matches requests against rules in the current configuration. Proxy routes requests handled by the client through the proxy path. Direct uses a direct path. These are modes, not three different servers. Changing modes won’t fix an incorrect password or extend an existing service. In particular, Proxy should not be taken to mean that every communication from the device must pass through a remote server. System network behavior, the client’s scope, and protocol capabilities each have their own limits.

PROXY, DIRECT, and REJECT in rules are policy keywords; don’t confuse them with the Global Routing modes shown in the interface. PROXY in a rule must also be understood in the context of the current selection and policy definitions in the configuration. If the configuration uses a custom policy group, a rule may reference the group name rather than the literal word PROXY. When learning the setup, check how the existing configuration references policies. Changing only the text at the end of a rule does not necessarily change the policy as intended.

Rules are checked from top to bottom; put FINAL last

In Config mode, rules are checked from top to bottom, and the matching rule’s policy is applied. More specific exceptions generally need to appear before broader rules that could match first. Otherwise, the earlier rule wins and the exception is never reached. FINAL handles requests that did not match any earlier rule, so place it last. To troubleshoot rule order, inspect the rules from the top instead of searching only for the line you just added: an earlier rule may be taking effect.

The following is an example rule snippet for a .conf file. It illustrates structure and match order only; it is not a complete configuration or suitable for every network. example.com is a documentation domain. Adjust the example to your destination and existing policy definitions. Back up the original configuration before editing, and confirm that the modified file is selected.

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

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches the specified domain and its subdomains; DOMAIN-KEYWORD matches a keyword in a domain and may have a broader scope than expected. IP-CIDR and IP-CIDR6 match address ranges, while GEOIP uses a database to determine the region associated with an address. Domain requests also involve a resolution step before connecting to an address. Domain-rule matches and address-rule matches rely on different information, so you cannot infer the entire matching process from one address shown at the end.

Test one destination at a time; don’t change the whole configuration at once

Before editing a rule, be clear about the intended result: which destination should use which policy, and why does the current behavior fall short? Add a rule for that destination, make the request again, and check the policy shown in the available records. If nothing changes, first confirm that the configuration was saved and selected, whether an earlier rule matched, and whether an old session is still active. Don’t change DNS, the server, and a large set of rules at the same time. Even if the problem goes away, you won’t know which change made the difference.

Routing a destination to DIRECT does not guarantee it will be reachable; it still depends on local DNS resolution and network connectivity. PROXY does not guarantee that the remote server can reach it either. REJECT actively blocks the request and may affect page resources, sign-in, or app notifications. Understand a destination’s purpose before using it. Write rules to meet a clear need; more rules do not mean better rules. For detailed examples of rule order, see Custom Rule Priority and FINAL Explained.

Suggested order: keep a verified server, use Proxy to check the proxy path, then return to Config to verify routing rules. Restore your everyday mode after the temporary comparison.

If Proxy works but Config fails, check the rules, policy references, and DNS behavior related to the configuration first. If both fail, return to the server’s authentication and transport details and network reachability. This way of grouping the checks is more useful than repeatedly switching modes. Note the configuration name and Global Routing mode you end up using; the next section’s connection check depends on being able to repeat the same setup.

On-device statistics are not the remaining allowance shown by your service

Data helps you review traffic and related records within the client’s visible scope. The exact items depend on the current app interface. First check whether the statistics cover the current connection, a time period, or cumulative usage; then interpret changes in the figures. Traffic recorded by the client is not necessarily the same as the amount deducted by your service. The two may use different time windows, units, protocol overhead, or billing methods. To check the remaining allowance on an existing service, consult your own service account rather than estimating it from the client’s cumulative total.

Understand upload and download from the device’s perspective. Page requests, file transfers, and cloud sync can generate uploads; page content, video, and file downloads generate downloads. Background sync and app notifications can also use the network when you haven’t actively opened a webpage. A small, steady change in traffic is not enough on its own to indicate a problem. Consider foreground tasks, background activity, and the statistics window. In particular, check the units before confusing a transfer rate with a cumulative total.

Distinguish transfer rate, total usage, and time window

A transfer rate measures how much data changes over time; a total measures the amount used within a particular statistics window. A brief peak does not demonstrate sustained throughput, and a growing total does not mean data is still being transferred. Before comparing figures, check the units, including whether they’re bytes or bits. Different screens may display units differently. When documenting an issue, write down the complete unit shown on screen, not just a number without context.

Reconnecting, clearing records, or resetting statistics may change what you can see. Read what the current option does before using it. Don’t delete a server or subscription just to reset a number; they are different things to manage. To compare traffic for two visits, use the same destination and similar actions, note the difference between the starting and ending totals, and consider whether the browser served content from its cache. A page using less data the second time may be due to caching, not a change in network route.

Use request records to check whether rules are working as intended

If the app provides connection records, use the destination domain or address, matched rule, selected policy, and result to understand how a request was handled. First identify the request you just made, then find its record; the list may also include background tasks and traffic from other apps. A domain and an address do not always correspond one-to-one. Some connections use an address directly, while other requests may rely on a cached resolution. If the expected domain does not appear, don’t immediately assume that no network request was made.

Policy details in the records are especially useful for checking Config. First see whether the request matched a specific domain rule, an address rule, or FINAL. Then check whether the referenced policy is what you expected. If the record shows DIRECT, don’t change the server without checking first: the request may not have used it at all. If it shows REJECT, check whether the request was actively blocked. If the record doesn’t match expectations, return to Chapter 4 and check the rules from top to bottom. Confirm that the selected configuration is the same file you edited.

Traffic statistics tell you how much was observed; request records help show how a request was handled. Use both as evidence, but neither replaces checking what the destination service actually returned.

When traffic looks unusual, compare changes before and after a task

If traffic rises noticeably, pause large activities such as video playback, system updates, or cloud sync, then see whether the increase slows. Resume tasks one at a time to find what correlates with the increase. Don’t guess the source based only on a server name, and don’t treat a rising total as proof that credentials were exposed. If the total keeps increasing after you stop foreground tasks, check background app activity and available records to narrow it down. Also check whether the statistics window still includes earlier traffic.

If your service’s allowance decreases while Data on your device changes very little, consider whether another of your own devices is using the same service, whether the two statistics periods line up, and whether the service uses a different way of measuring traffic. Check those details before asking the support channel for your existing service about its usage calculations. The client usually cannot explain every detail of service-side usage. Repeatedly resetting local statistics will not resolve an account allowance issue; it changes only what your device displays, not the service’s records.

Share only the diagnostic details needed

Request records may contain visited domains, URL paths, network details, and personal identifiers. Before describing a problem to someone else, include only the details relevant to it and redact full subscription URLs, passwords, and identifying parameters. Check screenshots for sensitive entries in the background too. When you’re done, manage records you no longer need using the app’s available features. Keep records for as long as they’re useful for troubleshooting; there’s no need to accumulate all history indefinitely. For everyday maintenance, keep only reproducible conditions, key errors, and the conclusions that helped.

The goal is not to watch the numbers constantly, but to know how to interpret them: what the statistics cover, how to find a failed request, and how to distinguish what your device observed from your service account details. With that in mind, you can adjust only the Settings relevant to a real issue and avoid guesswork.

Manage app updates and subscription updates separately

App updates come through the App Store and mainly change the client itself. Subscription updates retrieve the server list for a service you already have. They are separate operations: a successful subscription update does not mean the app is up to date, and an app update does not guarantee that your service details are still valid. Keep an eye on the app’s App Store status and your own subscription status separately. There’s no need to chase unverified version claims. If you’re troubleshooting, record how to reproduce the issue before updating so you still have a point of comparison.

Follow the instructions for your existing service and your own needs when refreshing a subscription. Don’t repeatedly refresh just because one request is slow. After a refresh, check that the selected entry still exists, whether its name changed, and whether policy references in your rules are affected. If the list update fails but an existing entry still works, preserve the working setup while you troubleshoot the fetch. Keeping normal use separate from maintenance attempts can prevent a cleanup from removing all your usable details when you need a connection.

Back up the information, not just the app

App purchase records, server details, subscription links, and rules configurations are separate things. Being able to get the app again from the App Store does not mean all local content will be restored automatically. Check what your device backup actually restores. Before moving to another device, review the app’s export or backup options and confirm which configurations they include. For manually entered entries, keep the original details. A display name alone is not enough to recreate a connection.

A backup may contain passwords, subscription credentials, or other access details. Store it somewhere protected that you control. Don’t put a full configuration in a public note, shared folder, or troubleshooting discussion. Label backups with their purpose and configuration name, and keep a version you’ve verified works. Export the original configuration before making extensive rule changes. A backup is useful only if you can access and restore the information you need, so check its contents when appropriate rather than assuming the file’s existence is enough.

Restore in dependency order when moving to a new device

On the new device, first check the original purchase record and app identity in the App Store, then get the app according to the store’s terms. System requirements, universal purchase, and Family Sharing eligibility are determined by the App Store listing. Next restore your own server or subscription details, then your rules configuration, and finally check system VPN authorization. The new device may need its own permission prompts; authorization on the old device does not carry over this step. For purchase recovery checks, see Restore Previous Purchases.

After restoring, don’t immediately enable every automatic trigger and advanced option. Manually select a known entry first and verify the connection and common destinations. Once routing works in Config, re-enable On Demand. The device name, Wi-Fi environment, system settings, and app permissions may differ from the old device, so identical configurations may not trigger in exactly the same way. If something goes wrong during migration, return to the most recent verified stage instead of starting over.

Follow a consistent recovery sequence

For everyday issues, follow four steps: check the underlying network, confirm what is selected, review recent changes, and restore the known baseline. First rule out Wi-Fi authentication issues and network outages. Next check the server, configuration, and Global Routing mode. Then review whether you recently updated a subscription, edited rules, or enabled an automatic trigger. Finally, revert only the relevant change. This preserves useful evidence and avoids unrelated adjustments. Delete and rebuild only when you know what is damaged and have the details needed to restore it.

If a problem occurs on only one network, keep the configuration unchanged and compare it on another network you can use. If only one server fails, keep the other entries and check that server’s parameters. If only one destination fails, review the request records and relevant rules. For service access or allowance issues, contact the support channel for your existing service. For a purchase record issue, check your App Store account purchases. Take each issue to the relevant part of the process instead of trying to solve account problems with app settings.

Your rollback baseline should include at least the source of a working server, configuration name, Global Routing mode, necessary settings, and the steps from the last successful test. Keep credentials protected separately; don’t include them in public troubleshooting notes.

Keep brief notes instead of repeating trial and error

For each maintenance change, record only the essentials: what you changed, why, what you compared, whether it worked, and how to revert it. Don’t treat an unverified guess as a standing rule, or delete an existing backup after one brief success. When periodically removing duplicate entries and records you no longer need, first check what depends on them—especially the difference between subscription-generated and manually added entries. The goal is to reduce confusion, not simply to make the list shorter.

The complete workflow should now be clear: use the App Store to confirm the product and purchase; system authorization allows connections; your existing details provide the server; Global Routing determines how requests are handled; real access confirms the result; Data and request records provide evidence; Settings address specific needs; and maintenance keeps the setup recoverable. For a short walkthrough of the steps, use the Getting Started Guide. To review how something works, return to the relevant section in this page’s contents. There’s no need to rebuild parts of the setup that already work.