Shadowrocket
Rules & Configuration Guide

01 / FILE STRUCTURE

Config file structure and where it takes effect

Keep configuration files and server details separate

Server entries and configuration files serve different purposes in Shadowrocket. Server entries store connection details such as the destination, port, protocol, and authentication parameters. A configuration file defines how requests are matched, which policies to apply, and how certain DNS and request behaviors are handled. This guide assumes you already have your own subscription or server details. Selecting an imported server does not mean a set of rules is active; likewise, saving a rule file does not mean its PROXY policy has a usable connection target.

Before editing, check the selected server in Home, the active configuration file in Config, and the current Global Routing mode. Config is the usual mode for checking the file’s routing rules. Proxy and Direct change the global routing mode, so their test results cannot tell you whether a specific domain rule is correct. Keep the server, file, and global mode as separate checkpoints; changing one does not automatically update the others.

Read the file by section

Configuration files use a section-based text format. Headers in square brackets identify the section that follows. [General] holds global settings; [Rule] lists matching conditions and policies, one per line; [Host] contains static domain-to-address mappings; and [URL Rewrite] defines how matching URLs are handled. Section headers are not rules and do not match requests. A DOMAIN-SUFFIX entry under [General] will not become a working routing rule just because it contains a valid rule keyword.

This snippet shows two routing intentions: send example.com and its subdomains through PROXY, and send everything else through DIRECT. It contains no server credentials and does not provide a connection service. The example domain is for illustrating syntax only; it does not guarantee access to any service. When reviewing a complete file, locate all section headers first, then find FINAL in [Rule]. Don’t search from the first line for a domain name without checking which section it’s in.

Commas, equals signs, and comments have different roles

In [General], settings are typically written as a key, an equals sign, and a value, such as dns-server = system. In [Rule], commas usually separate the rule type, match value, and policy, such as DOMAIN,example.com,DIRECT. These formats are not interchangeable. Use standard ASCII punctuation when editing; avoid full-width commas from an input method. Comments can go on their own line beginning with #. Don’t rely on an end-of-line note to explain a rule; a separate line makes field boundaries easier to inspect and text easier to copy.

Not every config needs all four sections. You can omit [Host] if you don’t need static mappings, and [URL Rewrite] if you don’t need URL handling. Start with the minimum settings and add only what you have a clear reason to use. This is easier to validate than merging every section from multiple files. If a section or setting is duplicated, consolidate it into one clear definition instead of relying on overrides. Keep a copy of the original file before making structural changes.

02 / GENERAL & DNS

General settings and DNS

Check network boundaries before setting bypass ranges

Settings in [General] affect the environment in which the rules run. bypass-system = true bypasses system-related traffic; it does not set all Apple domains to DIRECT and is not a general replacement for rules in [Rule]. skip-proxy specifies address ranges to exclude from proxy handling. If a request is bypassed before rule evaluation, changing a later PROXY rule may not have the expected effect. Troubleshooting requires checking both global bypass settings and [Rule], not just moving a rule to another position.

For local network devices, choose bypass ranges based on your actual address plan. 192.168.0.0/16 and 10.0.0.0/8 are examples of private address ranges; your network may use different ones. Check your device’s network details and the destination service’s address before deciding whether to keep these ranges. A range that is too broad may exclude internal destinations that should use a proxy. A range that is too narrow may send printing, storage, or other local traffic over an unsuitable connection path.

[General]
bypass-system = true
skip-proxy = 192.168.0.0/16, 10.0.0.0/8
dns-server = system

DNS resolution and routing policy are separate

dns-server = system uses the system DNS settings and is a useful baseline. DNS resolves domain names to addresses; routing rules decide which policy a request uses. A domain resolving successfully does not mean the selected server can connect to that address. A request matching DIRECT does not mean its DNS query necessarily took the path you expected. Check the resolution result, rule match, and final connection separately to avoid blaming every timeout on DNS.

Before changing DNS, identify the problem: does the domain fail to resolve, resolve to an unexpected address, or resolve successfully while the connection fails? If only one target is affected, check that target and any [Host] mapping instead of immediately replacing the file’s DNS settings. If multiple domains fail to resolve, check whether the system DNS is available on the current network. Encrypted DNS addresses, bootstrap resolution, and connection paths can depend on one another; the address format alone cannot tell you whether a setting suits your network.

Whether a rule triggers resolution depends on its match condition

DOMAIN rules primarily match domain names; IP-CIDR and GEOIP need a destination address to evaluate. Address-based rules may involve DNS resolution when a request starts with a domain name. The no-resolve option on IP-CIDR prevents that rule from triggering an additional domain lookup. It does not disable DNS for the whole app. Use it when the request is explicitly addressed by IP or when you want to avoid resolution for a particular address rule; it may also prevent a domain-based request with no address available from matching that rule.

Apps and operating systems may cache DNS results, and web connections may reuse existing sessions. Refreshing the same page after a DNS change may not trigger a new lookup. To verify a change, start a new connection, reconnect Shadowrocket if needed, and check the timestamp and target in the logs. Keep a working dns-server = system configuration as a baseline. Change one DNS-related setting at a time to distinguish its effect from changes caused by stale cache entries.

If the issue only occurs when switching between Wi-Fi and cellular, record what happens on each network separately. System DNS, local address ranges, and server reachability can all vary by network. Don’t use a wider skip-proxy range to mask the problem or keep adding duplicate DNS settings. Restore a working baseline, identify what differs between networks, then see Troubleshooting for connection checks. Make lasting changes to your everyday config only after you know what needs to change.

03 / DOMAIN MATCHING

How DOMAIN rules match

DOMAIN matches one exact domain

DOMAIN performs an exact domain match. DOMAIN,api.example.com,PROXY applies to api.example.com; it does not automatically include example.com or match otherexample.com just because it contains the same text. Enter a hostname in the match field, not a scheme, path, port, or query string. Pasting a full web address into a DOMAIN field confuses URLs with domain names. If your requirement depends on a path, first determine whether URL handling is appropriate instead of broadening the domain rule.

An exact rule is useful for an exception to a broader rule—for example, sending all of example.com through PROXY while routing status.example.com through DIRECT. Put the exception before the broader DOMAIN-SUFFIX rule. Once the suffix rule matches, the later exact rule is never evaluated. Priority comes from the rule’s position, not from DOMAIN looking more specific than DOMAIN-SUFFIX. The app does not automatically reorder the file by match specificity.

DOMAIN-SUFFIX matches domain boundaries

DOMAIN-SUFFIX,example.com,PROXY matches example.com and its subdomains, such as www.example.com and a.b.example.com. Suffix matching follows domain boundaries; it does not match arbitrary text, so otherexample.com is not a subdomain. A suffix value usually needs neither a leading dot nor an asterisk. Copying *.example.com as a suffix example can lead to using wildcard syntax where it does not apply.

[Rule]
# Exact exception first
DOMAIN,status.example.com,DIRECT
# Parent domain and subdomains after
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

A webpage may request its main domain, image domains, authentication domains, and API domains at the same time. Adding a rule for only the domain in the address bar does not mean those dependencies will use the same policy. Identify the actual hostnames in connection records, then decide whether to use several DOMAIN rules or one DOMAIN-SUFFIX rule that reasonably covers them. Don’t compress unrelated targets into a short keyword; troubleshooting one page could otherwise change traffic paths for other apps.

DOMAIN-KEYWORD matches text within a domain

DOMAIN-KEYWORD,example,PROXY matches domains containing the text example, so its scope may be much broader than example.com. It can match other domains containing that text and does not require the same registered-domain boundary. Use a keyword only when you need that broader text-based match and its scope is clear. If you only need a parent domain and its subdomains, prefer DOMAIN-SUFFIX. The shorter the keyword, the more carefully you should check for unintended matches.

Write rule intent as a condition you can verify

Before adding a domain rule, describe its scope in one sentence—for example, “Only status.example.com should connect directly”—then compare that statement with the actual fields. If you mean “all subdomains,” check whether a suffix rule is appropriate. If you mean “a specific path,” a domain rule cannot express that requirement. For internationalized domains, check the hostname shown in request records so it matches the form used in the config. Don’t guess a domain from a webpage title or app name.

Test one target that should match and another that should not, giving you a positive and a negative check. Record the hostname, matched rule, and policy—not just whether the page loads. A successful page may be using DIRECT, so it does not prove the PROXY rule worked. A failure may also come from the server or destination service. If unrelated requests start using PROXY after a change, narrow the keyword scope and check rule order instead of adding more similar rules at the end of the file.

04 / ADDRESS & REQUEST

GEOIP, IP-CIDR, and USER-AGENT

IP-CIDR matches an address and prefix

IP-CIDR matches IPv4 address ranges, for example IP-CIDR,192.168.0.0/16,DIRECT. The number after the slash is the prefix length, not a port or the number of addresses to match. A longer prefix covers a smaller range. A single IPv4 address can be written with /32. When changing a network rule, compare the target’s actual address with the range boundaries; a similar-looking address prefix does not prove that it falls within the range. An incorrect prefix may apply one policy to many unrelated requests.

Understand local network ranges alongside skip-proxy in [General]. If a range is already bypassed globally, adding the same range as DIRECT in [Rule] may only duplicate the behavior; it does not prove the rule engine matched that line. To test a specific rule, first determine whether the request reaches rule evaluation. You can keep necessary direct-connect safeguards in everyday configs, but note their purpose in a comment. Duplicate entries do not increase priority.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

IP-CIDR6 and the limits of no-resolve

IP-CIDR6 matches IPv6 ranges. Don’t put an IPv6 address in IP-CIDR and expect it to be handled the same way. fc00::/7 is an example of a local IPv6 range; it does not mean all IPv6 requests should use DIRECT. A domain may resolve to both IPv4 and IPv6 addresses, so checking only one address type can miss the connection path actually in use. If a domain seems to match inconsistently, first check which address type the request uses, then decide whether to add the corresponding rule.

no-resolve is an option for address rules that prevents the rule from actively resolving a domain name to check for a match. A request made directly to an address can be evaluated using the address already available. A domain request with no address available to match may not hit the rule. This is a difference in usage conditions, not a syntax error. Don’t add no-resolve mechanically to every address rule to speed up resolution, and don’t treat it as a policy that forces DIRECT or remote DNS.

GEOIP does not identify a domain’s ownership

GEOIP,CN,DIRECT evaluates the geographic classification of the destination IP address. It does not use the domain suffix, webpage language, or service brand. A domain may resolve to addresses in different regions, and an IP database classification does not indicate current network quality. For a stable policy for a specific domain, express it with DOMAIN or DOMAIN-SUFFIX first, then place GEOIP later to handle remaining traffic. Otherwise, address changes may cause the same service to use different policies on different networks.

USER-AGENT depends on visible request fields

USER-AGENT matches the User-Agent content in a visible HTTP request; it does not identify a process by its app display name. USER-AGENT,ExampleClient*,DIRECT shows an intended prefix match, but it can only be evaluated if that request field is available. HTTP headers in ordinary encrypted connections are not usually visible directly. An app sending the field does not guarantee that the client can use it for rule matching. USER-AGENT is not a general substitute for routing traffic by app.

[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

Enabling request decryption to make USER-AGENT rules work adds trust and compatibility requirements; it is not a necessary first step for routing. If a domain rule can express your requirement, start with that. Address-based and request-attribute rules also need clear validation conditions: is an address available to match, is the request field visible, and has an earlier rule already matched? Answering these questions gives you a sounder basis for troubleshooting than dragging a rule from the bottom of the file to the top.

05 / POLICY & PRIORITY

PROXY, DIRECT, REJECT, and rule order

Policies define what happens after a match

The rule type determines what is checked; the policy determines what happens after a match. PROXY sends the request through the proxy path, usually via the currently selected server in a simple config. If the file contains policy groups or related settings, check which member is actually selected. DIRECT connects to the destination without forwarding through a proxy server, but traffic still depends on the current network, DNS, and destination service. REJECT denies the matched request; it is not a fallback policy that automatically takes over when a connection fails.

In a config, PROXY, DIRECT, and REJECT are policy keywords. The server selected in Home and the Proxy or Direct options in Global Routing are interface states. They appear in different contexts and must not be treated as the same concept. Changing a rule to PROXY does not fix a server password, port, or protocol setting. If every request matching PROXY fails, check the proxy connection path before changing each rule to DIRECT and assuming the problem is solved.

Three Global Routing modes

This table helps you choose a mode for testing; it does not mean all traffic always bypasses system exclusions and other global settings. You can briefly use Proxy or Direct to compare connection paths, but switch back to Config when you’re done and verify rule matches against the current file. Otherwise, “editing the file had no effect” may simply mean Global Routing is still set to Proxy or Direct. When recording test results, include both the mode and target so you can compare behavior under different routing conditions.

The first matching rule wins; there’s no automatic fallback

[Rule] is evaluated from top to bottom. The first matching rule determines the policy. Put more specific rules before more general ones; this is an ordering principle, not an automatic sorting feature in the app. If an earlier DOMAIN-KEYWORD matches a domain, a later, more specific DOMAIN rule cannot override it. Duplicate conditions usually make later entries unreachable, so consolidate them rather than expecting a newer line to replace an earlier one.

[Rule]
DOMAIN,status.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

In this example, status.example.com matches the first line, so the later suffix rule is not evaluated. blocked.example.com matches REJECT; other example.com subdomains use PROXY; remaining requests are checked against GEOIP and then handled by FINAL. If a request matches PROXY but the connection fails, the rules do not continue down to DIRECT. Rule evaluation and connection handling are separate stages: a connection result does not change the first match already selected.

FINAL should express a deliberate default

FINAL takes no match field and is written as FINAL,PROXY or FINAL,DIRECT. It handles requests not matched earlier and belongs at the end of [Rule]. Rules after FINAL cannot handle those remaining requests. Before choosing a default policy, decide where unlisted destinations should go. Don’t keep a copied file’s default policy without checking whether it matches your intent. Two FINAL entries do not provide primary and backup routes; the second is not a failover mechanism.

Keep REJECT rules as specific as possible and test them separately. A page’s analytics, images, authentication, and API calls may share a domain; a broad rejection can leave the page visible while breaking its features. First confirm that blocking is necessary, then see whether a precise domain rule can express it, and check dependent requests. To undo the change, remove or disable the REJECT rule you added and start a new session. A later DIRECT rule cannot undo a REJECT that matched earlier.

06 / HOST & URL REWRITE

The roles of Host mappings and URL Rewrite

Host changes address mappings, not routing policy

[Host] defines a static mapping between a domain and an address, for example lab.example.com = 192.168.1.20. It answers “which address should this domain resolve to?”—not “should the request use a proxy or connect directly?” After adding a mapping, still check how [Rule] handles the domain or destination address. This example illustrates a local service you manage yourself. Use a mapping only after confirming that the address is the intended destination; don’t use the example address to access a real website.

[Host]
lab.example.com = 192.168.1.20

[Rule]
DOMAIN,lab.example.com,DIRECT
FINAL,PROXY

A static mapping pins the resolution result, so you need to update it if the destination address changes. If the service normally distributes traffic across multiple addresses, pinning one address may bypass that process. Before editing, note the original resolution and confirm that the domain, address, and intended use all match. A mapping that works on one device may not suit other networks. For example, a local address may be unreachable when you leave the Wi-Fi network it belongs to; check the network range instead of repeatedly retrying the same mapping.

A mapping does not replace a certificate or service identity

When connecting to an HTTPS service by domain, the destination address and the domain covered by the certificate are separate requirements. [Host] changes the address; it does not make the service’s certificate valid for any domain or fix the server’s name configuration. If you see a certificate error, confirm that the service provides a valid certificate for that domain. A static mapping is not a way to bypass certificate validation. Reverting the mapping and starting a new connection can help distinguish an issue with the original service from one caused by pinning an address.

URL Rewrite uses regular expressions to match targets

[URL Rewrite] uses a URL match expression and a corresponding action. The example below redirects a specific path to another path; 302 indicates a temporary redirect response. This is not a proxy policy and does not automatically change PROXY to DIRECT. example.com is sample text, not an external service endpoint. Before using a rewrite, confirm that the action applies to your request environment and test one specific path first. Avoid broad expressions that cover every path on a domain.

[URL Rewrite]
^http://example\.com/legacy$ http://example.com/current 302

In a regular expression, ^ marks the start and $ the end. The dot in a domain is written as \. to prevent it from matching any character. This example matches only a complete URL ending in /legacy with no additional query parameters; /legacy/ and requests with query parameters do not meet the same condition. If you need to preserve paths or parameters, first understand how capture groups and replacements work. Don’t use .* indiscriminately to pull everything into the match.

Check HTTPS visibility limitations first

A standard HTTPS connection does not expose the full HTTP URL path directly. Applying a path-level rewrite to these requests usually requires additional request decryption conditions and certificate trust configuration. Adding [URL Rewrite] to a file alone does not make the path visible. Some apps also perform additional certificate checks, and enabling related features may affect compatibility. If you don’t have a clear need, keep the default connection behavior. Domain-based routing does not require adding decryption settings for URL rewriting.

A redirect creates a new destination, so the new request must be evaluated against routing and service conditions again. If another rewrite rule sends it back to the original path, a loop may occur. When testing, record the original URL, matching expression, redirect location, and final destination; don’t check only the page shown in the browser. Disable other rewrite rules for a single-rule test, then restore them one at a time to identify interactions between rules and redirects from the destination service. If redirects continue, revert the rewrite rather than broadening the expression.

07 / EDITING WORKFLOW

Editing workflow and common rule patterns

Copy the current file and make a minimal change

Before editing, keep a copy of the working config and use clear names to distinguish the original from the test file. Write down the target, match scope, and expected policy first. Then open the relevant file in Config and edit it. After saving, confirm that the test file is active, set Global Routing to Config, and start a new request to the target. Don’t change the server, DNS, default policy, and several rules at once; if the result changes, you won’t know which edit caused it.

Your existing server subscriptions and remote configs may have separate update workflows. Updating a server list does not necessarily update local rules. Fetching a remote config again may overwrite your local edits. Before editing remote content, understand how saving and updates work, and keep your rule intent in a copy or separate notes. Don’t rely on filenames alone to remember what you added; use separate comments to explain the purpose of each group of rules.

Direct by default; proxy only selected domains

If you want explicitly listed domains to use a proxy and everything else to connect directly, use a structure like this. DOMAIN-SUFFIX covers the example parent domain and its subdomains; FINAL,DIRECT handles remaining requests. Before adding another target, check whether an existing suffix rule already covers it. If so, there’s no need to add the same policy again. If the service depends on other domains, use actual connection records to identify them instead of guessing a broader keyword to cover every possible destination.

[General]
dns-server = system

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

Proxy by default; add direct-connect exceptions for specific targets

Another common requirement is to send unlisted requests through a proxy while keeping local network ranges or specific domains direct. First confirm that the selected server works, because FINAL,PROXY makes all remaining requests depend on that connection path. Specify address and domain exceptions separately. Don’t broaden every range outside private addresses just to make one internal domain connect directly. If your everyday config already includes global bypass settings, check those first to see whether additional network rules are needed.

[Rule]
DOMAIN,lab.example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
FINAL,PROXY

These are not fixed recommendations; they express different default policies. Don’t combine them by adding two FINAL entries. Choose the intended default first, then put the required specific rules before it. If you only want to change one domain, don’t also change the config’s default policy. To validate an exception, check that the target matches its specific rule, then check that an unlisted target uses FINAL. Together, these tests confirm both parts of the config.

Resolve conflicts before trimming merged files

When consolidating rules from configs you’ve saved, first look for overlap by type and match scope. If identical conditions specify different policies, decide which reflects your current intent. If an exact domain overlaps a suffix, preserve the correct exception order. If a keyword overlaps a suffix, check whether the keyword is too broad. More rules do not mean better coverage; duplicates and unreachable entries only make the file harder to review. Keep one clear FINAL after you consolidate.

Grouping a complete file into local exceptions, service domains, address ranges, and a default policy can make it easier to review, but it is not a required order. Comments can explain the intent of each group; actual priority still depends on line order. If an address exception must take precedence over a broad domain condition, put it in the right position for your use case. After organizing each group, test the same target and record the result so you can recover the original behavior if a larger reorder causes problems.

This page doesn’t repeat the steps for importing servers or editing server fields. To organize existing entries, see How to import subscriptions. For protocol fields, see Protocols and settings explained. Changing rules won’t fix authentication or transport settings; those belong to a different layer.

08 / VERIFICATION

Validating rule matches and troubleshooting

Record four facts for each test

When testing a rule, record at least the target hostname or address, the current Global Routing mode, the matched rule or policy, and the final connection result. Whether a page opens is only the last item; it cannot replace evidence of how traffic was routed. Check the target and policy shown for the current connection or log entry, and use what the app actually displays. A single page may generate requests to multiple domains and multiple connections. Choose a specific target you can request repeatedly, then follow its new record rather than mistaking a background request for the one you’re testing.

Connectivity Test checks connection status, but it cannot prove that every dependency of a webpage uses the expected rule. After confirming that the server is reachable, make a real request to the target and check the match. Existing connections may persist after a rule change, and the browser may serve cached content; reconnect and start a new session if needed. For before-and-after comparisons, keep the network, server, and target the same, and change only the rule being tested.

If the config seems unchanged, check the activation chain

If nothing changes after editing, check three things: the file, the mode, and the rule order. First confirm that you saved the active file, not a copy with the same name. Then make sure Global Routing is set to Config. Finally, work down [Rule] from the top and check whether an earlier condition already matches the target. Look especially for broad keywords, large address ranges, and an early FINAL. A newly added line can be syntactically correct and still have no effect if you skip the rules above it. The first match determines the result of the ordered list.

A rule match does not guarantee a successful connection

If the record shows the expected policy, investigate the execution path next. If PROXY fails, check whether the server selected in Home is still usable and whether the authentication fields, port, and transport settings match your existing details. If DIRECT fails, check whether the current network can connect to the destination. For REJECT, confirm that blocking was intended. Don’t treat a clear connection failure as a rule-priority issue. If needed, briefly compare Proxy and Direct, then restore Config and test again.

If only some features fail, check the page’s main request separately from subsequent API calls. Login, uploads, images, and persistent connections may use different domains or connection methods. A page loading successfully does not mean every dependency works. First check whether REJECT matched a critical endpoint, then see whether dependent requests are using an unexpected FINAL policy. If only a particular transport fails, check server and protocol support instead of broadening domain matches to work around a transport-layer issue.

Troubleshoot with a minimal config, then restore the full file

A minimal config keeps the necessary [General] settings, one rule for the target, and one FINAL. Temporarily remove Host entries, rewrites, and broad keywords you added. Use this to check whether basic matching behaves as expected; it is not a recommendation to discard your original config permanently. If the minimal file works, restore the original content one group at a time until the difference appears. If it still fails, check the target name, resolution result, and server path. Restoring one group per round helps identify the specific condition instead of merely confirming that the full file has a problem.

When reverting, restore both the config contents and the test mode, then start a new connection. You can record the target, network type, rule snippet, and error description, but remove authentication parameters from subscription links, server passwords, and other private details. Copying real credentials into troubleshooting notes can turn a localized connection issue into an information exposure problem. Example text that shows the structure is enough to discuss rule order, section placement, and field count.

For your first connection or VPN configuration permission issues, return to Getting Started. For purchases, restoration, and system requirements, see Restore a previous purchase; check the App Store page for system requirements. For more symptom-based guidance, see Troubleshooting. This page explains configuration behavior; app purchases, server connections, and rule matching are separate troubleshooting topics.