Shadowrocket
Subscription & Server Management Guide

First, distinguish the URL, subscription record, and servers

A subscription URL retrieves a collection of servers. A subscription record is the source and update settings Shadowrocket saves. Server entries are the connection targets that appear in Home after the subscription is parsed. These are separate things: copying a subscription URL does not create a record, and creating a record does not guarantee that it will return usable servers. When troubleshooting, identify which layer has the problem instead of mistaking a download failure for a failure of every server.

Subscriptions often contain access credentials. Even if a URL looks like an ordinary HTTPS link, anyone who has it may be able to view your server details. Before you begin, save the original URL somewhere private and confirm it came from your own subscription information. Don’t paste the full URL into public comments, search boxes, or screenshots. example.com in this guide is for illustrating the format only; it won’t connect to a server and doesn’t need to be visited.

Choose Subscribe from Add Server

Go to Add Server from Home, check Type, choose Subscribe, then enter the subscription URL and a label for identifying it locally. Some interfaces show subscription management separately from server adding. If the menu is elsewhere, look for the Subscribe type rather than choosing an arbitrary proxy protocol. Before saving, check the URL’s beginning, query parameters, and final characters. Watch for spaces, line breaks, or punctuation added during copying.

1. Make sure you’re entering a subscription URL, not a service information page, account page, or single-server share link.
2. Use a label that makes the subscription easy to identify. Don’t use a full account name, password, or access token as the label.
3. Save the subscription record, then use the update option shown in the current interface to retrieve the server list.
4. Return to Home and check the relevant group. Select an entry and confirm its protocol and address are complete.

After the first successful retrieval, check the basics: is the group easy to identify, does each server use the protocol in your original details, and are there any obvious duplicates? The number of entries can help you spot changes, but it doesn’t indicate connection quality. Even when a subscription parses successfully, you still need to select a server and verify the connection. Conversely, one temporarily unavailable server doesn’t mean the subscription URL can’t be updated.

Distinguish subscription contents from a Config file

A server subscription tells you which connection targets are available. A Config file controls how connections are routed and which configuration parameters are used. Entering a rules file URL under Subscribe, or importing a server share link as a full configuration, may result in an empty list or a parsing error. Don’t identify the content by its file extension alone. Check the original description and returned content to determine whether it’s a server collection, a single server, or a file with configuration sections.

If no servers appear after saving, first check whether you still need to fetch the subscription. Then check whether the response is a login page or error message. A page opening in a browser doesn’t mean the client can parse its contents as servers. Don’t repeatedly transform the URL without knowing the format. Keep the original record and use the error message to distinguish an unreachable network, expired access, or an incompatible format before deciding whether to re-enter it.

To establish your first connection, return to the Getting Started guide and complete the Global Routing and system permission steps. This chapter is about setting up management, not changing DNS, rules, and multiple advanced options during import. Confirm that the subscription can update first, then test whether a server connects. This gives you a clear starting point for troubleshooting.

Choose Type first, then enter the corresponding details

Manual setup is useful when you already have complete server details, need to check one entry, or are troubleshooting differences in an import. From Home, open Add Server, choose Type, then fill in the fields shown for that protocol. Authentication differs by protocol, so don’t paste every string from your details into input fields that merely look similar. If required fields are missing, check the original information rather than filling them with defaults from another protocol.

Address usually takes a server hostname or IP address; Port takes the corresponding port. You generally don’t need to add a web path to the address field, and you shouldn’t paste an entire share link there. Check the hostname, port, and authentication details together. One hostname may offer multiple services, and matching ports don’t mean the protocols are the same. Use a short local label such as “purpose / protocol,” but don’t use the label to infer actual server settings.

Check the address, TLS, and transport fields separately

The connection address, the server name used by TLS, and the transport-layer Host may all be different. If your details list multiple names, enter each in its corresponding field. Don’t change them all to match Address just for consistency. The TLS server name is used during certificate and connection checks, while the transport path may be used to route requests. A mismatch in any of these can leave the port reachable while the service connection fails.

For WebSocket and other transport parameters, preserve the leading slash, capitalization, and any existing query string in the path. Don’t remove spaces or special characters just because they look unusual. If your details don’t specify extra headers, don’t add values you found online. Troubleshoot by comparing each field with the original details. Note the current values and change one field at a time so you can identify the cause.

Enter authentication details exactly as provided

Use the original values for Password, UUID, and keys. Watch for full-width characters, input method substitutions, and hidden line breaks introduced when copying. Plus signs, equals signs, and slashes in a password may be valid; a key may also end with valid padding characters. Don’t decode everything that looks encoded before entering it. Client fields usually expect the value defined for that field, not a “readable version” you’ve guessed at.

For WireGuard, distinguish the local interface settings from the remote Peer settings. The private key identifies the local device; don’t use it as the peer’s public key or put it in a label or screenshot. For connection methods that rely on UDP, check whether the current network allows that traffic. Successfully saving the fields only confirms they’re formatted correctly; it doesn’t guarantee the network path or peer is ready for a connection.

After saving, return to Home and make sure you’ve selected the new entry, not an older one with a similar name. Test the entry first, then turn on the connection and verify an actual request. If the old entry works but the new one doesn’t, compare their Type, Address, Port, authentication, and transport fields one group at a time. Don’t overwrite the old entry; it’s a useful reference for reverting.

Maintain manually entered entries separately from subscription-generated entries. Local changes to subscription entries may be replaced during an update. If you need to keep an adjustment, save it as a separate entry if the client allows it, and label its purpose clearly. If a field name is unfamiliar, check the glossary. Don’t mistake an English parameter value for its Chinese explanation.

Scan QR Code reads text

A QR code carries text; it isn’t a proxy protocol of its own. It may contain a single-server share link, a subscription URL, or just a regular webpage address. Before using Scan QR Code, confirm the code comes from your own server information. After it’s recognized, review the parsed result to see whether it will add a server or a subscription record. A successful scan doesn’t mean the content is valid or that the connection will work.

Open the scan option shown in Home. The first time, grant camera access when prompted. If you previously denied permission, check Shadowrocket’s camera access in system settings, then try scanning again. If access is enabled but the code isn’t recognized, make sure the entire code is in view, in focus, and not obscured by glare. Keep the original border around the QR code; don’t scan just the center or shrink it too much.

If the QR code is displayed on the same device, use an image-recognition option provided by the current interface, if available. Otherwise, copy the original text from your source and import it from the clipboard. Don’t upload images containing credentials to online QR readers. Images compressed by messaging apps may lose detail; use the original image or link to avoid losing characters through repeated screenshots.

Check what you select before importing from the clipboard

Copy only the target link, not labels such as “Address:”, quotation marks, list numbers, code fences, or explanations. Some sources visually wrap long links without inserting actual line breaks. If the copied text contains a real blank line, check the original to confirm where the link ends instead of joining fragments by guesswork. Multiple server links usually belong on separate lines; make sure each line has a complete protocol prefix before importing.

1. Copy the original link from your source, not display text that may have been truncated when forwarded.
2. Return to Shadowrocket and use the clipboard import option shown in the current interface.
3. If the system asks whether to allow pasting, allow it only when the current operation needs clipboard access.
4. Check the parsed type and where the entry will be added, then save and review the Home list.

A link in the clipboard doesn’t mean the client must import it automatically. System paste permissions, the interface, and the content format all affect what the client can read. If no prompt appears, don’t keep copying different content to see what happens. Confirm the original link is still on the clipboard, then trigger reading through the explicit import option. When finished, copy some ordinary text without credentials to reduce the time a sensitive link stays on the clipboard.

Troubleshoot recognition failures separately from connection failures

If scanning doesn’t produce a saveable entry, the problem is usually still with recognition or format parsing. Check whether you scanned an information page, whether the protocol prefix is missing, whether the link was truncated, and whether the type is supported. Turning the connection on repeatedly won’t fix an import problem. Keep the original text and compare its structure with the format guidance in the next chapter. Don’t change the password or randomly remove parameters.

If an entry was added successfully but won’t connect, the import created a record; next check the fields, selection state, and network conditions. You can compare QR code and manual imports: if manually entering the same details works but scanning doesn’t, focus on transport, TLS, and extra parameters. If neither works, check the remote server details and current network rather than trying another import method.

Scanning the same code repeatedly may create duplicate entries; whether they’re merged depends on the import process, so don’t assume matching names will overwrite one another. After the first import, note the group and label before proceeding. If you’re unsure what was added, stop importing and check the protocols and addresses in the list. Then follow the steps in Organizing multiple subscriptions to avoid deleting an entry that was already working.

After importing, you still need to select Global Routing and authorize the system VPN configuration. These prompts are unrelated to the QR code itself. If you see the authorization prompt for the first time, read the VPN configuration permission prompt guide. Don’t assume the QR code is invalid or import the same information repeatedly just because system authorization isn’t complete yet.

A single-server link is not a subscription URL

A single-server share link encodes a set of connection parameters as text. Common prefixes include ss://, vmess://, vless://, trojan://, and hysteria2://. A subscription URL is usually an HTTPS URL that retrieves a collection and may return multiple servers. To identify the type, check what the source says it’s for, then inspect the link structure. Just because both can be copied doesn’t mean they belong in the same field.

A protocol prefix gives you a clue about the format, but parsing also depends on the authentication, address, port, and parameters that follow. Encoding conventions vary across protocols and export methods. VMess share content, in particular, is often stored as encoded data and shouldn’t be parsed like a web address with a username, password, and hostname. For unfamiliar formats, import them with the client first, then check the parsed fields.

This example illustrates the structure; it isn’t for connecting

The example below is fictional: it uses example.com as the server address and contains no real credentials. The username or authentication section, host and port, query parameters, and fragment label each have a different purpose. Real details may include additional fields. Don’t remove them just because they’re missing from the example, and don’t infer transport settings that apply to every server.

trojan://[email protected]:443?security=tls&sni=example.com#personal-reference
https://example.com/sub?token=xxxx

The question mark in a link introduces query parameters, which are often separated by &. A fragment after the hash is commonly used as a label. Fields containing special characters may be percent-encoded, so readable text that looks similar isn’t always interchangeable with the original encoding. If authentication details contain separators, decoding or rebuilding them carelessly can change field boundaries and alter the password, path, or label when saved.

Base64 is a text encoding, not a security measure or a test of whether a connection works. A link with no visible password may still contain full authentication details. Don’t treat encoded share content as a public technical log. And don’t repeatedly encode content without understanding its format: double encoding may make the client read ordinary text instead of the original server data.

Server parameters are not traffic rules

Share links usually convey connection targets; they don’t necessarily include the rules, DNS, or other settings from the current Config. After importing a server, whether a domain uses the proxy still depends on Global Routing and the active rules file. The .conf snippet below shows rules evaluated in order. PROXY is a policy keyword, not a subscription group name, and it contains no server credentials.

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

In this example, FINAL,PROXY assigns a policy to connections that haven’t matched an earlier rule. It won’t create a server or fix invalid credentials. This snippet is for explaining the format only; don’t replace a full configuration without understanding it and keeping a backup. To understand .conf sections, read the guide to Config file sections, and keep the context of settings such as [General].

Check what you’re exporting before sharing

When moving data to another device you own, first confirm whether you’re sharing a single server, a subscription URL, or a complete configuration. Exporting a single server may not preserve its subscription update relationship, and exporting a Config may not include the local server library. Check the export output to confirm what it contains. Don’t assume a filename means you have a complete backup, and don’t delete the original device’s entries before testing a restore.

If you see a parsing error, keep the original text and check the prefix, character boundaries, and escaping, then compare the imported fields. Don’t combine different protocols on one line or try to turn a link into a configuration by changing its file extension. If you need to share troubleshooting details, provide only the protocol, the stage where the error occurred, and necessary field structure—without credentials. Keep full links and QR codes in a controlled environment.

An update refreshes the local copy of remote entries

A subscription update requests remote content again and uses it to adjust the locally generated server list. It’s separate from the connection switch and latency tests: turning on the connection doesn’t prove the subscription was updated, and a successful test doesn’t mean you have the latest parameters. Before updating, identify the subscription group you’re working with and note the currently selected entry. This helps prevent selecting the wrong server if the update removes or renames the original.

You can update a subscription when setting it up for the first time, when the source indicates server parameters have changed, or when the list looks noticeably out of date. Frequent refreshes won’t fix every problem; if the response hasn’t changed, another request won’t improve a server’s route. Decide whether to enable automatic updates based on the options in your current interface and your needs. Keep in mind that the system may limit updates in the foreground, background, and on different networks.

Troubleshoot by request, response, parsing, and connection

If an update keeps waiting, first check whether the device can reach other known network resources, then see whether the subscription hostname resolves. The subscription server and proxy server may use different addresses, so being able to reach one doesn’t prove the other is reachable. If the interface offers a routing option for update requests, make sure it suits your network conditions. Don’t assume every update goes through the currently selected proxy server.

If parsing fails quickly, first check whether the response is actually subscription content. An account login page, access verification page, or error message usually can’t be treated as a server list. A browser saying a page opened successfully only means it received a response; it doesn’t mean the response is in a supported format. Don’t save an error page and try importing it, and don’t remove authentication parameters just because they look complicated.

After updating, check what changed—not just the success message

After an update, check that the group still contains entries, the previously selected server is still there, and its label or protocol hasn’t changed. The server count may drop because the remote collection changed; the number alone doesn’t indicate a problem. Likewise, a larger list doesn’t prove better quality. Confirm that new or retained entries have plausible parameters, then run a test and make an actual request to verify they work.

Keep subscription-generated servers consistent with the remote source where possible. Updates may overwrite changes you’ve made to a server’s password, transport path, or TLS name. If you need to keep a local experiment, record the changes and save them as a separate entry, making clear that it no longer follows the original subscription automatically. Don’t stop all updates indefinitely just to preserve local changes; remote parameters may still change.

If you think credentials in the original URL have been exposed, deleting the local subscription won’t invalidate that URL. Use your existing account management channel to check whether you can replace the relevant access credentials, then update the URL in the subscription record. After replacement, check what happens to the old link and remove screenshots, temporary text, and clipboard copies containing it to prevent reuse.

When update and connection problems overlap, change one condition at a time: keep the current network and verify the subscription request, test one updated server, then check Config and DNS. If the app shows connected but websites won’t load, continue with the Connected but no internet troubleshooting checklist. Don’t assume every failure is caused by a subscription update.

Name groups to show their purpose and maintenance relationship

When maintaining several existing subscriptions, keep their sources clearly separated instead of merging every server into one list from the start. Group names can indicate your own purpose, who maintains them, or how you use them—for example, “Daily / subscription,” “Work / manual,” or “Temporary / review.” Names don’t need to reveal account details or access URLs. It’s more useful to know where to update a group and which entries can be changed locally than to make every label look consistent.

Distinguish subscription-level labels from server-level labels. The former help you find the update option; the latter help you choose a connection target. Similar names don’t make them the same object. Remote subscriptions may rewrite server names during updates, so don’t rely on entry labels always staying the same. For notes you need to keep long term, save a record of the group relationships somewhere private and local.

Don’t identify duplicates by name alone

Two entries with the same name may have different addresses, ports, or authentication details; differently named entries may point to the same endpoint. To check for duplicates, compare at least the protocol, address, port, and key transport parameters, then confirm whether they come from the same subscription. Don’t publicly export your full list to ask for help removing duplicates; it may contain credentials. If you need to record your comparison, note only local group names and identifying details without credentials.

Similar entries from different subscriptions aren’t necessarily duplicates to remove. They may have different update schedules, authentication scopes, or usage requirements. Matching parameters now don’t guarantee they’ll remain the same. If you just want to simplify the list, use the client’s existing groups or filters where possible instead of breaking the relationship to the source. Decide whether to remove an entry only after you understand its purpose, backup status, and update behavior.

Server groups are not rule policies

Groups in Home organize servers; rules in Config determine how connections are handled. Moving a server to a differently named group usually doesn’t make a particular type of domain use that server automatically. If your Config refers to a policy or group by name, check those references after renaming it. The relationship depends on the active Config, so don’t infer traffic behavior from a group’s label alone.

Understand the three common Global Routing modes separately: Config applies the rules in the current Config; Proxy sends applicable traffic through a proxy policy; Direct handles applicable traffic as a direct connection. Don’t switch modes while organizing your server list and forget to switch back. Otherwise, test results won’t use the same conditions as before, and you may mistakenly think the group changes affected server quality.

Organize in batches and keep notes for reverting

Before cleaning up, note the current groups, selected server, and connection status, then handle one clearly identified set of duplicates. After each batch, check that the update option is still available, verify whether the selection changed, and make an actual request. Don’t delete or rename large numbers of entries, update subscriptions, and replace Config all at once. If something goes wrong after several changes, it will be difficult to identify the cause.

If you’re not sure what an entry is for, keep it for now and add a local note instead of deleting it just to shorten the list. When cleaning up, start with temporary entries that are clearly invalid and can be restored, then independent manual entries, and consider subscription groups last. A server deleted from a subscription may reappear at the next update because the remote collection and local copy are linked; that doesn’t necessarily mean the deletion failed.

After organizing, keep a maintenance note without sensitive values describing which groups update automatically, which entries are maintained independently, and which names are referenced by Config. It doesn’t need passwords or full URLs, but it can help you restore these relationships after changing devices or recovering data. For interface terms, see the Home, Config, and Settings reference to avoid bulk actions at the wrong level.

Test results apply only to specific conditions

Connectivity Test checks server behavior using a particular test method under the current network conditions. A lower time doesn’t mean every website will load or that throughput is higher. A timeout means the test didn’t finish under the expected conditions; it doesn’t prove the authentication details have permanently stopped working. To interpret a result, consider the test method, network environment, and whether the server was busy at the time.

Different test methods may cover different stages of a connection. A test that checks only whether a port is reachable can’t fully verify proxy authentication, TLS, DNS resolution, or a request to the destination. A test that sends a request through a proxy reflects only that target and path at that time. If the current interface lets you choose a test method or address, confirm which one you’re using before comparing results. Don’t mix values from different methods in one ranking and draw conclusions.

Verify one entry first, then test a limited selection

For a newly imported subscription, test one entry with complete parameters first to confirm the client and network are working. Then run tests on a limited group of servers you want to compare. Testing a large list at once may generate many concurrent requests, and results can be affected by your local network, remote restrictions, or the test target. If tests keep failing, narrow the check to one entry instead of increasing concurrency to get more results.

1. Use the same network and make sure no high-bandwidth task is affecting the results.
2. Choose a test method and a small set of servers to compare.
3. Retest unusual results after a pause; don’t delete an entry based on one timeout.
4. Select a candidate server, connect, and check the content you actually need to access.

Wi-Fi and Cellular may use different network paths. Reachability on one doesn’t guarantee reachability on the other. Retest after switching networks rather than relying on an earlier result. If all entries have problems at once, check the local network, system time, test target, and DNS first. When multiple independent endpoints fail together, shared local conditions are often a better place to start than changing each server’s parameters.

Sorting is a temporary view, not a promise of automatic routing

Sorting by test results can make it easier to find candidate servers, but it doesn’t automatically change the policies used by all rules or guarantee that the first entry is selected. After sorting, check the selection marker, current Global Routing mode, and Config. If rules refer to a specific policy or server name, the actual connection may not use the entry you just tested. Check the active Config to see what’s in use.

Compare servers at similar times, on the same network, and with the same test method, then confirm results with the task you need to perform. Large downloads, short webpage requests, and long-lived connections place different demands on a network path; no single latency value summarizes them all. A region or purpose written in a server label isn’t a substitute for testing. Labels help identify entries; check the current connection state to determine the actual route.

If a connection fails, check the actual request path

If a test succeeds but a webpage won’t open, first confirm that the selected server is being used for the request, then check Global Routing, DNS, and rule matching. During troubleshooting, you can temporarily compare different modes, but change one condition at a time and restore the original settings after testing. Don’t permanently replace the whole ruleset just to open one webpage, and don’t blame every failure on high latency.

When recording results, note the network type, test method, whether the target was selected, and the stage where the error occurred. There’s no need to share full server addresses or credentials. To distinguish routing issues from connection problems, read Troubleshooting servers, Global Routing, DNS, and rules. Reliable management comes from repeatable checks, not a single ranking or isolated number.

Before deleting, check the object and its relationships

Deleting a server, deleting a subscription record, removing a Config file, and deleting the system VPN configuration are different actions. The first two affect local server management; Config affects rules and configuration content; the system VPN configuration affects system connection authorization and related settings. Read the object name and confirmation prompt in the current interface before acting. A connection issue doesn’t automatically mean you should clear all your records.

A server deleted from a subscription may return during the next update. Deleting the entire subscription record may also remove the entries it generated; check the confirmation prompt to see what will be removed. Before deleting, note the currently selected server and check whether Config refers to it by name. If the referenced entry disappears, the resulting problem may be at the policy selection layer rather than with the remote server itself.

Back up data from each layer

A complete restore usually needs more than one .conf file. Check separately that you’ve saved subscription URLs, independently entered servers, Config files and their selection state, local overrides, and necessary operating notes. Don’t assume an export option includes everything. Read the current interface’s description of what will be exported, then inspect the output. A file opening successfully doesn’t mean it contains restorable authentication details.

Backups, share links, and QR codes may contain equally sensitive data; keep them somewhere with restricted access. If you use built-in device file syncing, understand which account and sharing scope are involved. Don’t put backups in a publicly shared folder. Temporary exports created for troubleshooting need to be managed too. Delete copies you no longer need after checking them so old credentials aren’t scattered across locations.

Restore in order: sources, entries, configuration, then connection

On a new device, first use the download guide for all platforms to get Shadowrocket, then restore subscription sources and independent servers from your backups. Next, restore Config and check that all referenced names exist. Finally, set Global Routing, select a server, and complete system authorization. This order helps distinguish missing data from connection requirements that haven’t been met.

Getting the app on iPhone / iPad is separate from restoring server details. Reinstalling the app doesn’t restore subscription URLs or local parameters. The iPhone / iPad app is a one-time $2.99 purchase on the App Store; Mac, Windows, Android, and Linux versions are free. See the download page for app access and purchase information. A one-time app purchase is not a service subscription, and restoring the app won’t create server details.

After restoring, test one entry and verify it with an actual request. Delete entries from the old device only after confirming the new one works. Some local settings, system permissions, and background behavior may differ across devices, so matching server names alone doesn’t prove the migration is complete. If the new device fails but the old one works, compare key fields, Config, Global Routing, and network conditions. Keep the old device as a reference for reverting.

Handle accidental deletion and invalid credentials differently

If you accidentally delete a local entry, restore it from a saved subscription URL, server share link, or backup. If you deleted only an entry from a subscription, confirm the subscription record still exists, then try a normal update. Don’t assume an undo option will be available, and don’t repeatedly import old backups without checking the current data. This can create duplicate entries and mix different parameters, making recovery harder.

If credentials have been changed or expired, an old backup can restore only the old parameters; it can’t restore remote access. Check your own current information, update the subscription URL or authentication details, and test the connection again. If you need to invalidate an exposed link, update the remote credentials rather than just deleting the local copy. Keep one backup you’ve verified can be restored and a separate maintenance note without sensitive values, so future updates and migrations have a clear reference.