Shadowrocket
Subscription & Server Management Guide

01 / Subscribe

Subscribe: Add a Subscription for the First Time

First, identify what kind of data you have

A subscription is a URL the client can request again to retrieve a set of server details. A single server link usually describes one connection, while Config determines how traffic matches rules. All three may be provided as a link or file, but they represent different things. Before importing, check the provider’s instructions to see whether you have a server subscription, a single share link, or a configuration file. A link opening in a browser does not mean it belongs in Subscribe: a login page, an information page, and a subscription response are different kinds of data.

Get your subscription URL from your service provider. Copy the entire line, including any query parameters after the question mark. These parameters may identify your account; removing them can return an empty list or an error page even when the domain is correct. When copying through a messaging app, check that the end was not cut off, that no period was added, and that line breaks were not inserted as actual characters. Never paste the full URL into a search box or public forum. When asking for help, describe the error and share only a redacted domain.

Choose Subscribe in Add Server

1. Open Home, go to the add menu, and open Add Server. Under Type, select Subscribe.
2. Paste the complete subscription URL into URL, add a recognizable label for this source, and save.
3. Wait for the first request to finish, then return to Home and check the relevant group for the imported servers.
4. Select a server and follow the quick-start steps to configure Global Routing and verify the connection.

Saving a subscription entry and successfully downloading its contents are separate steps. Seeing the subscription name in Home only confirms that its local entry was saved; it does not confirm that remote content was parsed. After importing for the first time, check that the group is expanded, server names are complete, and the number of entries matches your provider’s information. If the list is empty, review the request message and then check the URL. Avoid creating several subscriptions with the same name, or it will be hard to tell which one has the correct URL and which is just a failed local entry.

Distinguish request, content, and connection failures

A request failure means no subscription response was retrieved; possible causes include the current network, DNS resolution, an invalid URL, or access permissions. A content failure means a response was received, but it was not recognized as a server list. A connection failure occurs after server details have been retrieved. Check these three layers in order, and do not mistake a server timeout for a subscription parsing problem. If the response is a web page, follow its instructions to check your account or URL rather than importing the page text as configuration. Redact the full subscription URL in any troubleshooting screenshots you share.

Import a subscription for the first time on a network that can currently access its URL. If an update request is routed through a server that is no longer working, you may end up in a loop: you need to update to restore the connection, but need the connection to update. Disable the failed connection first, make sure the local network works, and then request the subscription again. If your provider specifies access requirements, check its instructions. Avoid changing multiple settings at once; keep the exact error message so you can distinguish a network issue from a problem with the subscription details.

02 / Add Server

Add Server: Manual Fields and Protocol Parameters

Select Type first, then fill in the details

Manual setup is for users who already have complete server parameters and need to maintain a separate entry. In Add Server, select Type first, as the protocol determines which fields appear and what they mean. Do not choose a similar-looking type and try to make it work by changing the port. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different authentication and transport methods. Sharing an address and port does not make them interchangeable.

Address usually takes a hostname or IP address, without a web path. Enter the server port in Port; do not include the colon and port as part of the hostname. If you have a complete share link, use an import option where possible to avoid losing transport settings hidden in its query parameters. A label is for local identification and cannot fix connection settings. Use the source, purpose, and protocol to name the entry rather than storing passwords or account identifiers in the name.

Check authentication, TLS, and transport settings separately

For Shadowsocks, check the encryption method and password. VMess and VLESS commonly use a UUID for identification. Trojan requires a password; check TLS and SNI against the provided details. Whether HTTP and SOCKS5 require a username and password depends on the server configuration—do not omit them just because the fields can be left blank. WireGuard uses a different structure for keys, interface addresses, and peer details; do not put a subscription password in the private key field. If you are unsure about a parameter, check the original details instead of trying it under different protocols.

The TLS setting determines whether the corresponding encrypted session is established. SNI specifies the server name for that session, while the connection address may be a separate entry hostname. If the provider lists them separately, enter them in their respective fields. For a certificate name mismatch or handshake failure, check SNI, the system time, and the original details first. Do not routinely disable certificate verification as a fix. Change one parameter at a time and record the result so you do not accidentally break settings that were correct.

The transport type and its Host, Path, and other settings must match as a set. Do not add or remove leading slashes, trailing characters, or query strings based on guesswork. Full-width punctuation, smart quotes, and spaces introduced by an input method can also change a parameter. Before saving, compare each field with the original details, paying particular attention to numbers, letters, and hyphens copied from an image. If the provider did not supply an optional field, leave its protocol default unchanged; do not fill it with a value from another server.

Save separate entries and keep changes isolated

Maintain manually added entries separately from subscription-generated servers. Changes to a server managed by a subscription may be overwritten on the next update. If you need to keep a local change, first make sure the copied or separately added entry is no longer managed by the subscription. After saving, run a test and then verify the connection with an actual request. If the same parameters behave differently on different networks, record the network conditions rather than immediately assuming the password is wrong.

For troubleshooting, keep only the protocol, redacted address, port, transport type, and error message; do not share authentication values. For details on Trojan fields, see Trojan passwords, SNI, and TLS parameters. Check questions about server configuration against the original details; changing a label will not make the client infer missing fields.

03 / Import

QR Code and Clipboard Import: What to Expect

Scan QR Code reads content; it does not validate it

A QR code is a way to encode text, not proof that it contains server details. Scan QR Code may read a single server share link, a subscription URL, or a regular webpage. After scanning, check what kind of item the client is about to create before saving. If it opens a webpage, check the source instructions to confirm the QR code’s purpose; do not put the webpage URL into an arbitrary protocol field. QR codes may contain complete credentials, and photos, forwarding, and photo syncing can all increase how widely they are stored.

From the add menu in Home, choose Scan QR Code and grant camera access when prompted. Position the code so the entire image is visible. Keep it in focus and avoid glare, steep angles, or screen zoom that could make it blurry. If the QR code is on the same device, import it from an image only if the scan screen explicitly offers photo library access. Otherwise, use the text link provided with the source. Never submit an image containing credentials to an external QR code reader.

Clean up the original text before importing from the clipboard

Copy the complete share link, return to Shadowrocket, and use the clipboard import option provided in the interface. If the system asks for paste permission, decide whether to allow it for this operation. If the copied source includes a title, instructions, and multiple links, check what the client can recognize. For a failed batch import, try one complete link first to tell an unsupported format from extra text mixed in with the links. Repeatedly granting permission is not a substitute for checking what was actually copied.

1. Copy one complete link from your own details and check that both the protocol prefix and the trailing label are intact.
2. Open the clipboard import option, review the preview or result message, and confirm the type of item created.
3. After saving, find the new entry in Home and check its protocol, address, and group.
4. Clear any temporary intermediary content when finished so you do not accidentally share credentials the next time you paste.

Messaging apps may collapse long links into shortened display text. Seeing a single line on screen does not mean the entire link was copied. Some editors also replace straight quotes with curly quotes or insert line breaks in the middle of a link. Return to the original text and try copying the link or raw text again. If you must pass it through a text editor, use a local tool that preserves plain text and avoid public sharing. Process only your own details; do not store other people’s authentication information.

Check the fields even after a successful import

A successful import means the parser found a recognizable structure, not that every field meets the server’s requirements. After saving, check at least Type, address, port, and TLS or transport settings. Make sure the purpose mentioned in the label matches the actual fields. Compare against the original parameters if the QR code was cropped from an image, decoded from text, or forwarded multiple times. If a QR code and a text link create different entries, pause before connecting and confirm that both actually describe the same server.

Scanning or pasting the same content more than once may create separate entries or update an existing item, depending on the import method and content. Do not assume an item was replaced based on its name alone: check its source, group, and details in the list. Before a batch import, note the existing groups. After importing, check the new content before deleting failed intermediate entries. If you already have a working entry, keep it until the new one has been verified in practice so you have a baseline to compare against.

Camera permission errors, denied paste permission, and content parsing failures are different problems. The first two are handled in system permissions; the last requires checking the link type, encoding, and completeness. Granting more permissions will not make an invalid format into a working server. If the scan screen works but cannot read the code, reduce glare, enlarge the original QR code, or use the text details instead. Never guess missing authentication characters; obtain a complete copy of your own details.

04 / URI

Share Link Formats vs. Config

Identify links by structure, not length

A share link usually contains a protocol prefix, authentication details, a target address, port, query parameters, and a label. Protocols use different formats: some fields are readable, some are encoded, and some package a set of parameters before encoding them. Do not apply the username position from one protocol to another, or delete an encoded section just because it looks like gibberish. Start with the protocol prefix and use the corresponding import option. Manual inspection is for checking the structure of the provided details.

A subscription URL usually uses HTTP or HTTPS and returns a list when requested from the server. A URL that looks like a webpage link is not necessarily a configuration file; the response type and intended use determine what it is. Adding a subscription URL as a regular HTTP proxy creates the wrong kind of item: HTTP proxy fields describe a connection endpoint, not the location from which to download a server list. Likewise, putting a Config file into Subscribe will not convert its rules into servers.

https://example.com/sub?token=xxxx

trojan://[email protected]:443?security=tls&sni=example.com#Personal-Trojan

The examples above show structure only. Their domains, passwords, and subscription parameters are illustrative and cannot be used to connect. The first represents a possible URL for retrieving a list; the second shows the structure of a single Trojan share link. Real details may include additional parameters. Keep them intact rather than editing the link to match an example. A hash (#) in a link usually introduces a label, and a question mark (?) usually introduces parameters, but the supported format depends on the protocol and how the client parses it.

Encoding is not encryption, and a label is not authentication

Percent-encoding represents certain special characters, and some share formats also use Base64. Encoded text may still reveal passwords and server details when decoded, so it is not safe to share as a redacted example. Passwords containing special characters must be handled by the correct export or encoding process; inserting a password with delimiters directly into a link may change how it is parsed. If imported fields end up in the wrong places, re-import the original share link instead of repeatedly adding escape characters.

Labels and server identity are separate. Two links may have the same label but point to different addresses or use different authentication; the same server may also appear more than once under different labels. Compare the actual fields, not just the text after the hash. To explain a format issue to someone else, build a structural example using a fake domain and password. Changing the label to “test” does not remove sensitive information.

Config manages rules; it does not replace server details

Config determines the order in which requests match policies. In Global Routing, the Config mode uses rules, while Proxy and Direct apply different global handling. If servers import correctly but traffic takes an unexpected path, check the current mode and active configuration instead of importing the same servers again. This rule snippet illustrates the order: match a specified domain first, then a geographic rule, and finally send unmatched requests to FINAL.

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

This snippet is neither a subscription nor server details that can establish a connection on its own. PROXY represents the relevant proxy policy; whether it works depends on the selected server and configuration context. DIRECT sends the relevant request directly. Rules are evaluated in order, and after a match, later rules are generally not checked. Back up and test server details and rules separately, changing one category at a time so you can tell whether a problem comes from the connection endpoint or traffic selection.

For DOMAIN-SUFFIX, GEOIP, FINAL, and other interface terms, see the glossary. For a failed link, identify the item first, check its structure, and then check its fields. Changing unrelated rules will not fix a format error, and a correctly displayed label does not prove that authentication details are valid.

05 / Update

Subscription Update Policy and Troubleshooting

An update refreshes source content, not just latency values

Updating a subscription makes a new request to its source and adjusts the servers it manages based on the response. Addresses, ports, authentication, transport settings, and names may all change. This is different from retesting the latency of the current list, which only checks saved entries and cannot retrieve new parameters from the source. If several servers stop working at once, first decide whether the subscription needs updating, then check the network. Repeatedly testing old entries will not sync changes from the source.

When establishing an update routine, manually update a subscription once while you can observe the result. Before updating, check which subscription and server you are using and whether you have local changes. Afterwards, check the source group, selected entry, and actual connection. If the interface offers automatic updates, enable them based on your maintenance needs. Do not assume background updates happen at the same time on every platform. System background restrictions, network conditions, and whether the client is running can all affect when a request is made.

Set an update schedule based on how often your details change

A sensible schedule depends on how often the source changes and how you use it, not on updating as often as possible. For a stable source, check before use or after receiving a change notice. Before traveling, changing networks, or moving to another device, update and verify in advance. Repeated requests in a short period will not fix an invalid URL and may be subject to request limits imposed by the source. If the interface does not clearly show background behavior, manual checks and verifying the result are more reliable than assuming automatic refreshes occur.

1. Before updating, note the source and entry in use; back up any independent local configuration if needed.
2. Update one subscription at a time, watch the request message and group changes, and avoid changing rules at the same time.
3. Check whether the previously selected entry is still there, review the new parameters, and run a test.
4. Reconnect and verify a real request; once it works, move on to the next source.

Manual changes to subscription-generated entries may be overwritten by a later update. Whether names, sorting, and groups are retained also depends on the actual result. Record lasting changes in independently managed entries rather than relying on local fields to survive every update. If a source removes a server, seeing it in the local cache does not mean it still works. Do not keep an entry just because its name is familiar if its authentication or endpoint has changed.

Troubleshoot in four layers

First, check whether the local network can send requests. Second, check whether the subscription domain resolves and connects. Third, check whether the source returns valid content. Fourth, check whether the current import option can parse it. Each layer requires different evidence: a connection error and an authentication failure are not the same. If you see an access-related message, check your own subscription URL and account status. If you receive a regular webpage, make sure you did not copy a management page instead of a server subscription.

If the list suddenly becomes empty after an update, stop before deleting anything. Check whether the group is collapsed or a filter is hiding its contents, then check whether the update finished and whether the source actually returned an empty result. If this is only a display issue, importing again will create duplicates. If the source content really changed, restoring an old cache may not restore a working connection. Keep the necessary notes from before the update for comparison, but do not upload the raw response publicly; it may contain server passwords and access tokens.

If the update succeeded but connections fail, troubleshoot the servers and network. Select an updated entry, check its protocol parameters, then test other entries from the same source. If only one is affected, you usually do not need to rebuild the entire subscription. If all sources fail at once, also check the current network and system time. See troubleshooting server timeouts and connection failures for a step-by-step approach to collecting evidence without repeatedly resetting settings across multiple screens.

06 / Organization

Organize Multiple Subscriptions, Names, and Duplicate Entries

Group by source; name by purpose

When managing several of your own subscriptions, keep their sources separate instead of combining everything into one long list. Give each source a stable, easy-to-understand local name, and label manually added entries separately. This makes it easier to identify what is affected by a failed update, changed parameters, or a deletion. Names can indicate purpose and how an entry is maintained, but should not include a full subscription URL, account identifier, or password. If that information appears in a list screenshot, it could be exposed through routine troubleshooting.

Group names should describe relatively stable information. A latency value in a name will become inaccurate when the network changes; a sorting number will become confusing after an update. Use a short source label, purpose, and protocol to help identify entries while keeping track of their original details. If the client only lets you change some display information, work within those limits rather than changing server authentication fields just to make names consistent.

Confirm an entry is a duplicate before deciding what to keep

The same name does not mean two entries are duplicates, and the same address does not necessarily make them duplicates either. The same target can use different ports, protocols, authentication, transport, or SNI; a single source may also provide endpoints for different network conditions. Compare key fields and source relationships before deleting anything. If two records differ only by label, still check whether one is managed by a subscription and the other is an independent copy: deleting them has different maintenance consequences.

Organize entries in two passes. First, record and label suspected duplicates without deleting them. Then check each group’s current connection, backup, and alternate entries before deleting anything. Servers imported through a subscription may be recreated the next time the source returns them, so repeatedly deleting them by hand may not last. If the interface offers filtering or display organization, first check whether it changes only what you see or modifies the actual data.

Keep subscription management separate from rule policies

Source groups show where servers were imported from; rule policies determine how requests are handled. The two do not need to map one-to-one. Putting two subscriptions in separate list groups will not automatically route different domains through each one. To choose a rule, check the configuration in Config and its policy context instead of inferring routing from group names. Keep server details correct before changing rules to avoid hard-to-trace side effects such as access changing after list organization.

After updating a source, check whether the entry in use is still in the expected group. If the source reuses a name, check the details before switching; a familiar name is not a stable identifier. You can keep an old entry temporarily with a note about its purpose and what needs confirmation, but do not leave an outdated copy mixed in with the current source indefinitely. A useful maintenance note says why you kept it and when to check it again—not just an unexplained asterisk.

Managing multiple subscriptions does not mean testing every entry at once. Start with a small sample from each source to check that import and updates work, then review the rest as needed. As the number of sources grows, keep operations traceable: note which source was just updated, which entry was just changed, and which group is due for deletion. Work on one group at a time and verify it before moving on. This avoids widespread accidental deletions and makes it easier to return to the last verified state.

For more on grouping and cleanup, see managing multiple subscriptions. The goal is to reduce the effort of identifying entries and avoid ambiguity, not to make the list as short as possible. If you are not sure what an entry is for, record and verify it first; that is more likely to preserve context than deleting everything and importing again.

07 / Connectivity Test

Latency Tests, Sorting, and Real Connection Checks

A test result answers only the question that test was designed to check

A latency test reflects the network and test method at that moment; it is not a permanent rating of a server. A TCP connection test, a request sent through a proxy, and a check of real-world access exercise different parts of the connection, so their values are not directly comparable. Before testing, check the client’s current test settings. Compare entries on the same network, at around the same time, and with the same method. A low number in the list does not prove that authentication, TLS, DNS, and access to the target site all work.

Before running Connectivity Test, make sure the subscription details have been checked. A test of outdated parameters says nothing useful about whether the current source works. After an update fails, do not treat a timeout from the old list as proof that the new details are invalid. Test one entry first, then decide whether to test the whole group. This avoids unnecessary wait times and mixed results. Pause bandwidth-intensive activity such as large file transfers during testing so entries are measured under more similar conditions.

Use the scope of the failure to find the problem layer

If only one server times out, check its address, port, and protocol parameters. If several entries from the same source fail, check whether the details need updating or the source has changed. If entries from different sources all fail, first check the local network, system time, and current connection status. If switching networks fixes the problem, note the difference between them rather than immediately rewriting all authentication details. The scope of a failure is more useful than a single latency value: it helps determine whether to inspect client fields, remote details, or the local environment.

Sorting can save time when looking for an entry, but it should not be the only basis for choosing one. After a test, you can sort similar entries by their current results and verify the leading candidates first. Untested entries, failed entries, and entries with measurements should be treated separately. Results from different protocols, test methods, or times should not be mixed and used to declare one server permanently better. For meaningful records, note the network and test method instead of keeping an isolated screenshot of a number.

A successful test still needs a routing and real-request check

Select a server, connect, and then check the current Global Routing mode. Config mode applies rules; Proxy mode focuses on verifying the proxy path; Direct mode does not prove that a server is working as a proxy. If a rule sends a target to DIRECT in Config mode, opening that target does not prove the selected server works. Test a normal use case of your own and check the connection log to see how the request was handled, rather than looking only at the top-level toggle.

If a real request fails, check its error type and matched policy in the connection log before deciding what to do next. DNS resolution errors, TLS handshake failures, authentication errors, and target access denials require different fixes. A browser loading indefinitely does not by itself prove a server timeout, and a failure with one target is not a reason to delete an entire subscription. Compare with another normal request, then check whether the issue is limited to a domain, protocol, or network to narrow down the cause.

For intermittent problems, a few comparable records are more useful than repeatedly running tests. Change one factor at a time—such as the network, server, or Global Routing mode—and observe the result before changing anything else. Changing DNS, rules, and authentication together makes it impossible to tell what fixed the issue. A timeout in the test screen does not mean the server has been permanently removed. Before deleting it, check for updates and retest on another network. Move entries that seem inactive into a list for review before scheduling cleanup.

For more error scenarios, see troubleshooting server timeouts, protocol parameters, and system time. Once verification succeeds, set any On Demand conditions you need. Automatic connection changes when the connection starts; it does not fix incorrect parameters or replace a complete manual connectivity check.

08 / Backup

Deletion, Backups, and Restore Order When Moving Devices

Before deleting, identify the item and what else it affects

A single server, an entire subscription, and Config are different items. Deleting an independent server usually affects only that local entry. Deleting a subscription entry may also affect the servers it manages. Deleting Config affects rules and policy settings. Read the confirmation prompt and check whether your current connection depends on the item before deleting it. Do not delete a subscription to remove one failed server or clear Config just to restore the list; doing so removes your baseline for diagnosing what may have been a local problem.

A server deleted from a subscription may reappear after the next update because it is still in the source. This does not necessarily mean the deletion failed; the local entry may have been recreated from the source. If you no longer use the source at all, check your backup and alternative connection before deleting its subscription entry. If you only want to hide some entries temporarily, check whether the interface supports display-level organization. Record how items are managed before deletion; it is more reliable than guessing which group a server belonged to by name afterwards.

Choose backups based on what you may need to restore

A backup should answer at least three questions: can you retrieve the subscription again, restore independent servers, and restore rules? Saving only a subscription URL may not recover manually added entries or local Config. Exporting only a rules file may not include server authentication. When using an export option, check exactly which items it includes. A generated file does not necessarily mean everything was saved. Backup files often contain sensitive information; keep them in a protected location you control, and do not share or forward them casually.

1. Note your current subscription sources and essential maintenance details. Store complete credentials in a protected location.
2. Back up independent servers and Config; check what the export includes and make sure the files can be opened.
3. Note the current Global Routing mode and any On Demand conditions to check again.
4. Test the restore process while the old device is still available, then clean up old data after confirming it worked.

If you use iCloud sync, first check that your devices, account, and the actual items to sync meet the requirements. Do not assume all local data syncs automatically. Sync passes current state between devices; a backup keeps a separate copy you can roll back to. They serve different purposes, and an accidental deletion may also sync. Before bulk cleanup, reorganizing groups, or moving to a new device, keep a separate, clearly identified backup and note what it contains so you do not restore the wrong file.

Restore your data first, then verify rules and automatic connections

On a new device, get the client first. Restore one subscription or a small number of independent servers, confirm that the basic connection works, then restore Config and check On Demand last. Do not import everything and immediately enable automatic connections; faulty rules, expired authentication, and system trigger conditions can become entangled. Follow the prompts on the new device to grant any required system VPN permissions. A working connection on the old device does not mean its authorization will transfer. Keep the old device available during migration so you can compare each item.

Update restored subscriptions, check independent entries again, and verify that the policies referenced by your rules still exist. The same name does not guarantee the same item. If a migrated configuration refers to a group that no longer exists, fix the reference before testing a real request. A successful backup is not measured by how many files you have, but by whether you can rebuild a working setup in a clear sequence. Recording the result of one restore can save time the next time you move devices.

For the client, the iPhone / iPad version costs $2.99 as a one-time App Store purchase. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Follow the download page instructions for installation and system permissions. Installers for other platforms are available on this site at /dl/shadowrocket/. For iPhone / iPad purchase restoration and system requirements, see the relevant sections of the download page. Manage account purchase history and subscription credentials separately.

After verifying the new device, follow your own device disposal process to clear subscriptions, servers, exported files, QR code images, and clipboard content from the old device. If credentials were exposed, replace them using the method provided by the service; deleting local files alone will not invalidate a leaked URL or key. For more on migration, see backing up Config and moving to a new device. For everyday use, return to the setup guide and verify the connection steps.