Shadowrocket Subscription and Server Management Guide

Separate subscriptions, servers, and Config

Three object types, three different jobs

Before you begin, distinguish the three object types that commonly appear together in Shadowrocket. A server entry is a set of parameters used to establish a connection directly, usually including a protocol, server address, port, authentication details, and transport options. A subscription is an update source; after the client reads it, it can generate a group of server entries. It is useful for maintaining multiple servers derived from the same existing data. Config controls rules, policies, DNS, and related behavior: it determines which rule a request matches and whether the request is handled by PROXY, DIRECT, or another policy. Server connectivity and traffic routing are separate layers. Changing Config cannot fix an incorrect port, and repeatedly refreshing a subscription cannot repair an unsuitable rule set.

The server list shown in Home is where you choose a connection target for everyday use. Subscribe stores and updates subscriptions; Add Server adds an individual server; Config selects or edits rule configurations; Global Routing determines whether the current mode uses a configuration, proxy, or direct connection. The layout may differ on iPhone and iPad, but these English labels retain the same functional relationships. If an entry appears in a different location than described here, find the same-named item in the current app rather than clicking by screen coordinates.

Keep the original data before entering anything

Whether you use Subscribe or Add Server, first save an unmodified copy of the original data. For a subscription, record at least its purpose, complete URL, and the last confirmed working status. For an individual server, record the protocol name, host, port, authentication fields, TLS status, transport method, and notes. Do not rely only on screenshots: long URLs, capitalization, paths, and query parameters can be cut off. Do not remove characters that look unnecessary before entry either. Slashes, question marks, number signs, and percent signs in a URL may carry structural meaning; the fact that edited data can still be saved does not mean its meaning is unchanged.

Start with a small number of entries, verify them, and then expand to the full list. The recommended order is: confirm the device time and network are working, add one server or subscription, run a connection test, select the target entry, and finally check Global Routing and Config. With fewer variables, it is easier to determine whether the issue lies in the original parameters, subscription parsing, server connection, or rule-routing layer. If you have not verified the app source, see the App Store authenticity guide first. Shadowrocket is developed by Shadow Launch Technology Limited, and its app ID is 932747118.

Subscribe entry and update strategy

Verify the complete URL before adding a subscription

In Shadowrocket, open Subscribe and add a new item. You will usually enter a subscription URL and may set a name or update behavior using the fields provided. Before pasting, check for spaces or line breaks at either end. Chat apps, email, and web pages may include sentence-ending punctuation when copying long text, or may copy only an abbreviated version visible on screen. The reliable approach is to copy the complete value from the original data you already saved, then move the cursor to the beginning and end after pasting to verify it. Do not inspect only the domain in the middle.

Choose a name that describes the purpose or scope instead of vague labels such as “Subscription 1” or “New Subscription.” The name is for local organization and cannot repair the URL. If the same URL is added more than once, an update may create apparently identical server groups, making selection and troubleshooting harder. Before adding one, review the Subscribe list and confirm that no item already has the same purpose, domain, and path. Even a one-character difference in authentication parameters represents different data and should not be merged by guesswork.

Name: Workday
URL: https://example.com/sub?token=xxxx
Pre-update checks:
1. Starts with https://
2. Has no trailing space, period, or line break
3. The token parameter is complete
4. The same URL has not already been saved

Manual updates, automatic updates, and failure handling

A subscription update means that the client reads the remote content again and adjusts the server entries associated with that subscription. For routine maintenance, start with a manual update so you can observe the result: after updating, check whether the server count changed unexpectedly, whether existing notes changed, and whether the currently selected entry still exists. Retest entries you plan to use. Automatic updates are suitable once the data is stable, but do not set the interval too aggressively. Frequent requests do not improve connection quality and may keep changing the list during troubleshooting, making the same issue difficult to reproduce consistently.

When an update fails, do not immediately delete the subscription or tap repeatedly. First identify the layer where the failure occurs. If ordinary web pages also fail to load, restore the current network connection first. If only this subscription fails to update, check whether the URL was truncated, whether the device time is correct, and whether its authentication details changed. If the update reports success but the server list is empty, return to the original data and verify that the response still uses a format the client can parse. One failure does not mean every existing local entry is invalid; before deleting anything, confirm whether the current entries can still be tested and connected.

After an update, judge “refresh succeeded” and “server is usable” separately. A successful refresh only means that the client retrieved and processed the data; it does not mean every server can establish a connection. Conversely, a timeout on one server does not necessarily indicate an incorrect subscription URL. Confirm the update status in Subscribe, run Connectivity Test from the server list, and then verify an actual connection with the selected entry. Layered checks prevent connection failures from being mistaken for subscription failures.

Controlled changes before and after updates

A common challenge in subscription management is that an update can overwrite content generated by that subscription. If you edit a server name or field under a subscription directly, a later refresh may replace the local change with remote data. Keep long-term personal notes in a separate record. For experimental parameters, copy the entry to a standalone manually entered server and label it “Test copy.” The subscription remains unchanged, and the next update will not interrupt the experiment.

If many duplicate entries appear after an update, do not delete them one by one immediately. First determine whether the same subscription was added repeatedly, whether multiple subscriptions contain the same server, or whether changed remote notes only make entries look similar. Handle the first two cases at the Subscribe level; for the third, compare the protocol, host, port, and authentication fields. For a systematic approach, continue to Organizing multiple subscriptions. If an on-screen message is difficult to interpret, consult Troubleshooting under “Subscription and server import.”

Add Server fields and verification order

Choose the protocol first, then map the fields

Add Server is intended for a single server whose complete parameters you already have and want to enter field by field or use as an independent test copy. The first step is not entering an address but selecting the correct protocol type. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different authentication models. Similar field names do not make their meanings interchangeable. The interface may still let you save an incorrect type, but the connection will fail during the handshake, authentication, or transport stage.

Use a consistent order: protocol type, server address, port, authentication fields, TLS or encryption options, transport method, Path and Host, then notes. After each group, compare every character with the original data. Enter the server address exactly as provided, whether it is a domain or IP address. Do not add a protocol prefix or append the port to the address field. Enter only digits in Port. You may choose the name or note, but do not let it replace the record of the original parameters.

Authentication, TLS, and transport fields cannot be guessed independently

Authentication fields are usually case-sensitive. Hyphens in a UUID, symbols in a password, and capitalization in a key are part of the data and should not be rewritten automatically. If a connection fails after copying, delete the field and paste it again to rule out invisible spaces. Treat TLS, SNI, Host, Path, and Transport as a related group: when the original data specifies them, map each one exactly; when it does not, do not fill in values based on another server. Host and SNI may contain the same text in some configurations, but they operate at different layers and cannot be substituted arbitrarily just because the characters match.

Transport must also match the original data. After selecting a transport such as WebSocket, the interface may show additional fields such as Path and Host; these fields have meaning only with the corresponding transport. Copying a Path from another entry will not make an incompatible transport work. When editing an existing entry, confirm the protocol and Transport first, then check whether switching options left any additional fields behind. If necessary, create a test copy and fill it in from a blank state to eliminate interference from stale fields.

Minimal verification loop after saving

Save the entry when finished, but do not immediately add the rest in bulk. Return to Home, find the server you just added, and run the available Connectivity Test or latency test. Once the test responds, select the entry as the current server and check Global Routing. For the first verification, use Config and confirm that the current Config contains understandable rules. To isolate rule effects, you may temporarily compare Proxy and Direct for a clearly defined test, then restore the intended mode afterward. The three Global Routing modes are Config, Proxy, and Direct.

When a test times out, check fields in order rather than changing several options at once. Verify the address and port first, then authentication, followed by TLS, SNI, and Transport, and finally the device time and current network. Change only one item per attempt and test again so you know which change mattered. If every parameter matches exactly but the connection still fails, preserve the original entry and test record instead of overwriting the only accurate copy. For more detail on protocol basics, see Which protocols does Shadowrocket support?

Scan QR Code, clipboard, and share links

Verify the QR code content before scanning

When server information has been encoded as a QR code, use Scan QR Code to read it. A QR code is simply another way to carry text; it does not make the parameters more accurate. Before scanning, confirm that it belongs to the server data you intend to import, and avoid displaying QR codes containing authentication details in public. After recognition, do not connect solely because the import succeeded. Open the new entry and check the protocol type, server address, port, and note against your expectations.

If the QR code is displayed on another personal device, increase the screen brightness and keep the camera steady. When recognition is difficult, use the original share text rather than repeatedly cropping a blurry image. A cut-off edge, excessive compression, or an obstruction over the center can prevent recognition. A scan failure is a reading-layer problem, not proof that the server parameters are invalid. If reading succeeds but the test fails, check the parameter layer, especially the protocol type, authentication details, and Transport fields.

Handle spaces and multiline text when importing from the clipboard

Clipboard import is useful for a single share link or structured text that the app can recognize. When copying, select from the scheme identifier through the final character and avoid including explanatory text before or after it. If a message contains a title, numbering, and multiple links, copy each link separately instead of relying on the client to guess which line is valid. Clearing the clipboard after import is also prudent because share links may contain server addresses and authentication details.

Some text tools automatically wrap long URLs. A visual line break may not be a real line break, but copying from rich text can insert spaces or newline characters. If a scheme is recognized but the connection fails, paste the link into a trusted local plain-text editor to inspect its structure and compare it with the original data. Do not troubleshoot by deleting characters in the middle; missing query parameters or encoded characters may still leave a recognizable link that produces an incomplete server entry.

Share links are parameter containers, not long-term backup formats

Common share text uses a prefix to identify the protocol, followed by the address, port, authentication details, and note. Protocol structures differ, so changing one protocol’s link prefix to another does not convert it. The examples below only show how to recognize structure and are intentionally unusable. In practice, use the complete original data you already have.

ss://[email protected]:443#Example
vmess://ENCODED-DEMO-DATA
vless://[email protected]:443?type=ws&security=tls#Example
trojan://[email protected]:443?security=tls#Example
hysteria2://[email protected]:443?insecure=0#Example

A note at the end of a link usually supplies the display name and may be difficult to read after percent-encoding. This does not affect the protocol body, but take care not to damage preceding query parameters when editing manually. If the imported note is garbled, first confirm that the connection parameters are complete, then change only the local name. Do not edit the address or authentication fields at the same time. For formats such as VMess that use whole-value encoding, avoid splitting and reassembling the link manually. Import the original link instead, then verify each field on the server details page.

Share links are suitable for transferring one entry between two personal devices in a controlled setting, but they should not be your only backup. They may omit local notes, sorting, Config, and other management information, or become invalid if copied incompletely. For long-term storage, keep the original parameter notes, subscription URL records, and Config files, and document each purpose. When transferring one entry to another personal device, be mindful of your surroundings when generating or displaying a QR code, and close the display promptly afterward.

Grouping, naming, and deduplicating multiple subscriptions

Manage by source boundary first, then name by purpose

When Subscribe contains only one or two items, default names may seem sufficient. As the number grows, unclear names directly affect updates and troubleshooting. At minimum, name items by purpose, device context, or data boundary, such as “Daily primary,” “Temporary test,” or “Legacy configuration check.” Do not pack the region, protocol, and subscription purpose into one overly long name; keep details in a separate record. The goal is to know which server group an action will affect before updating.

Use each subscription as the management boundary instead of moving entries one by one in a mixed server list. Open Subscribe first and confirm each item’s URL, name, and latest manual update result; then return to the server list to inspect the entries generated by each group. If a subscription is no longer in use, first disable its update behavior or record its status, then delete it only after a period of confirmation. Immediate deletion removes both the associated entries and the basis for historical comparison, making it harder to distinguish “no longer needed” from “temporarily failed to update.”

Compare key fields when identifying duplicates

Identical display names do not necessarily mean identical servers. When checking for duplicates, compare at least the protocol, server address, port, and authentication identifier. For TLS or Transport, also compare SNI, Host, Path, and related options. Treat entries as duplicates in connection terms only when these key fields match. Conversely, different names with identical key fields may simply be the same server given different notes by different subscriptions.

When duplicates are found, trace each entry back to its subscription first. If the same subscription was added repeatedly, keep the entry with the accurate URL and normal updates, then remove the duplicate Subscribe record. If the entries come from different subscriptions, decide what to keep based on your maintenance boundaries instead of blindly deleting every entry with the same address. The same server in different subscriptions may diverge in later updates. A duplicate today does not guarantee a duplicate forever. If the goal is a clearer Home list, improve naming, sorting, and removal of inactive groups rather than damaging the subscription structure to achieve zero duplicates.

Establish a consistent maintenance routine

Multiple subscriptions do not need to be rearranged every day. A more practical routine is: name items and update them manually when added, spot-check important entries after updates, preserve test records when something looks wrong, and delete only after confirming that an entry is invalid. Sorting helps with everyday selection, but it is not a permanent verdict on server quality; network conditions, test targets, and time all affect latency. Reordering the list dramatically after every test only makes familiar positions keep changing.

Keep a short local inventory listing each subscription name, purpose, whether it updates automatically, the latest manual verification result, and its associated Config. Do not copy complete authentication details into the inventory; use it only to explain management relationships. For a new subscription that needs testing, give it a separate name and include it in the daily group only after updating, spot-checking, and verifying an actual connection. This keeps duplicate or malformed experimental data from disrupting a stable list.

Before bulk organization, avoid changing Config at the same time. If the server list and rules change together, it becomes difficult to identify which layer caused a connection issue. Stabilize subscriptions and server entries first, then check Global Routing and Config; or keep the servers fixed and test the rules separately. The goal is not the shortest-looking list, but a list whose source boundaries, update methods, and purposes can be understood again later.

Connectivity Test, latency sorting, and troubleshooting

Test results answer only the conditions of the current test

Connectivity Test and the latency test in the server list quickly indicate whether the current device, network, and moment can establish the relevant test connection to a target. The results are useful for filtering obvious timeouts and assisting with sorting, but they do not represent long-term performance for every app or traffic type. The test target, protocol handshake, congestion, and wireless signal all affect the result. A low number once does not mean permanent stability, and one timeout should not immediately justify deletion.

Before running a batch test, make sure the device is not switching networks. If it is moving from cellular data to Wi-Fi, or Wi-Fi has just reconnected, a batch test may show timeouts across the entire group. Wait for the network to stabilize and, where possible, keep the app in the foreground. If the first result is abnormal, wait briefly and test again. If only a few entries continue to time out, move on to checking their individual parameters.

Use the failure scope to identify the layer

The most useful information in test results is not one number but the scope of failure. If every server times out, check the current network, system time, and Shadowrocket connection status first. If every server under one subscription times out while others work, inspect the shared fields or data state introduced by that subscription’s latest update. If only one server times out, first verify that entry’s address, port, authentication, and transport parameters. If the test responds but the target content does not open, check the selected server, Global Routing, Config rules, and DNS instead of repeatedly editing the subscription URL.

Use sorting for selection, not as a substitute for verification

After sorting by latency, entries with faster responses in this test appear near the top. Sorting helps narrow candidates from a large set of existing servers, but verify the protocol parameters and purpose before connecting. Some entries may respond quickly yet be unsuitable for the current Config, and short-term variation may change their position between tests. First narrow the list to a few candidates, then verify each with an actual connection instead of always selecting the first item.

When batch-testing a multiple-subscription list, test groups separately so the results remain readable. After recording entries that repeatedly time out, check whether they share an address, protocol, or subscription; shared characteristics often explain more than an individual number. Before declaring an entry permanently invalid, retest on a stable network and verify that the latest subscription update succeeded. Deletion is the final step, not the immediate response to a first timeout.

When the connection works but routing is unexpected

If the server test succeeds and the main connection is active, but a domain takes an unexpected route, the issue is usually in the rules layer. First confirm that Global Routing is set to Config. In Proxy mode, requests are not routed per the Config rules; in Direct mode, the server entry does not handle the current traffic. In Config mode, check rule order from top to bottom. Confirm that a more specific DOMAIN, DOMAIN-SUFFIX, or IP-CIDR rule is not being shadowed by an earlier broad rule, and check the final destination defined by FINAL.

If every domain behaves unexpectedly, also check that Config has the intended file selected and that the policy names referenced in it actually exist. A rule can correctly say PROXY while still failing to produce the expected result if the corresponding policy has no usable server. For a complete connection-failure checklist, see Server timeout and connection failure checklist. For the shortest first-connection workflow, see First connection tutorial.

Deletion, backup, recovery, and device migration

Identify the object level before deleting

A deletion in Shadowrocket may target an individual server, an entire Subscribe record, or a Config, and each has a different scope. Deleting a manually entered server removes only that local record. Deleting an entry generated by a subscription may allow a later update to recreate it. Deleting the Subscribe record removes the update source for that group. Deleting Config affects rule selection but does not automatically delete servers. Before acting, confirm which list you are in and review the name, address, and associated purpose.

For an entry that is temporarily timing out, record or mark it instead of deleting it immediately. Before removing a subscription, save its complete URL and purpose, then confirm that no other subscription depends on the same arrangement. Before deleting Config, check whether it is currently in use and whether it contains local changes. If you later realize the deletion was wrong, accurate recovery is possible only if the original data was preserved. Re-entering a long URL or complex rules from memory easily creates new errors.

A backup should cover four categories of data

A complete management backup should contain at least four categories: subscription URL records, manually entered server parameters, Config files, and a short inventory explaining how these items relate. Saving only subscription URLs does not cover independent manual entries, and exporting Config does not automatically include all server authentication details. Before backing up, review migration-related items visible in Home, Subscribe, Config, and Settings, and handle each object separately.

If the current app interface provides Data, Import from Cloud JSON, or a corresponding import/export entry, read its on-screen description first and confirm the scope of the data it handles. Do not assume that being able to import a type of JSON restores every setting automatically. After exporting, verify that the file was created and has an identifiable name without overwriting existing data, and record its purpose at export time. Backup files and subscription URLs may contain sensitive information, so keep them in controlled personal storage.

Restore in order when moving to another device

When restoring on a new iPhone or iPad, first obtain Shadowrocket through the App Store purchase history, then restore data layer by layer. See the device migration and purchase restoration guide for purchase and restore options. Always check the App Store listing for system requirements. Once the app is ready, import one Config or keep the default state, restore one subscription and update it manually, then test one server. After the basic path works, add the remaining subscriptions and manually entered servers.

Do not import everything at once on first launch and immediately overwrite existing content. Staged recovery keeps errors within a smaller scope: if a subscription will not update, inspect only that subscription; if a server cannot be tested, verify only that entry; if routing is wrong, check Config next. If you use Import from Cloud JSON, spot-check individual items after import rather than relying only on the item count. Names, sorting, and the selected item may differ from the old device without indicating lost parameters.

Run three rounds of checks after recovery. First, confirm that Subscribe can update manually. Second, test Connectivity Test and an actual connection for the main servers. Third, with Global Routing set to Config, verify that commonly used domains reach the expected policies. Then check automatic connection behavior such as On Demand, so it does not introduce extra variables before basic connectivity is confirmed. Keep the old device’s data until the new device has passed stable verification, then handle it according to your personal data-management plan.

Create records that can be restored, not merely saved

A useful backup is not defined by the existence of a file but by whether it explains how to restore it. Document the purpose of each Config, the corresponding name for each Subscribe entry, the field checklist for each manually entered server, and the verification steps after recovery. If you only save an unexplained long link, months later it may be unclear whether to add it to Subscribe or import it as an individual server, or whether it is still within your current scope.

After an important configuration change, save a new copy, but do not fill storage with many near-identical files. Keep three states such as “Current stable,” “Before changes,” and “In testing,” and never put authentication details in filenames. Once an experiment succeeds, make the verified version the current stable copy; if it fails, return to the before-changes copy. This versioning method manages personal data and does not depend on the app’s displayed version or lose its value when the interface changes.

Config, Global Routing, and rule-based routing

Understand the three Global Routing modes

Server management ultimately needs to work with traffic policy. The three Global Routing modes—Config, Proxy, and Direct—mean different things. Config evaluates requests against the rules in the selected configuration. Proxy sends requests through the current proxy policy. Direct connects requests directly. Use Config for everyday rule-based routing. Proxy and Direct are better for clearly defined comparison tests, such as determining whether a problem comes from the rules layer; restore the intended mode when testing is complete.

Rules use first match from top to bottom

Rules in Config are usually processed in the order written. Once a request satisfies a rule, the specified policy is applied and later rules are not considered. More specific rules should therefore come before broader ones. For example, a single DOMAIN rule should appear before a wider DOMAIN-SUFFIX rule, and a local-network IP-CIDR rule should appear before FINAL. FINAL catches requests that did not match earlier rules and is normally placed at the end of the rule list.

DOMAIN matches a complete domain name exactly. DOMAIN-SUFFIX matches by domain suffix. DOMAIN-KEYWORD matches a keyword in the domain and is usually broader. GEOIP uses the geographic database result for the destination IP. IP-CIDR and IP-CIDR6 match address ranges. USER-AGENT matches the request identifier. PROXY, DIRECT, and REJECT on the right side of a rule are handling policies, not server protocol names. PROXY must resolve to an available policy or server; DIRECT means a direct connection; REJECT denies the request.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-SUFFIX,apple.com,DIRECT
DOMAIN-KEYWORD,media,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fe80::/10,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

The examples demonstrate syntax relationships and are not suitable for every network environment. Check an actual Config against your own goals and existing configuration. Copy the original file before editing, then change only a small number of rules at a time. Moving many rules, renaming policies, and changing DNS simultaneously makes failures nearly impossible to locate. Start by adding one specific DOMAIN rule to verify matching, then gradually expand to DOMAIN-SUFFIX or other broader types.

Keep server names, policy names, and rule targets aligned

Writing PROXY at the end of a rule does not make every server available automatically. Policy names in Config must correspond to actual policy structures, and those policies must have usable servers available. If a subscription update changes server names, policies that refer to specific names may need review. A more stable approach is to point rules to clear policy names and let those policies manage server selection, rather than scattering specific server names across many rules.

When Connectivity Test succeeds but rules do not take effect, check in this order: Is Global Routing set to Config? Is the intended Config selected? Was the target domain matched by an earlier rule? Does the policy name at the end of the rule exist? Does that policy contain a usable server? Does FINAL appear too early? You can temporarily add a narrowly scoped DOMAIN rule to verify matching, then decide whether to expand it. Do not refresh every subscription during troubleshooting, as changes to the server list can interfere with rule testing.

Editing, importing, and rolling back Config

Keep an original copy before editing Config and give test copies clear, recognizable names. After importing a new configuration file, check section names, rule blocks, and FINAL, then test a small number of known domains. A file being importable does not mean every policy reference works; parseable syntax and executable policies are separate checks. If the app reports that a policy name cannot be resolved, return to the configuration and verify its spelling and associated group.

Rule debugging should always have a rollback path. Before each change, record the current stable copy. After editing one group of rules, test immediately and note the purpose of the change. If the result is wrong, restore the previous stable copy instead of layering on more temporary rules. Do not simply concatenate two complete Config files from different sources: shared sections, same-named policies, duplicate FINAL rules, and different DNS settings may overwrite or conflict with one another. If a merge is necessary, understand and process each section separately, validating at every stage.

After server and Config management are complete, daily maintenance can follow a fixed routine: update Subscribe as needed, spot-check key servers, keep names clear, connect in Config mode, and when something fails, locate it across the four layers—network, subscription, server, and rules—while saving copies before important changes. For only the first-connection steps, return to the Shadowrocket setup tutorial. To browse issue categories, open Troubleshooting.