Official Manual / Settings Reference
Shadowrocket Settings Guide
Check settings by their source, then verify the results with real requests.
For your first connection, start with the Quick Start Guide to import an existing subscription, select a server, and verify the connection. Use this page afterward to understand settings, confirm their scope, and troubleshoot issues. You do not need to change every option.
01 / Configuration Sources
Config and Global Routing
Before deciding whether a Settings option applies, identify the Config currently in use. Shadowrocket’s connection results are not controlled by a single switch: the server selected in Home provides connection parameters, Config contains rules and related settings, Global Routing determines the routing mode, and the system network provides basic connectivity. An existing subscription is typically used to maintain server entries; it is not the same as a configuration file used for routing. A successful subscription update does not mean that rules or DNS settings have also changed.
Distinguish Config, Proxy, and Direct
In Global Routing, Config, Proxy, and Direct select three different routing modes. Config processes requests according to the rules in the active configuration; Proxy routes traffic in proxy mode; Direct routes traffic directly. These describe routing intent, not a guarantee that every request will succeed or that the app handles every connection on the system. When troubleshooting, note the current mode. Otherwise, you might edit rules while Proxy is selected and mistakenly conclude that the rules were not saved.
| Mode | Purpose | What to verify |
|---|---|---|
| Config | Route according to the active Config | The rule and policy matched by the request |
| Proxy | Check the proxy path | Whether the selected server can connect |
| Direct | Check the direct path | Whether the current network can reach the destination directly |
Rule order matters more than rule count
Rules are typically checked from top to bottom, and the first match determines the next policy. DOMAIN-SUFFIX matches a domain and its subdomains; GEOIP matches based on the destination address and its geolocation database result; FINAL catches requests that did not match earlier rules. A broad rule placed too early may prevent a more specific exception below it from taking effect. When editing, find the entries related to the target domain and review the rules above them. Do not just check whether a seemingly correct line appears at the end of the file.
[General]
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
This example illustrates the structure; it is not a complete configuration for every network. example.com is a sample domain. PROXY and DIRECT are policy keywords, not server addresses. The domain rule checks the sample domain first, GEOIP handles matching addresses, and FINAL catches what remains. Before using a real configuration, confirm that an existing server works and review each rule for your needs. For more on matching behavior, see How to Write DOMAIN-SUFFIX, GEOIP, and FINAL Rules.
Defaults and a Recommended Baseline
Check the current installation and selected Config to determine the defaults. Importing a configuration, restoring data, or switching configurations can change what you see. For everyday use, select Config after you understand its rules. Proxy and Direct can help isolate issues, but remember to restore the original mode after testing. To establish a baseline, record the Config name, selected server, Global Routing mode, and one test request. This makes it easier to identify the cause of later changes.
Saving a file and applying its settings are two separate things to verify. After editing, confirm that the changes were saved and that the file is the active Config. Then follow the app’s prompts for the connection state. Existing connections may continue using their original path, so start a new test request instead of watching a page that has been open all along. If the result is still unexpected, check the request record in Log rather than importing the same content again.
If a server test succeeds but a particular domain fails, first distinguish server reachability from rule matching. Check the full domain in the request, including subdomains, redirect domains, or different address families, then review the matched policy. If all requests fail, start with the connection and server parameters. If only a particular type of request fails, narrow the search to rules and DNS. To repeat the initial connection setup, return to the Quick Start Guide. Resetting every setting at once can hide the cause.
02 / Name Resolution
DNS Settings and Resolution Paths
DNS translates domain names into addresses that can be used to connect. It is not a proxy server and does not determine the route for every request. Before troubleshooting DNS, identify what failed: a domain that will not resolve, a connection failure after an address is returned, and a page whose main document loads but whose additional resources fail are different problems. Only the first clearly points to name resolution. The others may involve routing, the server, the destination service, or connection logs. Do not assume every page that fails to open has a DNS problem.
Check the DNS Settings in the Active Config
DNS behavior may be defined in the active Config, not just in a Settings screen. Open the current configuration and check for an explicitly specified resolver, domain mapping, or related option, then compare it with the state shown in the app. An unspecified setting does not produce the same result on every network: system-provided DNS conditions can change between Wi-Fi, cellular, and different network access states. This guide does not prescribe one DNS address for every device.
In a configuration, dns-server = system means to use the DNS provided by the system. It is a useful baseline example when identifying where a setting comes from, not a claim about the app’s factory defaults in every situation. If an existing Config explicitly specifies a resolution method, understand its original design before changing it. Do not paste this line at the end of a file: it belongs in the relevant configuration section, and duplicate definitions can make the file ambiguous. Keep a complete copy before editing so you can restore individual settings.
Evaluate DNS Transport and Request Routing Separately
The difference between conventional DNS and encrypted DNS is how resolution requests are transmitted; neither guarantees correct results or successful access. Encrypted DNS also requires a connection to the resolver. If the resolver’s address is a domain name, resolving that name may itself be a prerequisite. Overly complex settings can create a troubleshooting loop: the service domain needs resolution, while the resolver depends on a path that is not yet available. If this happens, first return to a simple, verified baseline.
| Symptom | Check first | Does not prove |
|---|---|---|
| No destination address returned | Resolver and its reachability | That server credentials are incorrect |
| Address returned, but connection times out | Route, server, and destination port | That resolution is definitely wrong |
| Issue after switching networks | Network access, cache, and address family | That the entire configuration must be replaced |
IPv4, IPv6, and Cache Limitations
A domain may return both IPv4 and IPv6 addresses. Resolving one address family does not mean the current network or selected server has a working path for it. If requests consistently fail for one address family, use Log to identify the address actually being connected to, then check the network conditions. Disabling an address family is not a universal recommendation: it may temporarily make one test pass while hiding the underlying path issue, and may affect other requests that were working.
Caching can make a change appear to have no effect, but Shadowrocket is not the only place that caches results. The system, browser, app, and upstream resolver may all retain results, and existing connections may not perform a new lookup. For a fresh test, close the original connection and send a new request. If the app offers a relevant cache-clearing option, first check what it clears. Repeatedly clearing data in multiple places adds work and removes useful evidence for comparison.
Recommended Settings and Verification Steps
If you do not have a specific DNS requirement, keep the settings in your current working Config. When an adjustment is necessary, use only a resolver whose purpose and reachability you have verified, and change one setting at a time. Record the original configuration, target domain, returned address, matched policy, and connection result, then retest on the same network. Comparing page load times without confirming that a DNS lookup occurred cannot tell you whether the change affected DNS, caching, or the destination service.
Resolution performed inside an app, existing connections, and different request methods can make diagnostic results differ from what a particular app shows. For a more reliable comparison, keep the network, Global Routing mode, and server the same, and test the same destination repeatedly. If DNS returns a reasonable address but access still fails, continue with the Log and Proxy ports sections instead of repeatedly changing resolver addresses. You can also look up common connection symptoms in the FAQ.
03 / Connection Triggers
On Demand Connections
On Demand triggers VPN connections based on conditions; it is not another way to write routing rules. It answers “when should a connection be attempted?” Global Routing and Config answer “how should requests be handled after the connection is established?” Turning on On Demand will not fix incorrect server parameters or choose suitable rules for you. First verify that an existing server works with a manual connection, then consider letting conditions trigger that verified connection.
Check the Current Configuration for the Default State
Do not infer the default On Demand state from a screenshot of another device. A fresh installation, system data restore, VPN configuration added again, or changes to in-app conditions can all affect what you see. Check the switch and conditions in Shadowrocket, then verify the corresponding configuration in the system’s VPN settings. If the device has multiple VPN configurations, make sure you are changing the one used by Shadowrocket, not an older entry.
When connecting for the first time, the system may ask for permission to add a VPN configuration. This authorizes the system to register the connection configuration; it is not a purchase confirmation and does not mean the server has been verified. Read the system prompt and confirm its source before proceeding. If you cancel, return to the app and follow its prompts to try again. Do not delete other system configurations without understanding the impact. Managed devices may also have restrictions that require an administrator.
Set Conditions Based on Your Network, Not Guesswork
If the current interface offers conditions such as Wi-Fi, cellular, or a specified network, read what each one triggers before enabling it. Recognizing a Wi-Fi name does not establish every property of that network or guarantee internet access as soon as you connect. Public networks may require an access confirmation, and network names can be duplicated. Start with simple, understandable conditions, then add exceptions only as needed instead of creating many overlapping conditions at once.
During testing, observe at least three stages: whether joining a network meets the condition, whether the system attempts to connect, and whether the target request succeeds after connection. An enabled switch does not prove the final stage worked. Record the network type and time before and after switching, then check the app state and Log. If the trigger works but the request fails, investigate connection parameters and routing instead of changing the trigger conditions. This keeps issues at different layers from obscuring one another.
Manual Disconnects and Subsequent Triggers
With condition-based triggering enabled, a manual disconnect may not stay disconnected. The system may try to reconnect when the conditions are met again. To pause automatic behavior temporarily, pause On Demand first, then manage the current connection and confirm its state in the system. If a connection returns right after you disconnect, check whether the conditions are still active before assuming the switch is broken. Restore the conditions you need after testing.
| Test stage | Action | What to look for |
|---|---|---|
| Manual baseline | Pause condition-based triggers and connect manually | The target request succeeds |
| Condition trigger | Enable just one clear set of conditions | The system attempts to connect |
| Network switch | Switch to a different, real network | Conditions and connection state match |
Sleep, Network Changes, and Recovery
Device sleep, switching between Wi-Fi and cellular, or a brief loss of network access may interrupt or re-establish an existing connection. On Demand cannot prevent these underlying changes and should not be described as a guarantee of a continuous connection. If access briefly fails after switching networks, wait for the system to finish connecting, then check for a reconnect record. If the network itself is not available yet, repeatedly toggling the app switch usually just creates more failure records.
The right settings depend on how you use the connection. If you need automatic triggers, enable only the necessary conditions after the manual baseline is stable. For a controlled troubleshooting setup, temporarily pause condition-based triggers so each test corresponds to one connection attempt. “Enable everything” is not a universal recommendation. There is no single setting for every device that balances battery use, background activity, and connection stability; assess them using real usage records.
If the issue occurs only with automatic triggers, keep a record of one successful manual connection and one failed automatic connection, then compare network conditions, selected server, and active Config. If the conditions match but the results differ, check the system configuration and app state one at a time. To repeat the authorization and connection checks from the beginning, follow the main tutorial. Do not change DNS, rules, and protocol type at the same time just to test On Demand.
04 / Reachability Tests
Ping and Connectivity Test
Ping and Connectivity Test provide results for specific test conditions, not a complete assessment of server quality. A test can tell you whether a probe completed within a given time, but it cannot replace a real request. A low value does not mean every page will load faster, and a timeout alone does not prove the server configuration is invalid. Before interpreting a result, confirm the test method, target, and current network.
Know Which Part of the Connection Was Tested
Different test methods cover different connection stages. A basic reachability probe, an attempt to connect to a specified port, and accessing a destination through a proxy have different dependencies. Check the options in the current app interface; do not assume that a test uses a particular protocol just because it is called “Ping.” Knowing which stages the probe covers tells you what a pass or failure can—and cannot—rule out.
For example, successfully connecting to a server port does not prove that authentication, TLS negotiation, and access to the destination will also succeed. Successfully accessing a test target through a proxy proves only that the target was reachable at that time. A server may allow one type of probe but restrict another, and the test target itself may be temporarily unavailable. So if a test passes but a webpage will not open, check the real request in Log instead of rerunning the speed test.
Default Target, Timeout, and Concurrency
Check the default test target, timeout, and concurrency settings on the current device; restored settings may differ from the initial state. If you do not have a specific issue to solve, keep the app’s current test settings. If you need another target, choose one whose purpose you understand and whose reachability you can verify on the current network. Do not use an address containing login details or a private token as a test target, and do not treat one service’s result as a verdict on every service.
A timeout sets how long the test waits; it does not give the connection more bandwidth. A setting that is too short may classify temporary fluctuations as failures, while one that is too long slows down batch checks. Excessive concurrency can also strain limited network resources, making tests compete with one another. Establish a baseline with a few servers and the same test target, then adjust only as needed. Do not keep changing every setting in pursuit of a lower number.
| Observation | What it may mean | Next step |
|---|---|---|
| One timeout | The probe did not complete before the deadline | Retest under the same conditions and check Log |
| Large fluctuations | Network, load, or target conditions changed | Reduce concurrency and keep multiple results |
| Test succeeds, but the service fails | The probe did not cover every stage of the request | Check the real request and matched policy |
Compare latency, throughput, and stability separately
Latency measures the wait for an interaction; throughput concerns sustained transfer capacity; stability requires observing failures and fluctuations over time. They are related but not interchangeable. A webpage also involves stages such as DNS, connection setup, encryption negotiation, server processing, and resource loading. A single probe covers only some of them. When selecting a server, consider the tasks you actually need to perform rather than ranking servers by just one number.
A more useful comparison controls the conditions. Keep the device, network, target, and test method the same, and record multiple results and failures. After switching between Wi-Fi and cellular, treat the results as a separate set rather than combining them with the earlier data. If background syncing or large transfers are running during a test, note that too; otherwise, you cannot tell whether fluctuations came from the server or competition on the local network.
What to Check When a Test Fails
If every server fails at once, first check whether the device is actually online, the network still requires access confirmation, and the test target is available. If just one entry fails, check its address, port, and protocol parameters. If a subscription was recently updated, confirm that you are testing the current updated entry, not an older manually retained copy. Different protocols require different parameters. Do not change a protocol type at random just to make a test pass.
Run one set of tests under the same conditions before and after an adjustment, then verify the result with a real request. If the number improves but the actual issue does not, do not treat the adjustment as a fix. For help checking Trojan authentication and TLS fields, see Password, SNI, and Allow Insecure Settings. Use existing server information to set protocol fields; a failed test is not a reason to weaken certificate verification.
Keep a reproducible record: test time, network type, entry name, method, target, and result. You do not need to expose passwords or subscription addresses; use a label you can recognize. This is more useful for troubleshooting than “sometimes fast, sometimes slow,” and helps determine whether a change produced a repeatable improvement.
05 / Request Evidence
Log and Connection Troubleshooting
Use Log to break a connection issue into stages you can check—not to react to one error word by changing every setting. A request may fail during resolution, rule selection, server connection, authentication, TLS negotiation, or destination response. Find the record that corresponds to the operation you performed, then identify the failing stage before deciding whether to change DNS, Config, or server parameters. The level of detail varies by screen; refer to what the current app displays.
Default Logging and When to Enable It
Check the logging switch, detail level, and save behavior on the current device instead of assuming the defaults are always the same. For everyday use, keep logging at a level that supports basic checks. Increase the detail only when reproducing an issue, then restore it afterward. More detail means more records to review and may expose more request information. Enabling logging does not recover past requests, so plan the test before sending the target request.
Keep a useful reproduction short. Note the current time, network type, Global Routing mode, Config, and selected server. Then access the target once and check the relevant records right away. Do not open many apps or repeatedly reload pages; background connections can bury the request you are investigating. If the app offers filters or search, narrow the results by domain, time, or connection details, but do not assume a vague name identifies the right connection.
Follow the Connection Stages, Not a Guess Based on Keywords
Start with the request domain or address, then check the selected policy and server. If the request matched DIRECT but you expected PROXY, return to Config and review rule order; changing the server password will not help. If the policy is as expected, check whether resolution completed and whether a connection, authentication, or handshake error followed. The absence of a stage in Log does not prove that it did not happen; the current logging detail may not display it.
| Stage | What to check | Where to look first |
|---|---|---|
| Rule selection | Domain, address, and matched policy | Config、Global Routing |
| Basic connection | Server address and port reachability | Network and server entry |
| Authentication and handshake | Credentials, time, and TLS name | Corresponding fields in Add Server |
| Destination response | Whether the destination returned a valid response | Destination service and real request |
A connection timeout means the wait exceeded its deadline. It may be caused by an unreachable path, an inaccessible port, or no response from the remote end; it does not identify the cause by itself. For authentication errors, first check the credentials provided for the existing server, including spaces and whether each value is in the right field. For TLS errors, check the server name, certificate, device time, and other relevant conditions. Do not treat enabling Allow Insecure as a general fix: it changes the scope of certificate verification.
Data and Log Serve Different Purposes
Statistics in Data and request details in Log serve different purposes. Statistics can show traffic changes over a period, but cannot explain on their own why a particular page failed. Request records can help identify a stage, but may not represent a complete account of business traffic. Do not use app statistics as the billing basis for an existing service either; the metrics, time ranges, and calculation methods may differ. For troubleshooting, use the type of evidence that matches the issue.
If a foreground page fails and you cannot find a corresponding record, first check whether it used the expected connection method, reused an old connection, or made the request before logging was enabled. Then confirm the request’s actual domain: redirects and page resources may use different names. Do not assume a request did not go through the app just because searching for the page title returns nothing. Logs are generally organized around network connection details, not visible webpage titles.
Exporting, Redacting, and Restoring
Logs may include domains, IP addresses, network names, and connection identifiers, so review them before exporting. Do not publicly share subscription addresses, authentication fields, or other reusable connection details. Even a short excerpt may contain sensitive values in its surrounding context. The error stage and field structure are usually enough to explain the issue; you do not need to include the full configuration. The example.com used in this guide is not a substitute for manually redacting real records.
After making a fix, repeat the operation that originally failed and confirm that the new record shows the expected path. If the error disappears but the request now uses a different policy or server, note that the conditions changed; this does not by itself prove the original issue was resolved. If you still cannot identify the cause, use the FAQ troubleshooting categories to narrow it down. For domain rejection policies, see What REJECT Does and Where It Applies so you do not mistake an intentional rejection for a network failure.
06 / Listening and Remote Connections
Proxy Ports and Protocol Parameters
First identify what each port belongs to. The remote port in Add Server is part of the connection details for an existing server. A listening port in local Proxy settings is an entry point on the device. A business request also connects to a port on the destination service. Even if the numbers happen to match, these are separate settings. Changing the local listening port will not fix an incorrectly entered remote port, and changing the remote port will not make a disabled local entry available.
Enter Remote Parameters from Existing Server Details
Check the server type, address, port, and authentication fields as a set. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard, HTTP, and SOCKS5 have different parameter structures; there is no universal set of fields that applies to every protocol. Choose a type based on the instructions for an existing server, then enter each value accordingly. Do not guess unfamiliar fields based on another protocol or switch types just because one looks more familiar.
A port number identifies only part of the connection target; it does not establish the protocol type or TLS status. Two services can use the same common port but require entirely different authentication and transport settings. For TLS configurations, check the server address separately from the field used for name validation; do not assume they are always the same. See Trojan Parameter Guide for field details instead of guessing by trying different passwords.
| Port belongs to | Value comes from | What changing it affects |
|---|---|---|
| Remote server | Details for an existing server | Entry point for connecting to the server |
| Local Proxy | Current app settings and the calling app’s configuration | Proxy entry point available on the device |
| Destination service | Destination service and address | Entry point for the final request |
Local Listening Defaults and Recommendations
Use the current app interface to check available local Proxy features, listening addresses, and ports. This guide does not prescribe a fixed default port or require copying values from another device. If you do not have a specific need for local proxy access, keep the existing settings and do not enable a listener just to troubleshoot regular webpage access. If you do need to change one, record the original value and update the address and port in any app that uses this entry point.
A valid port must be considered together with its listening address and protocol type. A loopback address usually allows access only from the same device, while a local network address involves other devices on the network; broadening the listening scope changes who can access it. If the interface offers a local network access option, enable it only when you understand why, and check the network environment. Do not broaden access just to make a test pass, and do not confuse a system VPN configuration with sharing a local network proxy.
Port Conflicts and Mismatched Connection Types
If a calling app reports that it cannot connect to a local proxy, first confirm the corresponding entry is available in Shadowrocket, then check the listening address, port, and protocol. HTTP and SOCKS5 proxy entries work differently, so the calling app must use the matching type. Sending an arbitrary request to a port does not test every protocol. If you suspect a port is in use, check the error shown in the current interface instead of repeatedly changing remote servers.
Changing a listening port does not automatically update its callers. A browser, test tool, or other app with proxy settings may still have the old connection address. Stop the old test, update the calling app, and reconnect. If you have both a system-level connection and a separate in-app proxy setting, identify which path the test uses. Otherwise, overlapping settings can make the results difficult to interpret.
Handle Connection Parameters and Security Checks Separately
For VMess and VLESS, check the UUID, transport, and related fields against the existing server details rather than relying on the name; their parameters differ. WireGuard has its own keys, peer, and address settings, so do not treat it as an entry with just a password and port. For more, see VMess vs. VLESS and the protocol glossary. These links explain fields; they do not provide connection resources.
A recommended troubleshooting sequence is to verify that the device is online, check the remote details, review protocol authentication and handshake, and only then check a local listener that is actually involved in the test. After each change, retest the same destination and confirm the path in Log. If an existing subscription updated its port or authentication details, make sure the selected entry is current. Do not mix an older manual copy with the updated subscription entry. Without evidence, keeping the current settings makes the cause easier to isolate than changing several ports at once.
07 / Status Access
Widget and System Status
A Widget is a shortcut for viewing status or triggering actions provided by the app; it is not a separate connection engine. What it can display or do depends on the system, the components offered by the app, and the selected Widget style. Do not assume your device has the same buttons as another device, or treat a status shown in a Widget as proof that a target request succeeded. To verify the connection, return to Home and send a real request.
Establish an In-App Baseline Before Adding a Widget
First select a server, confirm Global Routing, and verify a manual connection in Shadowrocket. Then add a Widget. A Widget cannot replace the initial import or supply missing authentication details. If a related action requires authorization in the foreground, return to the app and follow the prompt. Repeatedly tapping the Widget cannot skip steps that must be completed in the app, and may make multiple state changes harder to distinguish.
The system’s editing interface determines where you can add a Widget and its size. Select Shadowrocket, review the descriptions of the available styles, and choose one that suits what you need to see. This guide does not specify a fixed size or layout because available options vary by device and system. After adding the Widget, check that its static information matches Home, then test any available actions. Do not conclude it has failed before it has had a chance to display the initial state.
A Refresh Delay Does Not Mean the Connection Failed
Widgets depend on the system’s refresh schedule and may not update immediately after every connection change. Background activity, power-saving conditions, and system scheduling can all affect when they refresh. If the Widget and in-app status do not match briefly, open the app to check and confirm with a real request. Removing and re-adding a Widget is only a display-level workaround; it should not be the first step for every connection issue or replace checking the actual connection logs.
| Where to check | Useful for confirming | What else to verify |
|---|---|---|
| Widget | Shortcut or Widget display | Current in-app status |
| Home | Selected entry and connection action | Result of a real request |
| System VPN status | System connection configuration status | Rule and server availability |
| Log | Request stage and policy details | When the user performed the action |
How It Interacts with On Demand
If On Demand is active, disconnecting from a Widget may be followed by another connection attempt when the network conditions are met again. This does not mean the Widget has a separate hidden setting; the condition-based trigger is still in effect. To test a single Widget action, pause On Demand first, then check Home and system status before and after tapping. Restore the original conditions when testing is done. Changing both automatic triggers and the Widget layout at once makes it hard to tell what changed the result.
Similarly, after changing the selected server or Config, the Widget may need to refresh before it shows the update. Use the in-app selection as the source of truth, then wait or refresh it in the normal way provided by the system. If tapping the Widget opens the app, check the result in the foreground rather than judging by whether the system screen closed. A shortcut saves steps to open the app; it does not reduce the conditions needed to verify a connection.
Displayed Information and Privacy
A Widget may appear somewhere others can see. If it shows a server name or connection status, avoid including private account details, usage notes, or reusable connection information in the name. Check the Widget area before sharing a device screen, not just the app window. A Widget is not a secure way to store subscription credentials; do not put a complete subscription address in an entry name for convenience.
For everyday use, show only what you need and use a recognizable, non-sensitive name in the app. Not adding a Widget has no effect on a configured manual connection if you do not need a shortcut. If the display looks wrong, first note the differences between the in-app status, system status, and Widget, then check whether the system still has the Widget. Consider re-adding it only if the issue is limited to the display; do not reset network settings.
Distinguish three common issues: if the Widget has not refreshed, check its display; if its action did not complete, check whether foreground authorization is needed; if the connection is established but access fails, return to DNS, Config, and Log. This sequence avoids repeatedly disconnecting a working connection because of an outdated status display. If the issue occurs only after switching networks, review condition changes in the On Demand section. If the initial connection is not complete, return to the tutorial first, then set up a shortcut.
08 / Data Recovery
iCloud Sync and Restoring Settings
iCloud features sync or restore data within the scope supported by the app; they do not guarantee identical state on every device. Check the current interface for supported data, switches, and instructions before enabling them. Server entries, configuration files, system VPN authorization, the current network, and connection state are separate layers. Syncing one type of data may not sync the others, which may still need to be checked on the destination device.
Default State and System Requirements
Check the current app and system settings to determine the default sync state. Before using it, confirm that the device is signed in to the intended Apple Account, the system permits the app to use the relevant iCloud features, and the network can complete the sync. An enabled switch does not prove that data has finished uploading, and content not yet appearing on another device is not a reason to import it again immediately. Check both the app records and system interface, since syncing depends on system state.
Getting the app and restoring its configuration are separate steps. On a new device, get Shadowrocket from the App Store first, then handle data and initial connection authorization. Check the App Store page for system requirements, device compatibility, and purchase availability. For how to verify the official listing, see How to Verify the Official App; for restoring a purchase, see Getting Shadowrocket Again on a New Device. Sync capabilities do not establish purchase availability across devices; check each separately.
Choose a Primary Device Before Making Changes on Multiple Devices
Before enabling sync, decide which device has the complete configuration you want to keep and save a clearly identifiable copy. Do not edit the same important content on two devices at once and assume the system will merge the changes as you intend. If the devices already have different versions, compare the files and entries before choosing which to keep. Sync is not a substitute for reviewing changes. Do not batch-delete duplicate entries until you have checked what they do.
Use clear names to distinguish your everyday Config, test copies, and restore copies, but never include passwords or subscription tokens in names. After restoring to a new device, check the entry count, key fields, and Config contents before selecting a server and Global Routing mode. Entries with the same name can contain different internal fields; the list title alone cannot confirm a complete restore or prove that the server still works.
Sync, Backup, and Subscription Updates Are Different
Sync may propagate changes to other devices, so it is not the same as a backup that permanently preserves an older state. Subscription updates retrieve entry information from an existing subscription; they do not determine how to merge local edits. To preserve a configuration long term, use the export or backup options available in the current app and save a separate copy. Know where it is stored and who can access it. Before deleting cloud or local data, confirm that the copy is readable.
| Action | Main purpose | What to check afterward |
|---|---|---|
| iCloud sync | Transfer data within the supported scope | Content and current selection on the destination device |
| Configuration backup | Keep a restorable copy | File readability and what was saved |
| Subscribe update | Refresh information from an existing subscription | Current entries and manual changes |
| App Store restore | Get a previously purchased app again | Account and store purchase status |
New Device Checks and Sensitive Information
After restoring, run the minimum verification sequence again: confirm the device is online, check the selected entry and Config, complete VPN configuration authorization if prompted by the system, and send one real request. Test On Demand only after the manual baseline works; check the Widget only after the in-app state is correct. This helps distinguish missing data, incomplete authorization, and an unavailable server, rather than blaming the entire sync process for one failed connection.
An exported configuration may contain server addresses, passwords, keys, or subscription tokens; protect it like connection credentials. When sending diagnostic information, include only the necessary structure, not the complete file. This guide makes no claims about encryption methods or retention periods for specific synced data beyond what the current interface states. To understand data handling, also read the Privacy Policy and the relevant information provided by the system. Before deleting anything, check whether the action affects other devices.
To restore a previous state, first pause any operation that is continuing to make changes, then restore a verified copy and review DNS, On Demand, test settings, and the current routing mode one by one. Do not start by restoring every default; that can erase clues about the cause. Keep a short change log with the setting, old value, new value, and verification result. If an issue returns, starting from the last known working state is more useful than trying every setting again.