Shadowrocket Server Management

01Subscribe: Import an Existing Subscription

Tell subscription URLs apart from rule configurations

Subscribe retrieves server details from a subscription URL you already have. A subscription can contain multiple server entries, which are usually grouped by source after import. Future updates still depend on the original URL. A server entry stores the address, port, and authentication details for one connection; a subscription provides access to those entries. Check which one you have before importing so you don't mistake a webpage URL for a subscription URL.

Config manages configuration files, which primarily contain rules and related settings. A URL alone does not make a Config file equivalent to a server subscription. Some complete configurations also include servers or remote resources, so determine the file's purpose from its contents. For a server subscription, choose an Add Server option with Type set to Subscribe. For rule configurations, check the file's purpose in Config rather than trying different import options at random.

Import a subscription by entering its details

Open the add menu from Home, then go to Add Server. Set Type to Subscribe, enter the subscription URL you already have, and give the source a recognizable name. The layout may vary by device or app version, so use Type and the field labels to identify the right option. Copy the entire URL, paying particular attention to query parameters that may be truncated by line breaks, trailing punctuation, or an incomplete selection in a chat app. A URL wrapping onto two lines on screen does not necessarily contain a line break.

After saving, check that the subscription group appears and that it contains server entries. Importing requires the app to access the URL and parse its response, so saving the URL and importing servers are separate steps. If the group appears but is empty, check the update status and returned content rather than assuming the servers cannot connect. Verify server authentication and connectivity after the entries have been imported.

1. Make sure you copied your subscription URL, not an account or information page.
2. Select Subscribe, enter the URL and a recognizable name, then save.
3. Check that the group and its entries appear, then review one server's settings.
4. Select a server and follow the setup guide to choose a mode and verify the connection.

Troubleshoot import issues by checking retrieval, parsing, and connection separately

If the subscription can't be retrieved, first check whether your current network can reach the URL and whether it is still valid. A login page, verification page, or error message returned by the URL will not become a server list just because you saved the address. Don't enter your account password in an unrelated field or share your subscription with an unfamiliar website to test it. Subscription URLs often contain access credentials, so treat them as private. When troubleshooting, describe the type of error without revealing the full URL.

If retrieval succeeds but no usable entries appear, check the content's format and completeness. Refer to the original instructions to confirm that the URL provides subscription content supported by Shadowrocket; don't judge by the file extension alone. If only a few entries are missing, compare their protocols and fields before clearing the whole group. If needed, keep the entries that still work, then run one deliberate manual update and note what changed. This makes it easier to identify the original issue.

After importing, return to Home and check whether the selected server belongs to the group you just added. Viewing a subscription does not necessarily select one of its entries for the current connection. For your first test, verify a single known entry, including its address, mode, and authorization flow, before sorting the group. This helps distinguish an import issue from selecting the wrong entry or a connection failure.

02Add Server: Enter Server Details Manually

Choose the fields based on the protocol

Use Add Server when you already have complete details for a server or need to check fields after importing. First select Type, then fill in the fields shown for that type. Don't fill in fields for one protocol and then simply change the type: authentication and transport settings differ between protocols. Changing the type may add fields or leave values that need to be checked again. Keep the original details handy for comparison.

Address is usually the server's domain name or IP address; Port is the port the server actually listens on. Don't add a webpage path to the domain, and don't assume TLS means you should use a particular common port. The server address, TLS Server Name, and transport Host may be the same or serve different purposes. If the original details list them separately, enter each in its corresponding field rather than changing them all to match.

Authentication, TLS, and transport are separate layers

Shadowsocks requires the encryption method and password used by the server. VMess and VLESS usually require a UUID and any additional parameters specified by the configuration. Trojan requires the password and relevant TLS details. These values aren't interchangeable. Saving the form only confirms that the fields passed basic input checks; it doesn't mean the server will accept the credentials. If the connection drops soon after it starts, compare the original details before randomly changing encryption or transport options.

TLS is separate from proxy protocol authentication. Server Name is usually used for certificate name verification and Server Name Indication; it is not a label or note. If you see a certificate error, check the name, device time, and original settings, then confirm the server's certificate status. Disabling certificate verification changes the connection's trust boundary and should not be a routine troubleshooting step. Leave options at their defaults unless the original details specify otherwise or you have confirmed what they do.

With transports such as WebSocket, Host and Path are part of the transport settings. Slashes, capitalization, and query strings in Path can affect server routing, so don't edit them as if they were ordinary notes. If the original details specify TLS, a transport, and a path, match each value to its own field. Hysteria2 and WireGuard have their own keys and connection parameters; don't apply another protocol's setup steps. Enter only the fields required for the selected Type and explicitly provided in your source details.

Review the details after saving, then test one setting at a time

Give a manually added entry a recognizable label, such as “Manual test,” but never include a password or full key in its name. After saving, reopen the edit screen and check the type, address, and port, including whether copying added spaces. When making corrections, change one category of settings at a time and note why. If you change the port, TLS, and transport simultaneously, even a successful connection won't tell you which change fixed the problem.

You can review fields for imported servers in the edit screen, but local changes to subscription entries may be overwritten by a later update. Before making a lasting local change, check whether the app lets you copy the entry as a separate server, and name the original and test copy clearly. Don't directly edit your only known working server before validating the change. For other ways to import details you already have, see Four Ways to Add Servers.

03Import with Scan QR Code or Clipboard

A QR code carries information; it doesn't change the server settings

Scan QR Code reads the text encoded in a QR code. It may contain a server share link, a subscription URL, or just a regular webpage address. After scanning, check what was recognized and what is being imported. Successfully reading the code doesn't guarantee that the server details are correct. The protocol, address, and authentication information in the QR code should correspond to what you would enter with Add Server; the difference is how the details are entered, not how the connection works.

Before scanning, make sure the QR code comes from server or subscription details you already have, and avoid displaying codes containing credentials on public screens. If you scan with the camera, grant the requested permission when prompted. If permission was denied, check it in system settings rather than repeatedly tapping the scan option. If the app offers scanning from your photo library, you can choose a saved QR image. Keep the full code and its edges clear; don't crop its finder patterns or use a heavily compressed thumbnail.

If a QR code won't scan, first improve the conditions: show the entire code with adequate brightness and no glare or noticeable blur, then adjust the distance. If the same code still fails and you have the original text, import the text or enter the details manually instead of repeatedly taking screenshots that may lose information. Scan one code at a time if an image contains several. After importing, check the name and source to avoid adding duplicates and mistaking them for updated entries.

Control what you copy before importing from the clipboard

Clipboard import is useful when you already have a complete server share link. Copy only the link you need, return to Shadowrocket, and use the clipboard import option shown in the current interface. If iOS asks for permission to paste, confirm as appropriate. Explanatory text, quotation marks from a chat, and punctuation at the end of a link aren't part of the protocol and can prevent recognition. Don't copy an entire chat for convenience or expect the app to identify every extra note automatically.

For batch imports, keep one link per line and preserve the original characters. Distinguish a visual line wrap from an actual line break: a long link wrapping on screen is usually fine, but an inserted newline can split one entry in two. If only the first item imports, check whether the remaining entries use the same supported format and whether extra separators appear between them. If an import fails, test one entry on its own before processing the rest.

Always review imported details

Whether you scan a QR code or import from the clipboard, open an entry's edit screen and compare Type, Address, Port, and required authentication fields. A name is just a note; it doesn't prove the details are correct. Servers with the same name may use different addresses, and differently named entries may point to the same address. If the result is a subscription, check that it appears as a source group that can be updated, rather than as a one-time server list. Keep the subscription relationship for content that needs ongoing updates.

After importing, you can replace clipboard contents with ordinary text that contains no sensitive information to reduce the chance of pasting the link by mistake. This can't ensure that no copy remains on another device or in clipboard history, so consider the sync scope if you use a cross-device clipboard. QR code images saved in your photo library also require privacy care, especially to keep them out of public shared albums. Deleting a screenshot may limit further sharing, but credentials that were already exposed still need to be addressed through the original management channel.

If you're moving details you already have to another device of your own, first check the settings and verify the connection on the receiving device. Then clean up any temporary text and images. Don't delete the only record on the old device before confirming the new one works. A complete migration also involves Config, the selected entry, and On Demand settings; a successful QR import alone doesn't mean everything has transferred. See Delete & Back Up for a complete checklist.

04Share Link Formats and Configuration Boundaries

Check the prefix, then decide what to do with the content

Server share links usually have protocol-specific prefixes, while subscription URLs are commonly HTTPS addresses. A prefix can help identify the content type, but it can't confirm that the entire link is valid. A link with the right prefix may still be missing authentication, a port, or required transport settings. Likewise, an HTTPS URL isn't necessarily a subscription; it could point to an account page or an ordinary file. Check the source information to determine whether it represents a server, a group of servers, or a configuration file.

These prefixes help identify common content types; they aren't a complete compatibility list. Share formats can vary between protocols, and the same protocol may use different encoding schemes. Whether the app can import a link depends on its complete contents and the supported combination of settings, not just the protocol name. For an unfamiliar format, keep the original text, check the field descriptions in your source material, and review the details in Add Server without editing the original.

Encoding, query parameters, and notes each have a purpose

Authentication details in a share link may be encoded. Encoding is not encryption, and it doesn't make the link safe to share; anyone who can read it may be able to recover the server credentials. Don't add spaces, change capitalization, or delete trailing characters from a string that looks hard to read. Some formats depend on those characters, and text editors may automatically alter them. To compare details, use the original plain text instead of copying from a screenshot.

Query parameters after a question mark may determine the transport, TLS, or other connection behavior. A hash usually introduces a note, but its meaning depends on the format. Percent encoding represents certain special characters; don't delete it as if it were garbled text. If a name in Chinese displays incorrectly, first check whether the problem is limited to the note. If the address and authentication details are correct, don't re-edit the entire encoded link just to fix the name; change the display name separately after import.

Server details don't configure rules for you

Importing a server answers “where to connect and how to authenticate.” A rule configuration answers “which policy should apply to each request.” They work together, but neither replaces the other. Config rules are generally matched from top to bottom, and the matching rule applies its policy; FINAL handles requests that don't match earlier rules. The examples below illustrate rule syntax only. They contain no server credentials and aren't a complete configuration to use in place of your current settings.

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

PROXY, DIRECT, and REJECT in the examples are policy keywords. DOMAIN-SUFFIX and DOMAIN match different ranges, so don't swap them based on their names alone. GEOIP matches based on IP geolocation; it is not the same as routing by webpage language. Rules must go in the correct section of the configuration and be checked alongside the current Global Routing selection. With Proxy or Direct selected, don't use a single rule in Config to explain every access result.

For more on rule tuning, see Rule Order, FINAL, and Policy Explained. The key to maintenance is keeping information in separate layers: original share text for checking server details, subscription URLs for future updates, and Config files for rules and related settings. Naming these three separately is easier to troubleshoot than combining them into a generic link, and helps prevent missing key items during migration.

05Subscription Updates and Verifying Results

An update changes remote content, not just a timestamp

Updating a subscription requests the saved URL again and refreshes the related server entries with the returned content. An update may change addresses, ports, authentication details, or names, and may add or remove entries. It is more than a display refresh. Before updating, confirm which group and server you're using, and note any identifying details if needed. When troubleshooting a connection, comparing the entries before and after an update is more useful than simply noting that you tapped Update.

Use a manual update when you've been told the details have changed, an existing entry seems faulty, or you need to check the import result. Automatic updates can help with routine maintenance, but check the current Subscribe settings for available options and intervals. Don't assume every device will make background requests at a fixed time; system scheduling, network conditions, and app state can affect when they run. To confirm the latest result, check the feedback from the actual update.

Understand the result in three steps: request, parse, replace

If the request fails, check that the URL is complete, its access credentials are still valid, and your current network can reach it. A server connection failure and a failure to access a subscription URL are different issues and may not use the same network path. If existing servers still work, keep them rather than deleting and rebuilding the group after one failed request. Rebuilding usually won't fix an invalid URL and may remove usable entries and troubleshooting clues.

A successful request still needs to return content the app can parse. An error page may load successfully as webpage content without being a server list, so being able to open the URL doesn't prove that the subscription is valid. If an update empties the group or returns very different content, stop refreshing and recheck the original URL and its purpose. You don't need to publish the full response when troubleshooting; describe whether it contains server details, a webpage message, or an empty response without exposing access credentials.

After replacement, check the currently selected entry again. If an entry was renamed or removed, don't assume the old selection still points to the same server; the settings of an entry with the same name may also have changed. Start by checking the address and protocol of a frequently used entry, then run a test and try actual access. If only one entry changed unexpectedly, focus on that entry. If the whole group is affected, investigate subscription retrieval, account status, or shared settings.

Keep local edits separate from subscription maintenance

Names or connection settings you edit within a subscription may be overwritten by remote content; check the actual update result to see what is preserved. If a local change needs to last, record the field and reason instead of relying on memory, and mark it clearly as a local exception. If supported, keep a separate copy for testing, named distinctly from the original subscription entry. This helps avoid selecting a test copy after an update and mistaking its old settings for the current ones.

Set the update frequency according to how often the content actually changes. Repeated requests in a short period rarely fix incorrect content and can make results harder to compare. After an update fails, read the message, check the network and URL, then decide whether to retry. If you temporarily disable automatic updates to investigate, note the change and restore the usual setting when you're done. Otherwise, a temporary troubleshooting setting may be left in place and make you think the content is still updating normally.

The updated server list is not an update record for your rule configuration. If Config refers to separate remote rules or other resources, maintain them through their own options; updating Subscribe doesn't sync those resources. For a final check, verify three things: the server entries are as expected, the selected entry works, and Global Routing and the configuration still meet your needs. Checking all three helps distinguish a completed subscription update from a working connection.

06Organize and Name Multiple Subscriptions

Group by source and name by purpose

When managing multiple existing subscriptions, keep each source clearly identifiable. Give every subscription a recognizable name that indicates where its contents come from, rather than combining all servers into an untraceable list. Names can include a device purpose or custom category, but shouldn't contain passwords, access tokens, or full subscription URLs. A good source name should still tell you where to manage it days later, not just make sense right after import.

A server note and a subscription name serve different purposes: the subscription name identifies the source of a group and its updates, while the server note helps identify a specific entry. Use a simple, consistent naming scheme, such as putting your custom purpose first and keeping any useful original label. Don't put temporary test results in a permanent name; network performance changes, but names can be mistaken for facts. Remote-generated notes may also revert on the next update, so don't rely on a local rename as the only way to identify an entry.

Compare entry details, not just names, to find duplicates

Two servers with the same name may not be duplicates, and different names don't necessarily mean different connections. Before removing an entry, compare its protocol, address, port, and key transport settings while keeping authentication details private. A subscription entry and a manually added entry may have identical settings but different maintenance behavior: the former may update continuously, while the latter retains its locally saved values. Before deleting anything, decide which relationship you need to keep, not just which name to keep.

If a group has been unused for a long time, first check whether it contains the currently selected entry or whether a Config policy group refers to it by name. Renaming or deleting items can affect later selections when the configuration relies on name matching. Sorting the list only changes the order in which you find entries; it doesn't change rule priority. The top-to-bottom order of rules in Config is a separate concept from the order of servers shown in Home.

Organize across devices for clarity, not visual uniformity

When managing the same information on iPhone and iPad, consistent source names can make cross-device checks easier. Don't assume servers, selected entries, or Config files will automatically transfer in full from one device to another. Check the app's actual settings to see whether sync is enabled and what it covers. Even if both devices show the same name, verify the imported details and current configuration on each; matching notes don't prove that settings or connection status match.

Organize subscriptions in small batches. Handle one source at a time: name it, check for duplicates, test it, and back it up before moving on. If you delete several groups, rename entries, and switch configurations all at once, it will be difficult to identify where a later connection issue began. Before retiring an item, note its source and purpose, make sure the current connection doesn't depend on it, and then delete it. Distinguish temporarily unused entries from permanently retired ones in your maintenance notes.

Maintenance notes don't need to include every secret field. Group names, import methods, configuration purposes, reasons for changes, and test results are usually enough to help with troubleshooting. Keep server credentials and full subscription URLs in a protected location, separate from public notes. When describing an issue to someone else, you can say “a subscription update created duplicate names” or “the manual copy still connects” instead of sending a full export.

When you're done organizing, check the setup in its real use case instead of just looking for a tidy list: select the intended server, confirm Global Routing, open the required webpage, and check connection logs if needed. If something breaks after cleanup, first undo the most recent change instead of immediately changing DNS or all your rules. Keeping each maintenance step traceable and testable prevents routine organization from turning into an open-ended connection investigation.

07Connectivity Test, Latency, and Sorting

A test result only answers what it measures

Connectivity Test helps assess a server connection, but the result depends on the test method you selected. Different methods may check different layers: whether a connection can be established, whether a request can pass through a proxy, or whether a specific test destination is reachable. Check the app interface for the available tests and options. A reported time only shows that the test completed that particular process; it doesn't prove that every website, protocol, or sustained connection will work.

Test results depend on your current network, the target address, server status, and when you run the test. To compare servers, keep the test method and network conditions consistent. Don't mix results from different devices, times, or test targets when sorting entries. A single failure may be temporary; test again later and compare the result with actual use. Conversely, one successful test doesn't outweigh frequent disconnections. Note whether the issue is reproducible.

Troubleshoot layer by layer: connectivity, authentication, DNS, and rules

If the basic connection cannot be established, check the address and port, and whether your current network can reach the server. If the transport connection works but proxy requests fail, check authentication, TLS, and transport settings. If proxy requests succeed but some domains won't load, investigate DNS and rules instead of replacing the entire subscription. This order addresses one layer at a time and helps distinguish server problems from DNS resolution or routing issues.

If a test succeeds but a webpage won't load, check which policy the request actually uses. When Global Routing is set to Config, rules determine the policy from top to bottom. Proxy and Direct are different overall routing modes, so a server test alone can't tell you how a webpage is routed. First confirm the current mode, then check whether the request uses the expected server. If connection logs are available, review the domain, policy, and error together instead of focusing only on a latency value.

Sorting helps you find entries; it doesn't establish long-term quality

Sorting by test results can move entries with faster responses in this test closer to the top, but that order isn't a lasting quality ranking. Response time, sustained throughput, and connection stability are different measures, and the most suitable test target may vary. If a test fails, first check for missing settings or temporary unavailability instead of immediately deleting the entry. For subscription entries, a later update may also change the connection details.

To verify an entry, select it and complete a real access test: check the system's connection status, open the target webpage, and confirm the result. If only some pages fail, compare accessible and inaccessible domains while keeping the server and mode unchanged. Change one condition at a time to determine whether switching servers helped or whether rules, DNS, or the destination itself caused the difference.

When recording a test, include the context needed to reproduce it: network, test method, current server, Global Routing setting, and the observed issue. Error messages may contain private domains or parameters, so redact them before sharing. If only one destination is affected, test that destination rather than relying on batch results. If the entire network is unavailable, first confirm that the device itself has a working internet connection, then check Shadowrocket's server and configuration settings.

After sorting, check the current selection; changing list order doesn't necessarily switch the app to the first entry. When you're done, note the current state: which source the selected entry comes from, which mode is in use, and whether temporary changes have been reverted. This gives you a known starting point the next time an issue occurs, rather than leaving you to guess what changed during the last test. For the full first-connection workflow, follow the setup guide.

08Delete, Back Up, and Restore on Another Device

Confirm what you're deleting

Deleting a server, a Subscribe group, and a Config file have different effects. A server is one connection entry; a subscription group contains entries and their update source; a configuration file contains rules and related settings. Read the confirmation prompt and check whether the current connection depends on the item before proceeding. Don't assume all delete actions have the same consequences, especially when troubleshooting; avoid deleting your rule configuration along with server data.

A deleted entry in a subscription may return during the next update if it is still present in the remote list. A standalone local entry doesn't have the same source for restoration. If you want to exclude an entry permanently, check the app's filtering or management options instead of repeatedly deleting it. Restoring a deleted group usually requires the original subscription URL and valid access. A server name alone can't recreate the complete subscription relationship.

Check backups by source, server details, and configuration

A backup should cover the items you actually need to restore. A subscription URL lets you retrieve servers again; standalone servers require complete settings; Config requires the file and any related dependencies. Also note the current selection, Global Routing, and On Demand settings if needed. Check the current interface and exported content to see what the app's export, share, or backup options include. Don't assume any one export contains every setting.

1. List your existing subscription sources and make sure you can retrieve each original URL from a protected record.
2. Check whether manually added servers have complete details saved separately, and distinguish them from subscription copies.
3. Save any Config files you need to move and check that their remote resources are still available.
4. Record the current mode, selected entry, and any required On Demand settings.
5. Verify the restored setup on the receiving device before deciding whether to clear the old device or temporary export files.

Exports may contain passwords, UUIDs, private keys, or subscription access credentials. Save them somewhere protected and restrict access. Public cloud links, group chat files, and public notes are not suitable for complete connection details. If you use system file storage or device backups, check the access protections on your account and device. The goal is to be able to restore your data, not to make extra copies. Scattered files with unclear versions can increase the risk of using or exposing the wrong information.

Restoring the app and restoring connection details are separate tasks

After changing or resetting a device, restore your Shadowrocket purchase through the App Store before restoring subscriptions and configurations. The app purchase and server details are separate; getting the app again doesn't restore all your connection information. For purchase and redownload steps, see Restore a Previous Purchase. System requirements, purchase eligibility, and compatibility are as listed on the App Store page; don't infer them from another device's status.

On a new device, restore one source or server first, check its settings, and verify the connection before restoring anything else. After restoring Config, check that it is selected and that referenced names, resources, and servers are still available. If you made local exceptions on the old device, restore them one at a time from your maintenance notes instead of importing every test copy and guessing which one is current. Restoring in small batches makes omissions easier to spot.

Complete a verification cycle before deleting anything

A migration is complete when the setup works, not when the number of imported items looks the same. At a minimum, confirm that the selected server connects, commonly used destinations work, Global Routing is set as intended, and On Demand matches your needs. You may need to authorize the connection again on the new device; follow the system prompts. Don't erase the only working standalone server details from the old device before verification, and don't mistake a screenshot of a name for a backup.

If you accidentally share a full subscription URL or server credentials, deleting the message or local file won't invalidate copies that have already spread. Use the original account or server management channel to address the exposed credentials, update the saved details on your devices, and verify the connection again. Keep necessary change records, but don't copy old secrets into troubleshooting notes. Review your backups afterward so you don't restore information that has been exposed or invalidated.