Shadowrocket Complete User Guide

02 / FIRST LAUNCH

First launch and VPN permission

Start with Home before connecting

When you first open Shadowrocket, review Home before turning on the connection switch. Home brings together connection status, Global Routing, Connectivity Test, and the SERVER list. SERVER needs usable connection details; Global Routing determines how requests are routed; the connection switch starts the system network tunnel. Each has a separate role: a server in the list isn't necessarily selected, and selecting one doesn't mean the tunnel is connected.

If Home shows Not Connected, that only means the app reports no active connection; it doesn't tell you whether your subscription is valid. Check the list, select the server you intend to use, and confirm the routing mode—in that order. This helps avoid granting connection permission while the list is empty or the wrong mode is selected, then blaming every problem on system permissions. For an interface overview, see First launch and the Home screen.

Keeping the default settings at first usually makes problems easier to diagnose. You don't need to enable every extra feature at once. Start with one goal: make a manual connection using your existing details. Once it works, adjust On Demand, DNS, or rules one at a time. Handling permissions, connection details, and advanced settings separately makes it easier to identify what caused a change and return to a known-working setup.

What the system permission prompt does

When you start a connection, iOS may ask to allow a VPN configuration to be added. This is part of Apple's network extension permission flow. Once allowed, the device can create a VPN configuration for Shadowrocket to use. You may need to enter your device passcode or complete another authentication step; follow the on-screen instructions. This is not a purchase step and does not enter your server address. It gives the client the system permission needed to start the network connection.

A VPN configuration and a proxy server entry are different things. The system manages the former, which controls tunnel startup and permissions. The app stores the latter, which contains the server, port, and authentication method. So a VPN configuration in system settings doesn't guarantee the SERVER list is correct; likewise, a successful import doesn't mean system permission has been granted. Check each separately rather than deleting everything and starting over.

If you tapped Don't Allow by mistake, return to Home, try starting the connection again, and see whether the permission prompt reappears. If it doesn't, open system settings and look for VPN or VPN & Device Management to check existing configurations and their status. Menu names and locations vary by system and device. On a managed device, some settings may be restricted; check with the administrator before trying to change them.

Check for permission conflicts if the connection won't start

If the device has other VPN configurations or network extensions, first check which one is currently active. For testing, pause configurations that might also control network traffic, then test Shadowrocket on its own to avoid overlapping automatic connection triggers. Keep the original settings for other configurations; there's no need to remove everything just to troubleshoot. On a work- or school-managed device, check the purpose of each configuration and any management requirements first.

Only consider rebuilding the VPN configuration if you have a clear reason to suspect it is damaged and granting permission again hasn't helped. Before making changes, keep your server and Config details, stop the connection, identify the specific configuration, and then remove and reauthorize it using the system's available options. Deleting a system VPN configuration won't restore a subscription and shouldn't be the first step for every problem. See Understanding the VPN configuration prompt for more detail.

If the connection still fails after permission is granted, note exactly where it fails. A switch that immediately turns off may point to a permission or network extension startup issue. If it stays on but requests fail, check the server and routing next. Different symptoms call for different checks; permission being granted doesn't mean everything is working. Record the exact system message, network type, and action that failed rather than repeatedly toggling the switch.

04 / GLOBAL ROUTING

Global Routing modes and rule order

What Config, Proxy, and Direct do

Global Routing selects the routing mode for the current connection. Config uses the rules in the active Config file to determine where requests go. Proxy routes traffic through the selected proxy path. Direct connects without that proxy path. These are behavior modes—not speed settings or separate servers. Switching modes doesn't replace your authentication details; check that the server and Config are valid too.

For troubleshooting, briefly use Proxy as a comparison with Config. If the same destination works in Proxy but fails in Config, check rule matching and policy routing first. If both fail, check the server and basic network. Direct can help you observe direct access, but the result applies only to that network and destination at that time. Change one condition at a time, then restore the original mode so temporary settings aren't forgotten.

Global Routing isn't a standalone switch that every app can bypass. Requests may also be affected by the system network, DNS, app cache, and exceptions in the Config file. Check request logs to determine the actual route rather than relying on the selected mode alone. Browsers may reuse connections and apps may keep long-lived sessions, so after changing modes, send a new request—and close old sessions if needed—to check where the new connection goes.

Rules are evaluated from top to bottom; the first match takes effect

In Config mode, the order of rules in Rule directly affects the result. Put narrow, specific rules first and fallback rules at the end. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD matches a keyword in the domain. Keyword rules can have a broad scope, so don't put them ahead of all exact matches just because they're quicker to write.

IP-CIDR and IP-CIDR6 match address ranges. GEOIP uses the relevant IP address data; these rules are not interchangeable with domain categories. DNS results, address data, and the form of the actual request can all affect matching. If a domain rule doesn't match, check whether the request log shows a domain or an IP address and whether an earlier rule matched it. Don't infer the match from the web page title alone.

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

This is a rule snippet for learning, not a complete connection configuration. The first line sends requests matching the domain suffix to PROXY; the second selects DIRECT based on the GEOIP condition; FINAL sets the fallback policy for requests not matched earlier. Before adding it to your Config file, make a backup and confirm that the referenced policy exists. The example domain illustrates syntax; it doesn't mean every site of a particular type should use the same policy.

Policy names, fallback rules, and applying a Config file

Rule keywords determine “how to match”; the policy at the end determines “what to do with a match.” DIRECT, PROXY, and REJECT have different effects—don't change every rule to the same one just to troubleshoot. If the Config uses custom groups, rule references must match the names actually defined. A typo, missing group, or group with no available entries can prevent an apparently correct match from working as expected.

FINAL is a fallback and belongs after the rules that need to be checked. If it appears too early, later rules can't handle requests that should match them. When adding a rule, check its syntax and how its scope relates to the rules around it; a broader suffix or keyword rule may already cover the destination. Trace the actual match when troubleshooting instead of repeatedly adding duplicate rules to the end of the file.

When you've finished editing, save the file and confirm that it is the Config file actually in use. Opening a file to view it doesn't necessarily mean it's active for the connection. For rule details, see Sections in a .conf file; for how settings affect one another, see the Settings guide. Keep a copy you can restore, then make focused changes; this is usually easier to verify than replacing the whole file.

06 / DATA & OBSERVATION

Reading Data and request logs

Understand what the numbers measure; don't treat them as a bill

Data displays traffic and connection information as reported by the app; the items shown depend on the current interface. Before interpreting a number, check the time range it covers, whether it resets after reconnecting, and whether upload and download are shown separately. Different screens may track different things, so two different values don't automatically indicate a problem. A session total, cumulative total, and system per-app total are not the same measurement.

Traffic through a tunnel may include protocol overhead, handshakes, retransmissions, and background requests, so the reported amount won't exactly match the size of the files you use. Image caches, video preloading, and system background activity can also affect the totals. To check the effect of one action, note the starting value, perform a specific action, then check the ending value. Don't attribute a day's cumulative total to a page you just opened.

Traffic shown by the client isn't a substitute for usage records or billing information from your service provider. Each may use different time ranges, traffic directions, and counting rules. If subscription details show a remaining allowance, check its source and last update too. If values differ, note the time period and what you did, then ask your service provider how it calculates usage. Resetting the client counter won't change records kept elsewhere.

Use request logs to confirm which rule matched

When access doesn't behave as expected, the most useful log details are the destination, time, policy, and failure stage—not just total traffic. Send a fresh request, then find the corresponding entry by time. This helps avoid mistaking a cached result or old connection for the current one. A page may make several requests, so inspect each failure separately; success for the main domain doesn't mean every resource took the same route.

If a request shows a policy such as DIRECT or PROXY, check in Config which rule selected it. If an earlier, broader rule matched the destination, adding a more specific rule later in the file usually won't change the result. Adjust the rule order, save, and send a new request to see whether the change took effect. Long-lived sessions may keep using the old route, so check them separately from new connections.

For DNS failures, distinguish between “name resolution failed” and “connection failed after resolution.” For the first, check DNS settings, the current network, and the requested domain. For the second, also check the destination address, port, and path. Don't assume a single error message identifies every cause. The details in a log may vary by request type; a missing field doesn't prove that a step didn't happen, so consider the other available evidence.

Analyze traffic, battery, and background activity separately

Low traffic alongside high battery use isn't a contradiction. Frequent reconnects, repeated wake-ups, or an unstable network can drain the battery without transferring much useful data. Conversely, downloading a large file in a short time can increase traffic noticeably. Record usage duration, network type, and what you were doing; battery percentage and traffic volume can't be directly converted, and a single screenshot can't establish that the client is malfunctioning.

If you suspect ongoing background activity, check whether On Demand is enabled, whether apps are refreshing automatically, and whether the device is repeatedly switching networks. Compare similar conditions—for example, keep the network and usage pattern the same and change only the On Demand setting. A short test can be affected by system activity; look for a repeatable trend rather than drawing conclusions from a few minutes of fluctuation.

The system battery page may cover a different time period from Data, so align the periods before comparing. For background behavior, see On Demand and battery troubleshooting. The goal is to find unnecessary activity and failed retries, not to reach a particular number. Device models, networks, and usage vary, so there is no single threshold that applies to everyone.

For your own troubleshooting notes, keep the date, network, mode, Config name, reproduction steps, and result. You don't need to retain every request indefinitely. Brief notes are easier to compare and help limit the amount of sensitive information you store. Add detailed logs only when a problem needs further investigation, then review how long to keep them once it's resolved. Keep diagnostic tools separate from everyday use.

08 / MAINTENANCE

Subscription updates, backups, and routine maintenance

Check what actually changed after an update

Routine maintenance means keeping your connection details valid—not rebuilding everything frequently. Before updating a subscription, confirm which one you're updating. Afterward, check whether the number or names of entries changed and whether the selected entry is still available. If it was replaced or removed, select another and test it. A successful update only confirms that the list was retrieved; it doesn't test the servers. Updating a server list doesn't necessarily update your rules.

If your service provider changes an address or authentication method, check the new details they provide instead of only renaming the entry. An old address might work temporarily without remaining usable. Test the new details on your current network after importing them. Manual entries may not be changed by a subscription update, so maintain them separately. Avoid keeping multiple similarly named entries from different sources; they can make troubleshooting confusing.

Update the app through the App Store; check the store listing for update details and compatibility. Before updating, consider backing up the Config you currently use. Afterward, check permissions, the selected server, and key rules. If behavior changes, compare the actual settings and app messages instead of relying on memory about what an option “should” do. Track app, subscription, and Config updates separately to help identify what changed.

Back up with both recovery and privacy in mind

Before backing up, decide what you need to restore. A rules file alone may not include server credentials; a server list alone may not include custom groups or app settings. If you use an export or backup feature, check its options to see what is included. Give the backup a descriptive name and note the related Config and save date, but don't put a password or full subscription URL in the filename.

Backup files may contain connection credentials, so store them somewhere protected and under your control. When transferring a file through system file-sharing features or personal storage, make sure the recipient device and account are correct; don't accidentally choose a public sharing location. If you need to share a rules example, create a separate redacted copy instead of sending a complete backup. Other parts of the file may contain credentials or subscription details even if the visible rules do not.

Check that a backup can actually be restored; a successful export alone doesn't prove it's usable. At minimum, confirm that you can find the file, that its contents are complete, and that you know how to import it into the app. When migrating, keep the old device's data until you've imported the backup on the new device and checked the server, Config, and Global Routing, then tested a real request. Don't delete the only working copy before verifying the new setup.

Before changing devices, reinstalling, or returning after a long break

After changing devices or reinstalling, get Shadowrocket from the App Store purchase history for the account that bought it. The App Store listing determines purchase eligibility. Redownloading the app and restoring connection details are separate steps; a purchase record doesn't mean the Config has been restored. After importing a backup, you may also need to grant VPN permission again. Then review the active Config and On Demand conditions instead of assuming the old device's settings still suit the new one.

If you're returning after a long break, first verify the basic network, then check whether your subscription and server details are still valid. Incorrect device time, changed service details, or leftover settings may affect the connection; you don't need to change every rule straight away. Test manually with an existing valid entry, then restore On Demand and other optional settings after it works. Restoring one layer at a time helps distinguish expired details from a device configuration issue.

Before removing an old entry, check whether any group or rule refers to it and confirm that a usable replacement exists. You can clean up duplicates, but don't delete entries just because their names look similar; their protocols or settings may differ. After removing an entry, test your usual destinations to make sure no Config rules still refer to something that no longer exists. The goal is to remove ambiguity and stale details, not to minimize the list at all costs.

If a problem keeps happening, make a brief checklist: whether the app opens, whether the VPN starts, whether the subscription updates, which mode fails, and which destinations are affected. Compare it with the Connection checks and troubleshooting chapter for a more focused next step than repeatedly reinstalling. To retrace the basic setup, follow the Quick Start guide. For purchase or redownload issues, see Restoring a purchase.

Back to the guide contents ↑