Shadowrocket Rules and Configuration Reference

01 / CONFIG STRUCTURE

Config file structure: distinguish server details from behavior rules

In Shadowrocket, server details specify which server to connect through; a config file specifies how to handle a request. They are related, but they are not the same thing. A subscription you already have is typically used to import and update server entries. A config file with routing rules must be reviewed and enabled in Config. Seeing servers in Home does not mean custom rules are active. Before reviewing a config, note the selected server, the enabled config file, and the Global Routing mode so you can keep those conditions consistent while troubleshooting.

What the four config sections do

Text configs commonly use square brackets to mark section names. [General] contains general parameters, such as DNS and system traffic settings; [Rule] contains request matching conditions and their corresponding policies; [Host] maps specified domain names to addresses; [URL Rewrite] processes matching URLs according to expressions. Section names are not decorative headings: a line’s section determines how it is interpreted. A domain rule pasted under General cannot be used as a Rule entry, even if its syntax is correct.

[General]
bypass-system = true
dns-server = system

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

[Host]
localhost = 127.0.0.1

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

This snippet illustrates the structure; it is not a general-purpose config to apply in full. The two lines under General show a Boolean parameter and a DNS value; the three Rule lines show a domain, an address range, and a final policy. localhost under Host is an example of the local loopback name, and the last line demonstrates an HTTP-to-HTTPS redirect. Example domains do not represent real services, so clarify your goal before copying anything. In particular, FINAL affects every request that has not matched an earlier rule. Do not copy PROXY just because it appears in this example.

Punctuation, line breaks, and readability

Rule fields are separated by half-width commas, parameter assignments use half-width equals signs, and section names use half-width square brackets. Full-width commas, quotation marks, or spaces from an input method can keep content from parsing as expected. Put each rule on its own line; do not mistake a visual line wrap in a webpage for a new rule. You can read a rule as “keyword, match value, policy, optional parameters,” but not every keyword has the same number of fields. FINAL, for example, has no match value, so do not mechanically add a third field.

The order of config sections is not a fixed processing pipeline. General appearing above Rule does not mean every request first runs through all general parameters and then each remaining section. Host and URL Rewrite are not later rules in the Rule list, either. The order that matters from top to bottom is the order within Rule. Keeping config structure separate from rule priority helps avoid ineffective edits that move entire sections to “raise a rule’s priority.”

Check which config is enabled in Config

Open Config, identify the currently selected file, then open the item you want to review or edit. Before changing a copy, give it a name that describes its purpose and keep the original. Saving edits and enabling a file are two separate checkpoints: saving confirms the text was written, but does not necessarily mean the current connection is using that file. Return to the file list to confirm the selection, then check Global Routing. Interface layouts can change, so rely on the file name, selection state, and actual request results—not a fixed screen location.

If you are unsure whether you have the genuine app, first follow the authenticity check to verify the developer, Shadow Launch Technology Limited, the official icon, and app ID 932747118. Shadowrocket is a paid Apple-platform app available exclusively on the App Store. Check the App Store listing for system requirements. Once the basics are confirmed, make deliberate edits to the snippets on this page; changing the server and config at the same time makes it harder to identify the cause of a problem.

03 / DOMAIN MATCHING

Domain rules: exact names, suffixes, and keywords

When a routing target can be described by a stable domain, start with domain rules. Compared with listing addresses directly, a domain condition better expresses the intent to match a site or service and is less affected by changes to server addresses. A domain is not a complete URL: do not paste the scheme, path, query parameters, or port into a DOMAIN match value. For a full URL from the browser’s address bar, extract the hostname first, then decide whether to match only that name or all its subdomains.

DOMAIN: match one exact name

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,account.example.com,DIRECT
FINAL,PROXY

The first line targets api.example.com; the second targets account.example.com. DOMAIN does not mean “contains this text” and does not automatically cover other subdomains. If the actual request is to images.api.example.com, do not assume the first line matches just because it looks like part of the same service. Exact rules are useful for a small number of clear exceptions—for example, when most requests use the final policy but one hostname needs DIRECT. Confirm the full name in the actual request before creating a rule; a brand name shown on a page may not be the hostname used for network requests.

DOMAIN-SUFFIX: cover a suffix at a domain boundary

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

DOMAIN-SUFFIX,example.com covers example.com and its subdomains, such as www.example.com. It matches at a domain boundary, not any arbitrary string ending, so notexample.com is not a normal match for this suffix. The example puts an exact exception for private.example.com before the broad suffix rule. If you swap the lines, the suffix matches that exception first and the exact rule no longer has its intended effect. Pay more attention to how rules overlap than to how many lines they take.

A suffix usually does not need an asterisk. Treating *.example.com as the standard value for DOMAIN-SUFFIX confuses wildcard expressions with suffix matching. Do not broaden the scope to a very short public suffix just to cover image domains, either. The wider the scope, the more likely it is to include unrelated services. Start with the registrable domain actually used by the service, then add separate domains based on request records rather than assuming every request shares the same suffix.

DOMAIN-KEYWORD: broader scope, more false matches

[Rule]
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

DOMAIN-KEYWORD matches a keyword contained in a domain name. example here is not a complete domain and does not have the domain-boundary behavior of DOMAIN-SUFFIX, so it may match unrelated names. Use it only when you specifically need this broader condition and can check its impact. If your goal is only to cover example.com and its subdomains, a suffix rule is usually a better fit. A shorter rule is not necessarily more accurate, and using fewer keywords does not necessarily make it easier to maintain.

A page’s domain is not the only domain it requests

A page may send requests to separate domains for login, images, APIs, and static assets. If the homepage loads but login fails, the same rule may not be behaving inconsistently; another set of requests may be using a different policy. Check request records while reproducing the issue, identify the name that actually failed, then decide whether to add a rule. A third-party asset domain may be shared by multiple services. Its presence on one page does not mean every request to that domain should use that page’s policy.

If request records show only an IP address and no domain suitable for matching, a domain rule may not be the right place to investigate. Check address rules, DNS, and how the request was made instead of stacking more similar domain rules. For internationalized or otherwise unusual domain names, use the form shown in the actual record. After making a change, test both the target name and a similar name that should not match. This verifies that the rule covers the intended scope without including names beyond its boundary.

05 / POLICY

Global Routing and PROXY, DIRECT, REJECT

Config, Proxy, and Direct in Global Routing are mode choices. PROXY, DIRECT, and REJECT in Rule are policies for handling requests. The terms look similar but belong to different layers. When checking whether a rule is working, start with Global Routing. If requests are not currently being handled according to the config, you cannot assume that editing Rule will change the connection result. In particular, after temporarily switching to Proxy or Direct for a test, remember to restore the original mode before verifying custom routing.

PROXY: uses the proxy path; it does not guarantee the remote connection will succeed

The PROXY rule policy expresses the intent to connect through the currently selected proxy. It is not a server address and does not supply required authentication or protocol parameters. If the address, port, credentials, or other settings in a server profile you already have are wrong, a request can match PROXY correctly and still fail to connect. Verify two things separately: that the request selected the expected policy, and that the connection path used by that policy is available. Treating both checks as a single “the rule isn’t working” can send troubleshooting in the wrong direction.

Also note the server selected in Home. Results may differ if you change servers while keeping the same config; that does not mean the Rule syntax changed. For custom policies or groups, check their names and what they point to. Do not put an undefined name in an example. This guide uses three built-in policies so the snippets do not depend on extra group definitions. For more on Trojan settings, see Trojan parameter reference; do not try to fix protocol parameters by editing domain rules.

DIRECT: connect directly over the current network

DIRECT does not mean stopping Shadowrocket or turning off the system VPN configuration. It selects a direct connection to the destination in the current handling flow. Reachability still depends on the current network, resolution result, and the service itself. DIRECT is often appropriate for local network destinations, but the device must be on the relevant network. If it is not, or the local service is not listening on the relevant address, a DIRECT rule cannot create network connectivity that does not already exist.

REJECT: explicitly reject matching requests

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

The first line rejects a specified name, the second sends other matching suffix requests through PROXY, and the last handles the remaining traffic. REJECT is for destinations you explicitly do not want to connect to; it is not a substitute for choosing a final policy. If a rejected name is also used for login, verification, or content loading, parts of a page may stop working. Understand the name’s purpose before editing, then check key page actions afterward rather than only whether the homepage appears.

A rejection policy does not guarantee page cleanup. Page content and network requests do not map one-to-one, and a single domain may serve multiple functions. Using an overly broad suffix or keyword rule to block one resource can also affect normal requests. Start with a precise target and confirm the condition in request records before widening the scope. If a new problem appears, first remove the rejection rule you just added instead of stacking exceptions that obscure the original issue.

FINAL: choose a destination for unmatched requests

FINAL is a final rule with no match value. Common forms are FINAL,PROXY and FINAL,DIRECT. It is not the same as a global mode: FINAL is still part of the rule config under Config and handles only requests that did not match earlier rules. Choose a policy based on the intended default behavior; neither value is right for everyone. With PROXY, confirm that a server you already have is available. With DIRECT, account for unlisted destinations being handled as direct connections.

If behavior differs across the three modes, record the differences rather than jumping to a conclusion. Direct working while Proxy fails may point to the server path. Proxy working while Config fails may point to the matching policy or another config setting. If all three fail, the destination or current network may be the issue. Use connection records to make a specific diagnosis; mode-switch results alone cannot rule out every other cause.

07 / HOST AND URL REWRITE

Host and URL Rewrite: address mapping and URL rewriting are separate

Host maps names to addresses; URL Rewrite processes URLs that match expressions. Neither selects PROXY or DIRECT. When access fails, first clarify what you need to change: should the same domain resolve to a different address, should an old URL redirect to a new one, or should the connection use a different path? The first two needs may involve this section; the third belongs in Rule. Changing Host for routing often introduces additional address and certificate issues.

A minimal Host example and its limits

[Host]
localhost = 127.0.0.1

The name is on the left and the address on the right; localhost and 127.0.0.1 show a local loopback mapping. “Local” means the device making the connection, not the router or the selected proxy server. Do not use this address for a service hosted remotely. Adding a mapping provides address information; it does not make a service run at that address. If no service is listening on the target port, the network is unreachable, or the service is misconfigured, the connection can still fail even when the name maps to an address.

Before pinning a real domain to an address, confirm who maintains that address, whether it is stable, and whether access that way is supported. Many services return addresses dynamically based on region and load; pinning one result may disrupt their normal routing. A mapping can also hide changes in normal DNS responses, making it seem as though the resolver is still returning an old address. Use Host for clear, controlled mapping needs—not to keep a temporary resolution result indefinitely.

Host does not replace TLS verification

HTTPS connections also depend on the requested domain and certificate. Mapping a domain to an address does not mean that address serves the domain correctly, and it does not automatically fix a certificate name mismatch. For TLS errors, check the destination name, address, and server configuration; do not treat disabling verification as a routine fix. Remove a mapping when it is no longer needed, and check the actual address on a new connection so old config does not affect later troubleshooting.

The three parts of a URL Rewrite entry

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

This line contains, in order, a match expression, a replacement target, and a redirect status code. The leading ^ matches from the start of the string. The backslash after example escapes the period so it is treated as a literal character; without it, a period in a regular expression usually matches any character, broadening the match. The trailing slash is also part of the condition. The 302 here demonstrates a temporary redirect; it does not mean the rule will fix every HTTP request or automatically preserve the original path and query parameters.

The example uses a fixed replacement URL and does not explicitly preserve the rest of the matched URL. If your actual use case needs paths or query parameters, plan the capture groups and replacement method first, then test with a few controlled targets. Do not redirect login callbacks, API requests, and regular pages to a site’s homepage just because they share the same starting domain. An overly broad rewrite can break request semantics or create a redirect loop. If the rewritten target also matches another rewrite rule, check how they interact.

Limits on HTTPS visibility

A complete HTTPS path and request contents are generally inside an encrypted connection. Do not assume that adding URL Rewrite will affect every encrypted request. This chapter does not require HTTPS decryption or certificate installation as a prerequisite for routing rules. If you only want to choose a destination based on a domain, use a domain rule; you do not need extra settings to expose the full URL. Whether a feature applies depends on the request information actually visible and the processing conditions supported by the app.

Include a rollback step when testing either config section. Save the original value, add a single mapping or rewrite, check the target behavior, then revert it and test again to see whether the behavior changes consistently. If the problem remains after reverting, consider caching, existing connections, or changes to the target service rather than adding more entries. For a review of how all four sections fit together, see the config file structure guide. The principle here is to keep changes within a scope you can explain and verify.

08 / CHANGE AND VERIFY

Editing a config and troubleshooting: build a repeatable verification process

A correct config and successful access are related, but they are not the same conclusion. A correct rule may select a path that is temporarily unavailable. A successful visit may come from a cache or an existing connection, so it does not necessarily prove the new rule was used. Reliable verification means keeping test conditions fixed, saving the original config, changing one factor at a time, and recording the result of a new request. This chapter turns the rule types above into a reversible process for cases such as one domain failing, no visible change after an edit, or different behavior after a config update.

Step 1: Record the baseline before changing the config

First note the current network type, Global Routing mode, enabled file, and selected server. Then describe the specific action that triggers the issue. Instead of writing “it doesn’t work,” distinguish among a homepage that will not load, missing images, failed login, a failed API request, or an inaccessible local network device. Choose a reproducible action and, if possible, the same target each time. If the issue is intermittent, observe the baseline several times first; otherwise, a chance success after an edit can easily look like a fix.

Step 2: Save a copy and limit the scope of changes

Keep the original file in Config and edit a copy. Check whether the relevant section already has similar rules, duplicate conditions, or a FINAL placed too early. For a single-domain issue, try one narrow DOMAIN exception before adding a broad keyword rule. If you are changing DNS, do not also move Rule entries. If you are changing Host, do not also switch servers. This makes it possible to link a changed result to one specific edit.

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

This snippet verifies an exact exception: api.example.com uses PROXY, other names matching the suffix use DIRECT, and remaining requests use the final policy. After reviewing each line, map your own target to the intended policy. Do not use the example domain to test real connectivity, and do not append the entire snippet after an existing FINAL. If the current file is complex, reproduce the logic in a copy first, then merge it into the config you intend to maintain once it works.

Step 3: Save, enable, and make a new request

After editing, check that the changes were saved, return to Config to confirm which file is enabled, then set Global Routing to Config. Repeat the target action; if needed, disconnect and reconnect to reduce the effect of reusing an existing connection. Reconnecting does not clear every app cache, so also check request records to confirm a new network request was made. Do not equate “the page looks unchanged” with “the rule did not change”; the page may not have requested the relevant resource again.

Step 4: Check the match before the connection

If the request’s policy is not what you expected, go back to the top of Rule and check for overlapping conditions, the actual hostname, address family, and Global Routing mode. If the policy is correct but the request still fails, check the selected server, protocol details, DNS, and destination response. If the issue occurs only on one network, compare network conditions; if it occurs only with one server, compare connection results. Do not add duplicate rules when the policy is already correct: they cannot fix authentication errors, unreachable addresses, or a problem with the destination service.

Step 5: Retest nearby targets and keep a rollback record

After the target works again, check other requests under the same suffix, a target outside that range, and any local network access that could be affected. Retest more broadly after changing the final policy, because the destination for every unmatched request may change. Record which line you changed, why, how you verified it, and how to revert it. There is no need to save complete sensitive request contents. A well-maintained config should still make sense later—not just appear to work on the day you edit it.

If you still cannot identify the cause, continue with the troubleshooting checklist for when the switch is on but there is no connection, or look for a matching category in Troubleshooting. To review the import and connection process, return to the Quick Start Guide. For purchases and device compatibility, see the App Store authenticity guide. Check the App Store listing for system requirements and whether the purchase is universal. Buying the app again is not a troubleshooting step for a rule issue.