Official Guide · Feature Reference

Shadowrocket
Features & Common Settings

Choose how traffic is handled first, then adjust rules, connection conditions, and diagnostic options.

Get Shadowrocket for iPhone and iPad from the App Store for a one-time payment of $2.99. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. See the Get the App page for all platform options. Desktop and Android installers are distributed through /dl/ on this site. Check the App Store listing for iPhone and iPad system requirements.

Start with Global Routing Then check Config and SERVER Finish with Settings

This guide uses the iPhone and iPad interface labels to show where to find each option. Menus, system integrations, and available settings may differ on other platforms; follow the options shown in your installed version. The steps cover using subscription or server details you already have. No servers or subscriptions are provided, sold, or recommended. A one-time client purchase does not include a network service plan.

01 · Modes

Global Routing: Config, Proxy, and Direct

Global Routing determines how the client handles connections sent through the tunnel. Find Global Routing on Home and choose Config, Proxy, or Direct for your needs. This is not a server protocol setting or a connection toggle. After choosing a mode, check the selected server and connection status on Home.

Interface label / meaning	How it works	When to use it	What to check first
Config / configuration	Applies the policies defined by the active configuration's rules.	When traffic needs to be routed through a proxy, connected directly, or rejected.	The selected configuration file, rule order, and final rule.
Proxy / proxy	Typically sends traffic entering the tunnel through the current proxy.	For a quick check that a server can establish a connection.	The selected server, authentication details, and availability of the destination service.
Direct / direct connection	Typically connects traffic entering the tunnel directly to its destination.	To check whether the issue is related to the proxy route.	The local network, DNS, and the destination website's status.

For everyday rule-based routing, select Config, then open Config to confirm which file is active. To narrow down an issue, briefly switch to Proxy or Direct and test the same destination, then restore the original mode. Changing modes affects traffic handling; it does not fix an incorrect address, password, or certificate setting.

02 · Routing

Rule Types and PROXY / DIRECT / REJECT

A rule consists of a match condition and an action. Open the active configuration in Config to review the rule list or edit its contents. For rules to control routing, Global Routing on Home must be set to Config. Rules are generally evaluated in order, so place more specific conditions before broader ones. Use FINAL to handle remaining connections.

PROXY sends traffic to a proxy policy in the configuration, DIRECT connects directly, and REJECT blocks the connection. Policy names must be recognized by the active configuration. If the file references a custom policy group, make sure the group is defined and a usable option is selected. Renaming a policy at the end of a rule is not enough if the referenced policy does not exist.

The snippet on the right illustrates syntax only; it is not a complete configuration and does not represent a real service. Back up the current file before editing. Change one rule at a time, save it, confirm the active configuration, and then start a new connection. This makes it easier to identify the cause if something goes wrong.

See Quick Reference for rule keywords and the Protocol Guide for differences between protocol fields.

Rule · Policy

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

Rule keyword	What it matches	Notes
`DOMAIN`	An exact domain name.	The domain only, without a scheme or URL path.
`DOMAIN-SUFFIX`	A domain and its subdomains.	Useful for matching traffic by domain.
`DOMAIN-KEYWORD`	A keyword in a domain name.	Matches a broad range; check for unintended matches.
`IP-CIDR / IP-CIDR6`	IPv4 or IPv6 address ranges.	Check the address family and network prefix length.
`GEOIP`	A region in an IP geolocation database.	Results depend on the database and the address actually resolved.
`USER-AGENT`	A readable User-Agent request field.	Not available on every connection; it is not a general-purpose way to identify apps.
`FINAL`	Connections that have not matched an earlier rule.	Usually placed last to define the fallback action.

03 · Managing server details

Subscribe and Add Server

A server entry stores the protocol, address, port, and authentication details for a single connection. A subscription retrieves and updates multiple entries. Both require information you already have. Subscriptions and Config are separate: after importing a server list, confirm the active rule configuration and Global Routing mode separately.

Subscribe: Import an Existing Subscription

Open the add menu on Home, choose the appropriate type, then select Subscribe and enter a subscription URL you already have. Save it and update the list. Check that the update succeeds, then review the returned entries. Similar names do not mean the settings are identical, so check which group each entry belongs to before selecting it.

An update may replace entries generated by a subscription, so avoid relying on those entries to retain manual changes. If an update fails, check that the URL is complete and has not expired, and that the current network can reach it. Repeatedly deleting all configurations is not a good troubleshooting method.

Add Server: Enter a Single Server

Open Add Server on Home. Choose the protocol type based on the details you have, then enter the server address, port, and authentication fields. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different fields; do not guess the protocol from the address format alone.

When using Scan QR Code, check the protocol and key fields after importing. Save the entry, select it in the SERVER list, and run Connectivity Test before trying a real request. A successful test only confirms the result under the conditions used for that test.

04 · Connection conditions

On Demand: Connect When Conditions Are Met

On Demand lets the system establish or restore a VPN connection when specified conditions are met. It answers “when to connect,” while Global Routing determines “how to handle traffic after connecting.” They serve different purposes: enabling On Demand does not select a suitable server or replace the rules in Config.

Where to Set It and How to Test

Find On Demand in Settings and review the network conditions and connection behavior available in your version. First confirm that the server works with a manual connection, then enable On Demand. If options for Wi-Fi, cellular, or specific network conditions are available, configure only the ones you need; there is no need to enable everything.

After saving, switch to the relevant network and check the connection status on Home, then verify access with a new request. Note the current network and trigger conditions during testing so a brief system network reconnection is not mistaken for a rule-routing issue.

Pausing the Connection

When On Demand is enabled, manually disconnecting may not keep the connection off; the system may reconnect when the conditions are met again. To pause it reliably, check whether On Demand is still active, then confirm the connection status on Home.

On Demand depends on system permissions, network state, and the active configuration. Switching networks frequently may briefly interrupt the tunnel while it reconnects. Start by simplifying the trigger conditions and testing them one at a time, rather than changing DNS, server details, and rules simultaneously.

05 · Usage

Data: Usage Statistics and Connection Activity

Data shows the traffic usage recorded by the client and connection details available in your version. First check whether the figures cover the current session, a cumulative total, or a specific time period. Then compare changes in upload and download totals. If the interface offers a reset option, note the current figures and reset time so you can make meaningful comparisons later.

To troubleshoot, pause other transfers and note the current figures. Visit a destination and check whether new traffic is recorded. If connection details are available, use the domain, destination address, and matched policy to understand the route. Traffic activity only shows that data was transferred; it does not prove that a page loaded fully or that every connection used the same policy.

Client statistics may differ from records kept by the operating system, network provider, or server. Protocol overhead, the reporting period, and whether direct traffic is included can all affect the totals. Do not use Data to estimate a remote account's remaining quota or rely on a single upload figure to diagnose unusual activity. Before sharing screenshots or logs, check for browsing history and server details.

06 · Common settings

Settings: DNS, Testing, and System Integration

Before opening Settings, note the current configuration and existing values. Options can vary by platform and operating system version. The sections below explain what each feature does; you do not need to enable every switch. If the configuration file also defines similar settings, check it too, as those settings may affect the result.

DNS: Domain Name Resolution

DNS translates domain names into IP addresses needed for connections. Review DNS options in Settings and check in Config whether the active configuration defines DNS behavior. Use a resolver you know is available. Keep standard DNS, encrypted DNS, and proxy routing distinct; do not enter different address formats in the same field.

If an address is reachable but its domain name is not, check whether DNS resolution failed, whether the returned address family is reachable, and how DNS requests are routed. After changing settings, clear the cache or reconnect using the option available in your version, then send a new request. Do not disable all IPv6 or rewrite all DNS settings to address a single failed website.

Test Method: Choose a Testing Method

Test Method determines how servers in the list are tested. Find it in Settings and check whether an option tests connection establishment or a response from a specific destination. Then run Connectivity Test from Home. When comparing entries, keep the method, destination, and local network the same.

The displayed time is not a download speed and cannot predict how every website will perform. The destination's status, handshake, and moment-to-moment network conditions can all affect the result. If a method fails, verify with a real request rather than deleting an entry based on a single test.

Today Widget: Quick Access and Controls

Today Widget provides shortcuts through the system widget interface, where supported by your operating system and version. Check the relevant option in Settings, then add the widget through the system's widget management interface. Available layouts and actions depend on what the device actually displays.

For initial setup, return to Home to confirm the server, Global Routing mode, and connection permissions. Widget status may refresh with a delay. If it does not match actual connectivity, open the app to check before repeatedly toggling the shortcut. A widget also cannot replace On Demand condition settings.

iCloud: Syncing Configuration

iCloud can sync supported configuration content between compatible devices. Check the cloud options in Settings or configuration management to see what can be synced, and verify your system's iCloud permissions and sign-in status. Sync coverage depends on the current interface; do not assume it includes every server entry, statistic, or connection status.

Back up your local configuration before enabling sync, and avoid editing the same configuration on multiple devices at once. If changes conflict, compare the files before choosing which version to keep so you do not overwrite rules still in use. Configurations may contain subscription URLs and authentication details; decide whether to sync based on your account and device access controls.

07 · Troubleshooting

Diagnostics: Narrow Down the Cause with Evidence

Diagnostics provides the tools available in your current version. Find it in Settings and choose a tool or logging option that fits the issue. First identify whether the failure occurs while updating a subscription, establishing a connection, resolving a domain, or accessing a destination. Not every issue is caused by server speed.

Check the local network. Temporarily disconnect the client and check whether the local network can still reach services that were previously accessible. Rule out factors such as a Wi-Fi sign-in page or a system network switch.
Check the connection details. Review the protocol, address, port, authentication, and TLS fields. Look for spaces or missing text introduced while copying. For certificate errors, check the domain, device time, and settings rather than disabling verification.
Isolate the mode from the rules. Test the same destination with Proxy and Config. If Proxy works but Config does not, check which rule matched, the policy references, and the DNS route.
Record the smallest reproducible case. Note the network type, steps, destination, and error message. Enable detailed logging only when needed, then turn it off after reproducing the issue to limit irrelevant data and privacy exposure.

Logs may contain destination domains, IP addresses, subscription URLs, or identity details. Hide sensitive information before sharing, while retaining the error type and necessary context. “It won’t connect” alone is usually not enough to distinguish DNS failures, handshake failures, and incorrect rule selection.

08 · Verification

How to Confirm a Setting Change

Follow this order: select a server on Home → confirm the file in Config → choose a mode in Global Routing → connect → send a new request → review the result in Data or Diagnostics. Change one factor at a time and keep a note of its original value. If the result gets worse, restore that value before continuing. For first-time setup, follow the steps in Quick Start.

I Imported a Subscription. Why Aren’t Rules Being Applied?

A subscription usually provides server entries, not necessarily the rule configuration you need. First confirm that Global Routing is set to Config on Home, then check the selected file, rule order, and policy references in Config. A successful import does not mean the active file has taken effect.

Connectivity Test Passes, but Websites Won’t Load. What Should I Check?

First confirm that the test and the actual request use the same server entry. Then check DNS results for the destination domain, the matched rule, and any connection errors. The test destination and a real website may use different routes, so a single response does not prove that all traffic is working.

The Connection Comes Back After I Disconnect. What Should I Change?

Check whether On Demand is enabled and review its trigger conditions. The system may reconnect when those conditions are met. To pause the connection, adjust the On Demand behavior first, then check the status on Home. Do not delete a server or configuration file as a substitute for disabling On Demand.

Can I Use Shadowrocket on Desktop and Android?

Yes. The iPhone and iPad version is a one-time $2.99 purchase on the App Store. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. See the All Platforms page for the right option. Setup steps and system integrations vary by platform; follow the interface shown on your device.