Shadowrocket · Official Guide

Shadowrocket
Features and Settings

Choose how traffic is handled before adjusting connection and diagnostic options. This guide explains what each feature does, how to use it and what to check, with everyday setup on iPhone and iPad in mind.

Global Routing
Config / Settings
Connectivity Test

For your first setup, start with the Getting Started guide. For detailed parameter explanations, see the Settings reference. Shadowrocket is a paid Apple-platform app available exclusively on the App Store. For purchase details, see how to get the app.

Global Routing

Config, Proxy and Direct modes

What it does: Global Routing determines how requests are handled overall. Config mode uses Config, Proxy mode uses Proxy, and Direct mode uses Direct. This is not a server list and does not fill in missing server credentials. Even after you select a mode, a connection still depends on your local network, the destination and the status of the selected server.

Where to find it and how to set it: In Home, find Global Routing and select a mode. For everyday rule-based routing, choose Config, then go to the Config screen and confirm the active configuration. To test a proxy connection on its own, switch temporarily to Proxy. To check whether a destination is reachable directly, switch temporarily to Direct. After switching, make a new request to the same destination; do not treat a connection established under the previous mode as a test of the new one.

Mode	How it works	When to use it	What to check
Config / `Config`	Handles requests according to the rules and policies in the active configuration.	Everyday routing by domain, address or region.	Configuration file, rule order and policy references.
Proxy / `Proxy`	Uses the proxy as the overall routing choice.	Temporarily test the selected proxy route.	Default server, credentials and protocol settings.
Direct / `Direct`	Uses direct connections as the overall routing choice.	Check the local network and direct access to the destination.	Local network, DNS and destination reachability.

Keep in mind: Direct does not turn off the connection switch, and the system VPN indicator does not prove that a particular request went through a proxy. Proxy does not mean every system connection is routed through it. To determine where a request actually went, check the request log, the matched policy and the result of a test using a new connection. When troubleshooting is complete, switch back to your usual mode.

Config / Rule

Rule types and policies

What they do: Rules link matching conditions to handling policies. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, and DOMAIN-KEYWORD checks for a keyword in the domain. Address-based conditions include IP-CIDR, IP-CIDR6 and GEOIP, used for IPv4 ranges, IPv6 ranges and IP-based region matching, respectively. GEOIP results depend on the IP database, not the language of the website.

Where to find them and how to set them: In Config, confirm which configuration is active, then edit its [Rule] section. In general, put more specific conditions first and FINAL at the end as the fallback policy when no earlier condition matches. Save a copy before editing, then retest a specific destination. Editing a different configuration that is not active will not change the rules used by the current connection.

[Rule]
DOMAIN,example.org,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,ads,REJECT
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

The example above illustrates the syntax; it is not a complete configuration for every network. PROXY sends traffic to a proxy policy, DIRECT connects directly, and REJECT denies the request. Rules can also reference policy groups defined in the configuration. The referenced name must match the definition; otherwise, fix the reference first.

Keep in mind: Rules are generally evaluated in order. Once an earlier condition matches, later rules may not be reached. Keyword matching can cover more than expected, so make rejection rules as specific as possible. Domain and IP rules match different things, and DNS results can affect address-based rules. Do not assume a destination will match based on the rule text alone. USER-AGENT relies on the corresponding field being visible in a request; it is not a universal way to classify encrypted traffic.

For a closer look at rule syntax, see Rule keywords and matching order. When troubleshooting, identify the actual destination domain, check the first matching rule, then verify its policy instead of repeatedly adding the same condition.

Home / Add Server / Subscribe

Server and subscription management

What they are: A server entry stores connection details such as the protocol, address, port and credentials. A subscription uses a link you already have to retrieve and update a set of entries. Updating a subscription changes the server list; it does not update the rule configuration, and it does not guarantee that every updated server can connect.

Where to find it and how to set it up: In Home, use the add option to open Add Server. Choose a type based on the details you have and fill in the fields. Fields differ across protocols such as Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard and Hysteria2. Enter the original connection details rather than choosing a form based on a similar-sounding name. If you have a QR code, import it with Scan QR Code, then verify the protocol and address.

To add a subscription, choose Subscribe as the type in Add Server, enter your own subscription link, save it and run an update. Return to Home, select the server you want to use and check the selection indicator. The default server and the policy group selected in a configuration may be separate settings. If your configuration uses a policy group, check which option is currently selected in that group.

Keep in mind: Subscription links may contain access credentials. Before sharing a screenshot, copying logs or sending details for help, hide the full link and any authentication information. Manual edits to subscription-generated entries may be overwritten by the next update. To keep changes, first understand how updates work and save any notes you need. If a manual update fails, check that the link is complete, the current network can reach it and the response uses a supported format.

Deleting a subscription and deleting a single server entry may affect different items; read the confirmation prompt before proceeding. Matching names do not guarantee matching settings, so check the address, port, credentials and TLS fields one by one. For refresh instructions, see Subscription updates and troubleshooting failures.

On Demand

On Demand and trigger conditions

What it does: On Demand triggers connection behavior based on network conditions you configure. It determines when to connect; Global Routing determines how requests are handled after connection. They serve different purposes. On Demand will not fix incorrect server details or an expired subscription.

Where to find it and how to set it: In Settings, find the On Demand options and configure the conditions available in your current app. Before setting them up, connect manually and use Connectivity Test to confirm the basic route works. Then adjust one type of condition at a time and test it on the Wi-Fi or cellular network where you plan to use it. For conditions tied to a specific Wi-Fi network, check the network name carefully.

Keep in mind: When automatic triggers are enabled, disconnecting manually may not keep the connection off; matching conditions can trigger it again. To pause automatic connections temporarily, check the On Demand status as well. Network transitions and system power-saving behavior can also affect when a trigger runs. Do not treat On Demand as a continuous server health check.

If the connection drops and then comes back on, note the network type at the time and check the trigger conditions before deleting the configuration. If it does not connect as expected after a network change, first confirm that a condition matches, then check that the system VPN configuration is valid and that manual connection still works.

Data

Traffic statistics and request logs

What it does: Data displays traffic and related request information recorded by the app. Use it to observe changes during a connection, identify destinations and check policies against the logs. In-app statistics have their own scope and counting rules; they should not be treated as mobile carrier billing data or usage from a remote account.

Where to find it and how to use it: Open Data and first check which statistics or logs you are viewing and what period they cover. To observe a particular action, note the current counts, open just one destination, then return and check for new entries and traffic changes. If the current screen offers filters, clearing or reset options, confirm what they affect before using them.

Keep in mind: Caching, background connections, protocol overhead and differences in what is counted can make totals differ from expectations. New traffic does not necessarily mean the requested service worked; an entry may not appear immediately if a connection was reused or logging settings affect it. To compare two tests, keep the network, destination and test action as consistent as possible.

Domains, IP addresses and timestamps in request logs can help locate a problem, but may also reveal personal browsing habits. When sharing logs, include only entries relevant to the issue. Save any troubleshooting details you need before clearing records; cleared logs cannot be used to reconstruct earlier tests.

Settings

DNS, tests and auxiliary settings

Settings brings together DNS, testing and auxiliary features. The sections below explain commonly used options by purpose rather than prescribing fixed values for every device. An active configuration may also specify related parameters; confirm which source is in effect before editing. Use the defaults and switch states shown in your current app.

DNS: distinguish resolution from connection

What it is and where to find it: DNS resolves domain names to addresses. Review related options in the DNS section of Settings and in the relevant parts of the active configuration. A domain that cannot be resolved, one that resolves to an unsuitable address and a failed proxy authentication are problems at different stages.

How to set it up and what to check: Note the current settings and check whether the active configuration specifies a DNS server or resolution behavior before changing the relevant option. During troubleshooting, use the same domain to compare results before and after the change, adjusting one factor at a time. A custom DNS address must itself be reachable; entering an address is not a substitute for testing it. For TLS-related failures, also check that the domain matches the certificate. Disabling certificate verification is not a routine DNS fix.

Test Method: test types and what the results mean

What it is and where to find it: Test Method determines how latency tests are run. Find and adjust it in Settings. Different methods measure different stages of a connection, so results for the same server should not be compared as if they were directly equivalent.

How to set it up and what to check: Choose one test method, then test the entries you want to compare. If the selected method uses a test URL, make sure that address is reachable. A successful test only confirms that the test itself completed; it does not mean every website will work, and a latency value is not a sustained download speed. To check real-world access, open the service you want to use and review the request log.

Today Widget: adding and viewing the widget

What it is and where to find it: Today Widget provides widget-based shortcuts for viewing or controlling the app. First check the widget options available in Settings, then add a supported widget in the corresponding system widget editor. Available options depend on the current system and app support.

How to set it up and what to check: Choose the information or controls you need, then return to the app after adding the widget to confirm the connection status. Widgets may refresh periodically, so their display alone does not prove a request succeeded. If the widget and app show different states, open the app to refresh and check before deciding that the connection has a problem. Widget shortcuts are still subject to system permissions and On Demand conditions.

iCloud: sync scope and recovery checks

What it is and where to find it: iCloud options support data syncing or cloud storage workflows provided by the app. In Settings, check the relevant switches and confirm the app's iCloud permissions in the system settings. Expect only the data explicitly supported by the current screen to sync.

How to set it up and what to check: Before working across devices, save a copy of the existing configuration and check the account and sync status on both devices. Sync is not a complete backup, nor does reinstalling the app guarantee that all data will be restored automatically. After recovery, check the server list, active configuration and policy selection individually. Do not rely on filenames alone to confirm that contents match; treat sensitive subscription links as private credentials.

For more detailed explanations, see the Settings reference. Avoid changing DNS, the test method and automatic connection conditions all at once; even if the issue goes away, it will be hard to tell which change helped.

Diagnostics / Connectivity Test

Diagnostic sequence and verifying results

What it does: Diagnostics, logs and Connectivity Test show status at different stages. A connection test cannot replace checks of DNS, rules and access to the actual destination. The goal of troubleshooting is to narrow the issue down to a step you can reproduce and verify.

Where to find it and how to use it: In Home, check the selected server, connection switch and Global Routing, then run Connectivity Test. For further troubleshooting, find the available Diagnostics or Log options in Settings and record a single incident if needed. Menu locations depend on the current interface. Restore the original logging settings when you are done.

Check the local network. First confirm that the network itself works and rule out Wi-Fi that requires a sign-in. Repeat the test on the same network and note whether the issue occurs consistently.
Check the server details. Compare the protocol, address, port and authentication fields with the details you already have. A subscription updating successfully does not prove that its selected server can connect; test that server separately.
Isolate routing. Temporarily compare the results for the same destination under Proxy and Config. If the former works and the latter does not, check the active configuration, matching rule and policy group selection first.
Check resolution and requests. See whether the destination resolves, which address it resolves to and which policy the request ultimately uses. If only certain destinations fail, investigate those destinations first rather than rebuilding the entire configuration.
Restore and retest. Keep changes confirmed to work, undo temporary test settings, restore your usual routing mode and On Demand conditions, then test access again.

Keep in mind: Logs may contain server addresses, credentials, subscription links and browsing records. Check each item and hide sensitive details before sharing anything; never publish full credentials as troubleshooting material. A system VPN indicator, a successful server test and a successfully loaded destination are evidence of different things and must be checked separately.