Shadowrocket Official Manual

Shadowrocket Glossary

Use the English terms shown in the interface to find settings, and the fields in a rule to see how requests are handled. If you already have a subscription or server details, look up the relevant terms here. This manual does not provide, sell, or recommend them.

Interface & Controls

First, distinguish options that determine how requests are routed, controls that trigger connections, and tools for adding or testing entries.

Global Routing
Determines how requests handled by the client select an outbound route. Config follows the active configuration, Proxy uses a proxy route, and Direct connects without a proxy server. When troubleshooting a routing rule, first check that Config is selected.
On Demand
Starts a connection when the specified conditions are met, making it useful for automatically connecting based on network conditions. It determines when to connect, not which route an individual request takes. Even when the conditions are met, confirm that the server is available.
Add Server
An entry point for adding existing server details. Select a protocol, then enter the relevant address, port, and authentication details. Available fields vary by protocol. Saving an entry only adds the details; it does not confirm that the client can connect to the server.
Connectivity Test
Checks whether the client can complete a test over a specified route on the current network. The reported duration reflects only the conditions of that test and cannot be converted into download speed. For meaningful comparisons, keep the test target, network, and method consistent.

Proxy Protocols

A protocol defines how the client communicates with a server. Use the details you have rather than guessing the protocol from a port or name.

Shadowsocks
A proxy protocol that uses symmetric encryption. Connection details typically include the server address, port, encryption method, and password. An open port does not guarantee a successful connection; mismatched encryption methods or passwords can still prevent data from being exchanged.
VMess
An authenticated proxy protocol that commonly uses a UUID to identify the user. Check the transport method and related fields as well; a matching UUID alone does not mean two configurations are interchangeable. If authentication fails, compare each field with the original details.
VLESS
A proxy protocol with separately configured authentication and transport protection. Even if both sets of details include a UUID, you cannot reuse a VMess entry by changing only its protocol name. The transport method and security settings must match the peer.
Trojan
A proxy protocol that typically uses TLS for transport and password-based authentication. If the connection fails, check the authentication details and the server name required for TLS separately. A certificate name mismatch and an incorrect password are different issues.
Hysteria2
A proxy protocol built on QUIC that requires the network to carry UDP traffic. Access to regular websites does not mean QUIC connections will also work on the same network. When troubleshooting, note whether the issue occurs only on a particular type of network.
WireGuard
An encrypted tunneling protocol that identifies the peer by public key and uses UDP for transport. The public key used to identify the peer is different from the private key that must be kept secure on your device. Remove private keys and other sensitive details before sharing diagnostic logs.

Rule Keywords

The keyword at the start of a rule determines what it matches; the policy at the end determines what happens when it matches.

DOMAIN
Matches an exact domain. The condition example.com does not also match www.example.com, and it does not match URL paths. Use this precise condition when you only need to change how a specific hostname is handled.
DOMAIN-SUFFIX
Matches a domain and its subdomains. The condition example.com matches img.example.com, but not notexample.com. To handle a subdomain as an exception, place its exact-match rule before the suffix rule.
IP-CIDR
Compares the destination IPv4 address with a specified network range, such as 192.0.2.0/24. The number after the slash is the prefix length, not a port. If a request starts with a domain name, the result depends on whether the address has been resolved and on the rule parameters.
GEOIP
Matches based on the destination IP region recorded in the address database, not the website's language, domain suffix, or the device's location. A domain may resolve to different addresses on different networks, so it will not always match the same regional condition.
FINAL
Sets a fallback policy for requests that do not match any preceding rule. It requires no domain or address condition, as in FINAL,DIRECT. Place it after rules that need to be evaluated first so matching does not end prematurely.

Policies & Matching Order

Proxy and Direct in the interface are Global Routing options; PROXY and DIRECT in a rule are policies for handling that specific rule.

PROXY
Sends matching requests through a proxy route. A rule match only confirms that the route has been selected; it does not mean the proxy server can reach the destination. If diagnostics show a match but the request still fails, check whether the selected server and destination are reachable.
DIRECT
Connects matching requests to their destinations over the current network, without using a proxy server. Direct does not bypass DNS lookup or turn off the client. When rule handling is enabled, the client can still select different routes for different requests.
REJECT
Rejects requests handled by the client that match this policy. Rules only handle traffic that meets their conditions; they do not identify every element on a webpage. Before using a broad suffix condition, make sure it will not also block services on the same domain that you need to keep.
Rule matching order
Rules are checked in the configured order, and the first match wins. The client does not collect every match and then select the most specific one. If a broad suffix rule appears before an exact-domain rule, change the order and test again with the same destination.

When reading a rule, first identify the match type before the first comma, then check the policy at the end. For example, DOMAIN-SUFFIX,example.com,PROXY means that a domain ending in example.com uses a proxy route.

Subscriptions & Configuration Files

A subscription retrieves an existing server list; a configuration file defines how requests are handled. Refreshing the list does not change routing rules.

Subscribe
Imports an existing subscription URL and reads its server entries. After refreshing the list, confirm that the selected entry is still available and its settings are correct. Subscription URLs may contain access credentials, so do not include the full URL in diagnostic reports.
Config
As a page entry, this opens and manages configuration files. In Global Routing, it means traffic is handled according to the active configuration. Editing a file does not automatically select it. Before testing rules, check which configuration is actually enabled.
DNS
Looks up domain records, which a connection request may use to obtain the destination address. Domain lookup and connecting to the destination are separate steps: resolving an address does not mean the destination is reachable. When troubleshooting address-based rules, check the address actually obtained, not just the domain entered.
URL Rewrite
Applies rewrites and other actions to matching URLs. This is separate from choosing an outbound route in a rule. URLs may include paths and query parameters, which domain-based conditions cannot distinguish. Before writing a condition, confirm what request details the client can see in the current scenario.

Related Guides

To import existing details for the first time, see the setup guide. To compare rule fields and priorities, see the configuration reference.

The iPhone and iPad app is available on the App Store for a one-time purchase of $2.99. Check the App Store listing for system requirements. The Mac (Apple Silicon and Intel), Windows, Android, and Linux versions are free; installers are available only through the site download page at /dl/. Buying the app once does not include a service plan.