01 / Subscribe
Subscribe: Add an Updatable Subscription
A subscription is a remote URL that can be requested again to retrieve content used to create server entries. It differs from a single-server share link and from a Config file, which determines how connections are routed. Before importing, identify what you have: use Subscribe for a URL that retrieves a list of servers, and import a single link beginning with a protocol name as a server. Entering a webpage, account page, or help page in Subscribe may open the address, but that does not mean its contents can be parsed.
Check the URL and label before saving
In Home, open the add menu and choose Add Server. Set Type to Subscribe, then enter the subscription URL. The layout may vary, but make sure you are saving a Subscribe entry—not a server of an arbitrary protocol. Use a label that describes its purpose, such as “Personal” or “Test backup.” Don’t put full credentials in the label. After pasting, check the beginning and end of the URL, including question marks and separators. Remove any quotation marks, line breaks, or trailing punctuation copied with it, then save and wait for the first fetch to finish.
https://example.com/sub?token=xxxxThe address above illustrates a format; it does not provide a service. The path identifies a resource, and the query string follows the question mark. Preserve parameter names and values exactly—don’t modify your own URL based on an example. A subscription URL often acts as an access credential, so anyone who can read it may be able to retrieve the associated server details. Don’t include the full URL in public screenshots, note titles, or support requests. To describe its structure, use an example domain and dummy values while keeping the punctuation in place.
What to check after the first fetch
Saving successfully and fetching successfully are two different things. Check whether servers appear under the subscription, then confirm that the entry type, label, and number of servers match what you expect. The count is only a local check, not an indicator of quality. If an error appears, note its exact wording instead of repeatedly adding the same subscription. Seeing servers does not mean you’re connected: select a default server in Home, check Global Routing, and verify with an actual request. For the complete first-connection workflow, follow the Getting Started guide.
If the fetch fails, troubleshoot the URL, network, and response in that order. Compare the address with the original and check that its credentials haven’t expired or been replaced. Then check whether your current network can reach the subscription URL. Finally, determine whether the response contains server data or a login or error page. Don’t submit the URL to an unfamiliar online parsing tool just to test it. If only this subscription fails, keep the exact error and note the circumstances. If all network requests are failing, troubleshoot the device’s network first rather than assuming several subscriptions failed at once.
Manage subscription and connection status separately
Updating a subscription fetches server details again. It does not confirm that a server is currently usable, nor should it be treated as a fix for every connection problem. If one server stops working, compare it with another from the same subscription before deciding to update. A subscription stores the remote list URL; a server stores connection parameters; Global Routing determines how requests use those parameters. Keeping these three layers separate helps identify whether to change the URL, switch servers, or check the configuration rules.
02 / Add Server
Add Server: Check Each Field
Manual entry is useful when you already have complete server details, need to verify an import, or manage a small number of standalone entries. In Add Server, choose the correct Type before filling in its fields. The type determines what each parameter means; you can’t change the protocol by entering details in an arbitrary form and renaming the entry. Before you start, record the address, port, authentication details, TLS requirements, and transport requirements separately. If anything is missing, get the complete details first. Don’t substitute a “common default” for a missing field: a saved entry may still fail to complete the handshake.
Common and authentication fields
Enter a hostname or IP address in Address and the corresponding port in Port. Don’t paste an entire share link into Address or append the port to the hostname a second time. If you have a URL with a protocol prefix, first determine whether it’s a share link or field documentation. A label is for identifying an entry; it does not affect the connection. Authentication fields depend on Type: some use Password, others UUID, and some also require a username or key. Preserve capitalization and separators when copying credentials, check for leading or trailing spaces, and don’t shorten values to troubleshoot.
| Type | Check carefully | Don’t confuse these fields |
|---|---|---|
| Shadowsocks | Address、Port、Method、Password | Method must match the server requirements |
| VMess / VLESS | UUID, TLS, transport, and related fields | UUID does not replace transport or TLS settings |
| Trojan | Password, TLS, and server name | The connection address and certificate name may differ |
| HTTP / SOCKS5 | Address, port, and required authentication | Use authentication only if the details require it |
| WireGuard | Keys, address, Endpoint, and Allowed IPs | The local key and peer public key serve different purposes |
Check TLS and transport separately
TLS handles encryption and authentication at the relevant connection layer; the transport describes how data is carried. Neither replaces the other. If your connection details require TLS, check fields such as the server name rather than simply enabling a switch. For transports such as WebSocket, also verify Path and Host. A missing leading slash in Path or a typo in Host can affect the request. Some fields appear only after you select the corresponding type. Don’t put fields that aren’t shown into the label, address, or password field.
Address, the TLS server name, and the transport-layer Host can serve different purposes: network connection, certificate verification, and request routing. They don’t have to be identical. If they differ after import, don’t automatically replace them with the same domain. Change a value only when your existing connection details specify it, and change one field at a time. For certificate errors, first check the name, device time, and completeness of the parameters. Don’t routinely disable verification: that can conceal entry errors and weaken identity checks.
How to verify a saved entry
Save one test entry with a clear label, select it, and then connect. Saving only confirms that the form was accepted; it doesn’t prove the address is reachable, authentication works, or the transport matches. Check Connectivity Test first, then make an actual request and see whether only certain destinations fail. If basic connectivity works but a specific site doesn’t, investigate rules, DNS, or the destination’s access requirements instead of repeatedly changing credentials. If other entries of the same type work, compare their fields one by one. Don’t share a full password or UUID in a public support request.
For differences between VMess and VLESS fields, see UUID, encryption, and transport explained. WireGuard has more parameters; see Private Key, Endpoint, and MTU explained. Treat manually entered entries as standalone objects; don’t expect them to change when a subscription updates. Back up important manual entries after verifying them, and note which fields came from the original details and which you later changed locally.
03 / Scan QR Code
QR Codes & Clipboard: Identify Before Importing
QR codes and the clipboard are ways to transfer text, not server protocols in their own right. The same QR code could contain a single-server share link, a subscription URL, or an ordinary webpage address. Before using Scan QR Code or importing from the clipboard, identify the kind of object you’re importing, then check the result. Skipping manual entry doesn’t remove the need to identify the content, confirm permissions, and test the connection. Import directly only when you know the source and have the complete content.
Scan QR Code checklist
Open Scan QR Code in the app to use the camera. Follow the system prompt to allow camera access, then position the entire QR code in view. Keep all edges visible, focus clearly, and avoid glare. If scanning fails, adjust the distance before assuming the code is invalid. If you previously denied camera access, check Shadowrocket’s camera permission in the device’s system settings, then try again. Recognizing ordinary text or a webpage with the system camera does not mean a server entry has been created in Shadowrocket.
If the QR code is displayed on another device, scan it directly. If it’s saved on your current device, import it from an image only if the current app screen explicitly supports image recognition. Don’t assume other system features are supported by the app. Dense, compressed, or cropped QR codes may not scan; use the original clear image or copy the original text instead. Don’t upload QR codes containing personal credentials to public scanning sites or repeatedly forward them to people who don’t need them.
What to check when importing from the clipboard
When copying, select only the link itself—not labels like “Server address:”, code fences, or explanatory text. Return to the app and use the appropriate import option. If the system asks to allow pasting, confirm that you initiated the action and choose Allow. If no entry appears, check the original text to ensure it was copied in full. A later copy may have replaced the clipboard, or a denied system permission may have prevented access. Don’t assume that a copy confirmation means the import is complete.
For multiline text, first confirm that every line is a complete object and that the current import method supports batch processing. If the text only wraps on screen, you usually don’t need to insert line breaks yourself. Actual spaces or line breaks can corrupt a URI. If only some items in a batch import succeed, keep the original text for the failed items and check their format locally one at a time. Don’t import the entire batch repeatedly to find what’s missing; that can create duplicate entries and make new items hard to distinguish from old ones.
Check the imported object and its fields
After importing, first check where the result appears. A new Subscribe entry should let you manage its URL and future updates; a single SERVER entry should expose its protocol parameters. Then check Type, Address, Port, the label, and any TLS and transport details. A label may be generated from a link fragment; it’s only identifying text, not proof that the entry has passed a test. For entries with the same name, compare their fields rather than replacing an existing entry based on its list title. Keep a working entry until the new one has been tested.
If recognition fails, separate the problem into three parts: whether camera or paste permissions are available, whether the original text is complete, and whether the text uses a format supported by the current import option. If you can read the text but it won’t parse, continue to the next section on share link formats. If it parses but won’t connect, return to the Add Server field checklist. For troubleshooting, note the import method, whether a system permission prompt appeared, the result, and the exact error. Treat the original QR image and full URI as sensitive; don’t publish them with your report.
05 / Update
Update Policies: Manage Changes and Preserve Working Settings
Updating a subscription requests its remote URL again and adjusts the local subscription entries based on the response. It may add servers, remove old entries, or change connection parameters for entries with the same name; it doesn’t just refresh labels. Before updating, identify the subscription you’re using, the server currently selected, and any local changes you’ve made to subscription entries. If you need to keep independent changes, use the app’s export or backup options first. Don’t assume remote updates will preserve local edits.
Use a manual update as a troubleshooting baseline
When you’re setting up for the first time, have changed the URL, or suspect the content is out of date, start with one manual update you can observe. Note whether you’re connected, which network you’re using, and the current state of the entries. Afterward, check for an error, changes to the server list, and whether the previously selected entry is still there. Don’t change the URL, switch networks, and retry updates all at once; even if the problem clears, you won’t know why. Observe one change at a time to distinguish a successful fetch from successful parsing and a working connection.
Automatic updates are best for subscriptions you’ve confirmed can be fetched reliably. If the current screen offers an update toggle or interval, choose one that fits how often you use the subscription; more frequent updates aren’t automatically better. Update timing may depend on the device’s network, system background scheduling, and app state, so don’t expect an exact time. If local content may be out of date after a long time without opening the app, check it and run one manual update before testing the connection. An enabled automatic-update option doesn’t guarantee the list is current.
Distinguish a bad URL from a fetch-path issue
If an update fails, first confirm that the URL is still valid and yours to use—especially if credentials were reset and the old URL is still saved. Then check whether the current network can retrieve a response. If it fails only when the connection is on or only when it’s off, record both conditions and investigate whether fetching depends on the network path. Don’t assume updates must always use one particular connection mode. Config rules and the current server state can affect the request path; troubleshoot based on observed results, not a fixed combination of toggles.
Interpret error responses in context. A connection timeout means the request didn’t complete under the current conditions; an authentication error usually calls for checking access credentials; a parsing error means the response wasn’t in the expected format. One failed update doesn’t mean every saved server is unusable, and you shouldn’t immediately delete the whole subscription. If older entries still connect, keep them and handle the update problem separately. If an error page contains personal details, record only the error type rather than publishing the full response.
Recheck selections and rules after an update
After an update, the previously selected server may have been renamed, replaced, or removed. Return to Home, confirm the default selection, retest your usual entries, and check an actual request. The same name doesn’t prove the parameters are unchanged, and a good latency result doesn’t guarantee access to every destination. If local settings refer to specific names, check whether a rename affected them. Don’t make major changes right before you need the connection; leave time to verify everything before cleaning up old entries.
Updating a subscription is different from updating the app: the former refreshes server details from an existing subscription, while App Store manages the app itself. For purchase, restoration, and compatibility information, see the App Store authenticity guide. Check the App Store listing for system requirements. Don’t assume a connection problem means the app needs an update, or that a subscription update changed how the app behaves. Identify what changed, then compare the relevant fields and request results before and after.
06 / Organize
Organizing Multiple Subscriptions: Labels, Duplicates, and Scope
When you have multiple subscriptions, the goal isn’t simply to shorten the list—it’s to make each entry’s source, purpose, and maintenance method clear. First distinguish subscription-generated entries from manually added ones, then give each subscription a stable label. Name subscriptions by purpose, such as “Daily,” “Temporary test,” or “Personal devices.” Don’t put passwords, full domain lists, or subscription credentials in a title. Labels help you choose, but don’t replace keeping track of fields. You should still be able to identify the exact subscription after a rename or update.
Use a two-level naming scheme
Use the subscription label to answer, “Which saved source maintains this group of servers?” Use each server label to answer, “Which entry is currently selected?” Remote lists may impose their own naming rules. Before renaming many entries locally, consider whether an update may recreate their names. To keep your own notes, maintain a purpose map in a private record or use a label feature explicitly provided by the current screen. Don’t rely on adding extra text to remote fields as a permanent way to manage entries.
For a temporary standalone test entry, add “Test” and a brief purpose to its label, then decide whether to keep it after verification. Don’t call every entry “Usual,” or use only sequential numbers; updates can insert entries and make those numbers misleading. Keep your currently working server unchanged while reviewing subscriptions one at a time. Don’t rename every entry, delete duplicates, and change the default selection in one operation. Processing changes in batches gives you a clear step to roll back if something goes wrong.
Don’t identify duplicates by name alone
Two entries with the same name may use different ports, credentials, or transport settings. Two differently named entries may have identical connection details. To identify duplicates, compare Type, Address, Port, authentication, TLS, and transport fields locally. Don’t copy sensitive values into a public spreadsheet. Even if the fields match, entries from different subscriptions may be maintained separately. Deleting one doesn’t guarantee it won’t reappear on the next update; first decide which subscription’s maintenance relationship you want to keep.
For duplicates within a subscription, first check whether they’re present in the remote response. If they reappear after each update, deleting them locally changes the list only temporarily. If you imported the same subscription more than once, compare the full URLs and their purposes before deciding which entry to keep. Don’t delete based on matching labels alone. Before cleanup, make sure the default server isn’t among the entries you plan to remove and have a tested alternative ready. If the current screen doesn’t clearly support bulk cleanup, handling entries individually is more predictable than using an unclear bulk action.
Treat list order and actual routing separately
Sorting makes entries easier to find. It doesn’t automatically make the first server the default or guarantee that the app will switch automatically if a server fails. After changing the display order, check the selected entry in Home. If you use a policy group in Config, check its own selection rules; server-list order doesn’t determine how the group behaves. Keep stable, frequently used entries easy to find and clearly distinguish temporary tests, so you don’t accidentally select an unverified entry in a hurry.
You can keep a private management list without credentials, noting subscription labels, purposes, local changes, and the result of the last action. Record observed facts, such as “actual request verified” or “transport field needs checking,” rather than inferring availability from a name. For more detail, see Grouping, sorting, and removing duplicate entries across subscriptions. After organizing, test a common use case to make sure the list is clearer and the connection status is still easy to explain.
07 / Connectivity Test
Latency Tests & Sorting: Understand What Results Mean
A latency test shows whether a specific connection operation completed, and how long it took, under the current network and test method. It isn’t a sustained transfer-speed measurement and doesn’t prove that a particular website or app will work. Before interpreting results, check the test method, target, and network conditions. Don’t directly rank results from different methods. A timeout is one observation, not proof that a server has permanently failed. Consider repeat tests, actual requests, and comparisons with other entries.
Compare only under consistent conditions
When comparing servers, keep the network and test method the same and test them at roughly the same time. Don’t test one on cellular data and another on Wi-Fi. Reduce obvious competing traffic, such as large downloads, and test your usual entry before alternatives. If the screen offers multiple methods, note that they may cover different stages of a connection. Establishing basic connectivity doesn’t confirm that authentication, TLS, transport, and the destination request all succeeded. A method closer to an actual request may cover more stages, but its results also depend more on the test target.
| Result | What it tells you | Next step |
|---|---|---|
| Test returns a time | The test completed using the selected method | Verify a request to the actual destination |
| One entry times out | That entry didn’t complete the test under current conditions | Retest and check the address, port, and parameters |
| All tests fail | A shared network or target issue may be involved | Check the device’s network and test conditions |
| Test succeeds, but some requests fail | Basic test results and a specific destination’s behavior differ | Check rules, DNS, and destination requirements |
Connectivity Test and real-world access complement each other
Select a server, turn on the connection, and use Connectivity Test to check connectivity. Then open a page or app you actually need. If the test succeeds but the destination doesn’t work, check whether Global Routing is set as expected, whether the relevant rule matches the destination, and whether DNS resolution works. Don’t blame every problem on the server without evidence. Conversely, if the destination works but a test fails, consider whether the test target has its own response requirements before deleting an entry that works for you.
Global Routing set to Config processes requests according to the current configuration; Proxy uses proxy routing, and Direct connects directly. When comparing results, note the original setting and change only one condition at a time. Restore the setting you need when the test is over. The routing mode affects what a result means: a page opening in Direct doesn’t prove the selected server works, and a successful request in Config may have matched a DIRECT rule. When testing a server, confirm that the request actually uses the expected route.
Recheck entries after sorting by latency
Sorting by latency only rearranges entries based on the current test. A lower value doesn’t necessarily mean a server will be more stable over time or support higher throughput. Don’t switch repeatedly just because one result was lowest. Prefer entries that perform consistently across repeat tests and work for your actual needs, and keep a verified alternative. After sorting, check which entry is selected as the default—especially in a long list or one with duplicate names. Don’t mistake the first visible entry for the one the app has selected and is using.
If a server behaves differently across networks, record the network conditions instead of changing the password. If only certain entries fail after an update, check whether their fields changed. If all entries fail at once, check what they have in common. A troubleshooting record can include the test method, network type, Global Routing setting, exact error, and actual destination behavior—but not the full subscription URL. For the first-connection checklist, see Default server, connection toggle, and Connectivity Test checklist to make sure you haven’t missed a basic step.
08 / Backup & Remove
Deletion & Backups: Confirm the Scope First
Before deleting anything, identify the object: a single server, an entire Subscribe entry, a Config file, and the app itself are different kinds of data, each with different recovery options. Deleting a server doesn’t revoke subscription credentials; deleting a subscription doesn’t cancel the remote resource. A backup should restore the local state you need while protecting authentication details—not put everything somewhere that’s easy to access publicly.
Match your backup to what you need to restore
If you only need to restore a subscription-generated list, save the working subscription URL and relevant notes. That’s usually simpler than copying each entry, but remember the URL may change later. To restore a manually added server, keep all protocol parameters or use the app’s server sharing or export options. To restore routing behavior as well, save the relevant Config separately; a server link won’t restore rules. When using a backup feature in the current screen, read its scope description instead of assuming it covers every setting.
Backups may contain subscription credentials, passwords, UUIDs, or keys, so protect them as carefully as the original details. Store them somewhere you control with access protection, and distinguish a notes-only list from a backup with full credentials. Don’t use a public share link as a long-term backup or attach complete server details to a support request. Replace real values with examples in copies used to explain a format. Keep recovery copies complete and don’t confuse the two.
Deleting one server versus an entire subscription
Before deleting a subscription-generated server, consider whether the next update will recreate it. If you want to remove the whole set of local servers, check the scope of deleting the subscription. Read the confirmation carefully and check whether associated entries will also be removed. These actions aren’t interchangeable: deleting one displayed entry doesn’t stop the subscription from updating, and clearing local data doesn’t invalidate remote access credentials that have already been exposed.
Before deleting the currently selected server, switch to another verified entry and make sure the connection still works. If it’s the only entry, prepare recovery details first instead of deleting it and figuring out what to do afterward. Test cleanup on a small set before continuing, and check the results so you don’t remove entries that share a name but have different parameters. Back up Config separately: keeping the server entries doesn’t preserve the original rules and policy settings.
Restore in order and verify your backups
To restore, first make sure the app was obtained from the App Store. For help finding previous purchases, see Restoring after changing or resetting a device. Restoring a purchase restores your eligibility to access the app; it doesn’t guarantee that servers and settings will also be restored. Next restore subscriptions or manual entries, check their fields and the default selection, then restore the Config you need and verify Global Routing. This order makes it easier to pinpoint connection issues instead of importing every backup at once and struggling to identify conflicts.
After making a backup, confirm that it can actually be read. Check that the export isn’t empty, subscription URLs are complete, standalone entries include required fields, and Config is the version you meant to keep. You can verify the backup’s scope, inspect entries, or perform a controlled import without deleting the original data. If a controlled import creates duplicates, remove the test copies only after confirming the recovery data is valid. Periodically checking that your backup location is still accessible is more reliable than simply remembering that you backed up once.
If credentials were exposed, deleting a screenshot, link, or local entry isn’t enough to address the access risk. Replace or revoke the credentials through the controls for the service you already use, then update the app and your backups. Keep a consistent maintenance routine: save a baseline before changes, verify the connection afterward, remove duplicates once testing is complete, and update the backup last. To repeat the connection setup, return to the Getting Started guide. For common questions, see FAQ: Connection toggle, Global Routing, subscription updates, and restoring purchases rather than rebuilding all your data to fix one issue.