Official Manual · Features & Settings
From Global Routing to Diagnostics, check each item in order: what it does, where to find it, how to configure it, and how to verify the result. First confirm the current mode and configuration, then adjust individual settings. This makes it easier to identify the cause if something goes wrong.
This page focuses on using Shadowrocket on iPhone and iPad. Menu locations and available options may vary; check what appears in the app. For system requirements, refer to the App Store listing. If you’re setting it up for the first time, start with the Getting Started guide, then return here to review the settings.
Global Routing determines how connections are handled overall. It is usually found under Home. Config, Proxy, and Direct are the three modes: rule-based routing, proxying, and direct connections. They are not separate sets of server details or the connection toggle itself. After choosing a mode, check the selected server, active configuration, and connection status on Home to understand how requests are actually handled.
Use Config for day-to-day routing by domain or address. Use Proxy as a temporary comparison when you want to rule out rule matching, or Direct to check whether the current network can reach a destination directly. Evaluate each mode against a specific destination; one page loading does not mean all requests followed the same route.
| Mode and interface label | How it handles requests | When to use it | Things to note |
|---|---|---|---|
| Config | Handles requests according to the rules and policies in the active configuration. | For rule-based routing or to check which rule matches a specific domain. | Make sure the configuration is enabled. Saving a file does not switch to it. |
| Proxy | Routes general requests through a proxy; actual behavior still depends on related network settings. | Temporarily compare server connectivity with rule-based routing. | This does not mean all system traffic follows the same route or that every destination is reachable. |
| Direct | Connects directly to the destination over the current network. | Check basic access over the current Wi-Fi or cellular network. | This does not turn off the connection toggle. Check On Demand behavior separately. |
In Home, open Global Routing and select the mode you need, then return and confirm the displayed value. Make a new request to the same destination and check the available connection details. Existing long-lived connections may not reflect the new setting immediately; end the test connection and try again if needed. When you’re done comparing, restore the original mode. Don’t mistake a temporary Proxy or Direct selection for active rule-based routing.
Rules determine which conditions a request matches; policies determine what happens next. In Config, first confirm which configuration is active, then review its rule order. Rules are generally checked from top to bottom. Once a request matches a rule, later rules do not override it. FINAL handles requests that did not match any preceding rule.
DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD looks for a keyword in the domain. IP-CIDR and IP-CIDR6 match their respective address ranges; GEOIP checks the region associated with an IP address. Before choosing a rule, identify whether it matches a domain or an IP address. A full URL is not a domain value.
DOMAIN-SUFFIX,example.com,PROXY
DIRECT connects without a proxy, PROXY routes the request through a proxy, and REJECT blocks it. A configuration may also refer to a policy group, whose current selection determines the final behavior. Check both the policy at the end of the rule and any group it references; the beginning of a rule alone does not tell you the request’s route.
IP-CIDR,192.168.0.0/16,DIRECT
To adjust a rule, identify the destination and check the rules that could match it. Place more specific conditions appropriately and keep a clear final handling policy. The examples above explain syntax; they are not a complete configuration. If a site behaves unexpectedly after enabling a configuration, note the matching rule and change that one item first. Don’t replace the entire configuration and change DNS at the same time. For protocol details, see the protocol reference.
A server entry stores the address, port, protocol, and authentication details needed to connect. A subscription imports and updates existing entries in bulk. These are separate from Config routing rules: having server details does not mean suitable rules are enabled, and importing a rules file does not provide a server to connect to.
In Home, tap Add Server and choose the matching type based on your existing server details, then enter each parameter. To use an existing subscription, choose the appropriate Subscribe type in the add menu, enter your subscription URL, and save. To import from a QR code, use Scan QR Code, then verify the type and key fields. Protocols require different authentication, transport, and TLS fields; don’t reuse one type’s settings for another.
After saving, return to Home and confirm the entry appears and the intended server is selected, then run Connectivity Test. An entry name is just a label, not proof that the connection works. Before editing manually, note the original values. Subscription-generated entries may be overwritten during a later update, so check how the app manages them before making changes you need to keep.
After updating an existing subscription, check that the number of entries, groups, and current selection are as expected. If an update fails, confirm the URL is complete and reachable on your current network, then check whether you need to obtain valid source details again. A successful subscription update does not mean a particular server can connect: the connection also depends on server status, protocol settings, and network conditions.
Subscription URLs, QR codes, and exported configurations may contain authentication details. Hide sensitive information in screenshots or shared troubleshooting reports, and never post a full subscription URL publicly. For step-by-step import instructions, follow the add-server steps in Getting Started.
On Demand lets the system decide whether to start a connection based on conditions you set. It controls when a connection starts; it does not replace request routing in Config. Check the On Demand section in the app for available conditions. Menu locations and condition names may vary, so follow what the app displays. Before configuring it, connect manually once to confirm system VPN authorization, server details, and basic access are all working.
If you need conditions for Wi-Fi, cellular, or a specific network, start with just a few. Save them, then check the connection status on each matching network. A test is meaningful only when the trigger conditions match the current environment; repeatedly opening and closing pages on the same network is not a substitute for testing a network change.
If the connection comes back after you turn it off manually, first check whether On Demand is triggering it again rather than repeatedly deleting the system VPN configuration. To stop the current test completely, pause On Demand, then turn off the connection and verify the system status. If it doesn’t connect automatically, first check whether the conditions match instead of immediately changing servers.
On Demand cannot fix incorrect authentication details or guarantee that all existing connections will survive a network change. Switching between Wi-Fi and cellular may require the connection to be re-established. Note the network, trigger conditions, and connection status before and after switching to tell whether the issue is with On Demand or the connection itself.
Data shows traffic statistics within the range the app can record, helping you track usage and changes. Open Data and check the displayed scope, time period, and units before comparing uploads and downloads. In-app statistics may use different accounting from the system’s cellular usage or an existing service’s billing, so they can’t tell you how much data you have left.
To check usage, note the current values, perform a clearly defined set of actions, then return to see what changed. If the page offers a reset option, check its scope and record any data you need before using it so you don’t lose your troubleshooting baseline. An increase only shows that traffic was recorded within the relevant scope. It does not prove a domain matched PROXY or that its content loaded completely.
To investigate unexpected usage, compare Data with connection details: identify when the increase occurred, then check the destination and handling policy. Background sync, media preloading, and app retries can all generate requests. Identify the activity before changing rules. Don’t judge whether a protocol uses less data based only on total usage over a period.
The sections below explain each feature. Check the available options in Settings or the relevant feature menu. Names and locations in the interface, as well as system support, depend on what appears on your device.
DNS translates domain names into addresses that can be used to connect. Successful name resolution and access to the destination service are separate steps. First check the source actually in use, either in DNS-related Settings or in the current Config’s DNS section. A configuration file may include its own DNS directives. Before changing anything, check for overlap or conflicts with other settings; changing one field does not necessarily affect every request.
Keep the original values and change only one DNS source or behavior at a time. Revisit the same destination and check resolution and connection details. If a latency test succeeds but a page won’t load, distinguish a DNS failure from a connection or TLS failure; don’t assume DNS is the cause of every issue. For IPv6, also check whether the current network supports connections to those addresses. An IPv6 address appearing by itself is not proof of a problem.
Test Method determines how Connectivity Test measures a connection. Open the relevant setting, read the description of the current method, and use the same method to compare existing servers. If it uses a test destination, keep that destination the same too. Different methods may measure a port connection or a specific request, so don’t rank their results as if they were directly comparable.
A test result does not guarantee that a page will load or indicate sustained transfer speed. Before comparing results, make sure the device is on the same network and avoid large data transfers during testing. Repeat and record a one-off failure. For a full diagnosis, also check Global Routing, the matching rule, and the destination you accessed.
Today Widget provides quick information or controls through a system widget. Check the related options in Settings, then look for the corresponding item in the system’s widget editor. Available options may vary by system and device; rely on what you see. Whether the widget appears does not determine whether the app can connect.
After setup, confirm the connection works in the app before checking the widget’s display and controls. Widgets may take time to refresh. If the status doesn’t match, check Home and the system VPN status instead of relying on the widget’s text. Also consider whether server names could be visible on the Lock Screen or a shared device.
iCloud options sync content supported by the app. First check that iCloud is available and the app has permission to access it, then review the sync scope in Shadowrocket’s settings. Syncing, importing files, and restoring everything are different operations. Don’t assume that all servers, authentication details, statistics, and system VPN permissions will move together.
Before enabling sync or restoring on another device, keep a copy of the working configuration and check whether content may be merged or overwritten. Afterward, review Config, the selected server, Global Routing, and On Demand one by one. Check system VPN authorization on the device itself. Even if synced content appears, test a connection before relying on it.
Diagnostics helps collect and review clues about connection issues. Check Settings for the diagnostic tools currently available. It serves a different purpose from Connectivity Test: a latency test provides limited connectivity information, while diagnostics can help locate the stage where a failure occurs. Before running a check, define what you’re trying to reproduce—for example, “the same domain fails under Config but works under Direct”—rather than simply noting that the connection is poor.
Note the network type, mode, test method, and error text when the issue occurs. A timeout, authentication failure, and certificate error point to different stages and require different fixes. Diagnostic output may contain domains, addresses, or authentication details; hide sensitive information before sharing the relevant parts.
Don’t weaken certificate verification just to clear an error. First check the server details, certificate name, and device time. Once the fields are confirmed, test the original destination again.
If only one destination fails, check its DNS resolution, matching rule, and service status. If all destinations fail, check the basic network and server details. This order avoids unrelated changes and helps distinguish app settings from server-side issues. For common symptoms, see Troubleshooting.
When setting things up for the first time, treat “connect manually” and “route traffic as intended” as separate tasks. The first checks your existing server details and system authorization; the second checks Global Routing and Config. Adding complex rules, automatic triggers, and multiple DNS changes before verifying a basic connection makes it harder to identify the cause of a failure.
After restoring settings, make a new test request. Existing connections, app caches, and system network changes can temporarily make behavior differ from what you expect. Keep the destination, network conditions, and observation period consistent; this makes results easier to verify than repeatedly toggling multiple settings.