Official guide / Settings reference

Shadowrocket Features and Settings

Start in Home to check how traffic is routed, then review the rules in Config. Adjust Settings if you need automatic connections or want to troubleshoot an issue. Examples below use the iPhone / iPad interface.

Global Routing

Choose a routing mode in Home

The connection switch and routing mode are separate settings. The connection switch controls whether Shadowrocket handles traffic; Global Routing determines how that traffic is handled. Open Global Routing in Home and choose Config, Proxy, or Direct. When setting up for the first time, try Proxy to check that the server can forward traffic, then switch back to Config to test your rules.

The three Global Routing modes
Mode How traffic is routed When to use it
Config (configuration) Routes traffic according to the rules and policies in the active configuration. For everyday routing, such as sending local network services directly while routing selected requests through a proxy.
Proxy Sends all traffic handled by Shadowrocket to the currently selected proxy server. Temporarily bypass rule matching to check whether the server can forward traffic.
Direct Sends traffic handled by Shadowrocket directly to its destination, without using a proxy server. Compare with direct access on your current network.

When troubleshooting, keep the network, server, and test destination the same, and change one setting at a time. If Proxy works but Config does not, first check that the expected configuration is active, then see whether an earlier rule is matching the request. If Direct also fails, check whether your current network can reach the destination. Direct does not turn off the connection; to test without Shadowrocket handling traffic, switch off the connection in Home first.

Rule-based routing

Edit match conditions and policies in Config

Each rule consists of a match condition and a policy. In Config, check which configuration is active and keep a copy of the original so you can restore it. Then edit its Rule section. After saving, return to Home and make sure Global Routing is set to Config. Saving changes to a different configuration will not make that configuration active.

  • Match by domain: DOMAIN matches a specific hostname; DOMAIN-SUFFIX matches a domain and its subdomains; DOMAIN-KEYWORD matches a specified string in a domain. To target a single hostname, use DOMAIN to avoid unintended matches on other domains.
  • Match by address: IP-CIDR and IP-CIDR6 match IPv4 and IPv6 ranges, respectively. GEOIP matches based on the destination IP's geographic classification, not the domain suffix or the device's location. If a domain resolves to different addresses, the result of IP-based matching may change.
  • Match request attributes and set a default policy: USER-AGENT relies on an identifiable User-Agent in the request, so it is not suitable as a general condition for all connections. FINAL handles requests that have not matched an earlier rule and should be placed at the end of the rule list.

Common policies are PROXY, DIRECT, and REJECT, which route requests through a proxy, connect directly, or reject requests. Rules are usually evaluated in order, and the first match determines how a request is handled. Put specific exceptions before broader rules; otherwise, a later exception may never take effect.

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

In this example, status.example.com matches the direct rule first, while example.com and its other subdomains use the proxy. Unmatched requests go direct. This illustrates rule order; it is not a complete configuration. Test with new requests to both the exception and a regular destination. If you still have questions, use Rule syntax and match order to narrow down the issue step by step.

Subscriptions and servers

Manage the SERVER list in Home

The SERVER list stores servers you can select. Add a server manually when you already have its connection details: open Add Server in Home, choose the protocol specified by your provider, enter the relevant address, port, and authentication details, then save. Fields vary by protocol. If you encounter an unfamiliar field, check the information supplied by your provider rather than copying settings from another protocol.

A subscription imports and updates a group of servers. Get the subscription from your provider. In Add Server, choose Subscribe, enter your existing subscription URL, and save. Then return to SERVER to check that the entries appear. After renewing or changing the URL, update the relevant subscription group and check which server is selected. Older entries may have been replaced, so an entry remaining in the list does not mean the selected server is still valid.

Check these separately: whether the subscription updates, whether the server passes Connectivity Test, and whether the destination is reachable. A successful update only means the client retrieved the list; it does not mean every server in it is reachable. Passing the test also does not guarantee that your current rules route the destination's request through that server. When asking for help, include the protocol and the steps that failed, but do not share the full subscription URL, authentication details, or screenshots containing them.

On Demand

Set when connections start in Settings

On Demand controls whether the system starts a VPN connection automatically when its conditions are met. It does not replace Global Routing or switch Config to Proxy automatically. First, connect manually from Home and confirm that the system VPN configuration is authorized. Then turn on On Demand in Settings and choose the network conditions for automatic connections using the options provided.

When setting this up for the first time, test one condition at a time. For example, to check whether a connection starts when you join a particular Wi-Fi network, confirm that the network name matches the condition, then disconnect and rejoin the network. Check the connection status in Home. Add other conditions only after this works. On hotel or public Wi-Fi that requires a web sign-in, complete authentication first, then test automatic connection; connectivity can differ before and after sign-in.

If the connection starts again after you disconnect manually, first check whether the current network still meets the On Demand conditions instead of repeatedly switching off the Home control. To troubleshoot, temporarily turn off On Demand and test the same destination manually. If that also fails, check the network, server, and routing settings first. Once manual connections work, turn automatic connections back on.

Data usage

Record a baseline, then compare upload and download

Data shows traffic recorded by the client. Open Data and check the statistics scope, time range, and units before comparing uploads and downloads. To measure a single operation, note the current figures, make one controlled request that uses a small amount of data, then return to the same view and check the difference. Avoid streaming video or downloading files during the test; background activity may also be counted in the same period.

Data's reporting scope, measurement method, and time window may differ from your provider's billing, so its figures cannot be used directly to check your service balance. If the counter does not change, make sure the connection is on, the request was not served from cache, and the current view includes that connection. Before clearing statistics, check what the action affects. To compare changes, keep the previous readings and test time; these are more useful than a screenshot showing only the total.

Common Settings

Know the difference between DNS, testing, shortcuts, and sync

DNS: Check which configuration controls name resolution

DNS resolves hostnames to addresses, and a resolution issue can look like a server connection problem. If only some domains fail, first check the DNS-related settings in the active configuration in Config. If its [General] section contains dns-server, note the current value before changing it. Change one setting at a time, reconnect, and make a new request to the same domain. If local network names are resolved by your network, switching DNS without checking may prevent those names from resolving.

Test Method: Keep test conditions consistent

Test Method determines how Connectivity Test evaluates a connection. Check the current Test Method in Settings and choose one suited to your troubleshooting goal, then run Connectivity Test from Home. If the interface also lets you change the test destination, use the same one to compare results. A single timeout may be caused by the test destination or current network, while a successful test does not mean every website is reachable. To diagnose an issue with a service, also test the destination where you encountered it.

Today Widget: Check what the shortcut controls

Today Widget is a shortcut, not a separate routing mode. If Today Widget is available in Settings, check its options in the client, then see whether it can be added from the system's widget manager. After adding it, try a connection action and check the resulting status and current Global Routing in Home. If the system does not list the widget, keep using Home; there is no need to change rules or servers.

iCloud sync: Check what syncs before enabling it on multiple devices

Review the iCloud options in Settings to confirm which items can sync, and check that both devices are signed in to the same iCloud account. You can first verify syncing with a configuration change that contains no credentials, then check which configuration is actually active on the other device. Do not treat sync as a full backup or assume it copies system VPN permissions or the current connection state. Check each item after switching devices.

Diagnostics: Record issues you can reproduce

If connections repeatedly time out or drop, note when it happened, the network type, the Global Routing mode, and what was affected. If Diagnostics is available in Settings, check its information while reproducing the issue, then compare it with the connection status in Home and the Connectivity Test result. Keep conditions consistent between tests. Before sharing logs, remove server addresses, subscription URLs, authentication details, and irrelevant browsing records; include only what's needed to diagnose the issue.

Get Shadowrocket and related guides

The iPhone / iPad version is a one-time purchase of $2.99 on the App Store product page. Check the App Store listing for system requirements. The Mac versions (Apple Silicon and Intel), Windows, Android, and Linux versions are free. Find installers and first-launch guidance for each platform on the Shadowrocket download page; installers are provided on this site at /dl/.

Haven't completed your first connection yet? Start with the Getting started guide. For step-by-step help with permissions, connections, and routine maintenance, see the complete user guide. For a specific error message, check Troubleshooting.