Official Manual · Server Management
Shadowrocket Subscription and Server Management
Find instructions by task for importing, updating, organizing, and backing up. All procedures assume you already have subscription or server details.
New users can start with the quick start guide to establish a connection, then return here to check specific fields and management steps. The tutorial explains how to connect; this guide explains what data is saved, what updates change, and how to troubleshoot problems.
- Subscribe
- Add Server
- Connectivity Test
- Deletion and Backups
Shadowrocket is a paid commercial app for Apple platforms. The one-time app purchase is separate from any service plan. The App Store is the only place to get the app; see how to verify and get the genuine app before purchasing. This manual covers managing information you already have; it does not provide, sell, or recommend servers or subscriptions.
Chapter 1 · What You’re Importing
Subscribe: Add an Existing Subscription
A subscription is an address used to retrieve a server list, not a server itself. Shadowrocket requests the address, parses the response, and adds any recognized server entries to the list. The subscription address tells the app where to get updates; each entry describes how to connect. Knowing the difference helps explain why re-entering a single server won’t fix a subscription update failure—and why a login page isn’t a subscription address.
Make Sure You Have a Subscription Address
Before importing, check the purpose described in the information you already have. A subscription address is usually a full URL, often with a long path and query parameters. A management page may require you to sign in before viewing its contents. They can look similar but return different data. Don’t identify an address by a single English word or remove parameters that look random; they may control access, and deleting even one character can return the wrong content.
Copy the entire address from beginning to end, and check whether a chat app or document has wrapped it across multiple lines. A visual line break may not be part of the original text, but joining lines manually can add spaces. Use the copy function in the original source when possible, then check the protocol, domain, and trailing parameters in the input field. Don’t paste the address into a search box or attach it to a public support request: anyone with the full address may be able to retrieve the same server details.
Add a Subscribe Entry from Add Server
Open Home, tap Add Server, choose Subscribe under Type, and enter your existing subscription address in URL. The layout may vary by device or app wording; the key is to select Subscribe rather than a single-server protocol. Add a recognizable remark, save, and wait for the list to load. For your first import, add one subscription at a time so you can identify the address if anything goes wrong.
Return to Home after saving and check for the expected subscription group and server entries. Seeing the subscription name only confirms that the management entry was created; it doesn’t prove that remote content was parsed successfully. Check whether the number of entries is roughly consistent with the information you have, whether the protocol types are recognized, and whether any errors appear. If the list is empty, keep the subscription entry, note the message, and check the address and network. There’s no need to add the same subscription repeatedly.
If the import succeeds, select a server with known, correct details and follow the tutorial to connect and verify it. A successful subscription update, a selected server, an enabled connection switch, and working requests are four separate states. Completing the first one does not prove that the entire connection works. For the order of server selection and enabling the switch, see First Connection Checklist.
Troubleshoot Based on Where the Failure Occurs
For an invalid address or a failed request, first check that the address was copied in full and that the current network can resolve the domain and connect to the internet. For authentication or permission errors, verify that the address you already have is still valid; don’t repeatedly change unrelated fields such as protocol or port. If the response is actually a webpage, login prompt, or plain text, the app may be able to reach the URL without being able to parse it as a server list. Confirm what the original information was intended to export.
If the same address behaves differently on different networks, record the network conditions for each attempt before checking whether DNS, the route, or connection status is involved. Don’t switch networks, change address parameters, and select a different server all at once; changing several variables makes the result hard to interpret. There’s also no need to assume updates must go through a proxy. The route that works depends on the current network and whether the address is reachable.
A successful import doesn’t mean every entry will work, or that the subscription includes routing rules. Check the server list separately from the rules in Config. Before moving on, note the subscription’s local name, the result of its most recent actual update, and the currently selected entry. These details give you a clear reference when adding servers manually, updating, and sorting later.
Chapter 2 · Checking Server Fields
Add Server: Enter Server Details Manually
Manual entry is useful when you already have complete server details, need to check an entry, or want a separate copy for testing. Unlike Subscribe, it saves connection details locally rather than an address used to retrieve a list. In Add Server, choose the Type that matches your existing details, then fill in the required fields. Authentication varies by protocol, so don’t paste every string from your details into whichever field looks similar.
What the Address, Port, and Authentication Fields Do
A server address is usually a hostname or IP address. Don’t paste in a full URL with a web protocol, path, and port unless the field specifically asks for a complete URL. The port is a separate number that identifies the remote service endpoint and must match the details you have. A remark is only for identifying the entry locally; it won’t fix an incorrect address, port, or password. Use the remark to describe its purpose, not to store a full password or other authentication details.
Authentication fields depend on the protocol. Shadowsocks requires the encryption method and password to match the remote server. VMess and VLESS commonly use a UUID as an identity field. Trojan uses password authentication; check the TLS settings against the details you have. For HTTP and SOCKS5, whether you need a username and password depends on the server. Two long strings aren’t interchangeable just because both fit in a field: a UUID, password, and key serve different purposes.
| Field category | What to check | Common mistakes |
|---|---|---|
| Address and port | The hostname or IP address you have, and its corresponding port | Pasting a full webpage URL into the host field |
| Authentication | Password, UUID, or protocol-specific key | Copying extra spaces or mixing up authentication types |
| TLS | Whether it’s enabled, the Server Name, and certificate requirements | Using the connection address as the certificate name |
| Transport settings | The transport type, Host, and path in your existing details | Missing the path or changing letter case |
Check TLS and Transport Separately
TLS establishes a protected connection; transport settings describe how protocol data is carried. Both may be configured, but they aren’t the same setting. The connection address may point to an endpoint, while Server Name is used for TLS name verification and Host may be part of a transport request. These values may or may not be the same. Check each one against your existing details rather than assuming the other names can be omitted because the address resolves.
The path is also part of the settings: its leading slash, letter case, and query string can all affect how the remote service identifies it. Watch for input methods that replace punctuation, especially full-width colons, spaces, and curly quotation marks. For certificate errors, check the device time, Server Name, certificate validity, and existing settings instead of disabling verification. Relaxing verification changes the security boundary and may hide the actual configuration error.
WireGuard has a different configuration structure from common password-based proxies. It uses details such as a local interface key, peer public key, Endpoint, and address ranges. Hysteria2 has its own authentication and transport requirements as well. Don’t apply troubleshooting steps for one protocol to another. If your details include only a name and address but omit required authentication information, get the original parameters rather than guessing defaults from the protocol name.
Save and Check One Server Before Expanding
After entering the details, reopen the entry to check what was saved, then select it and test the connection. Before editing an entry that already works, keep a record of its original details or create a clearly labeled test copy. Change one related set of fields at a time—for example, check only the transport path rather than changing the port and DNS as well. Record the error stage before and after each change to see whether it actually resolved the problem.
A manual copy usually won’t sync automatically when its original subscription updates, so it’s useful for short-term troubleshooting, not as a permanent replacement for remote management. Label its purpose when testing is done to avoid selecting an outdated copy later. Conversely, don’t assume that changes made to an entry in a subscription will survive future updates. Record important edits separately and check them against the latest remote details later.
Check the settings in this order: Type, address and port, authentication, TLS, transport, and finally the actual request. A consistent sequence makes differences easier to spot when reimporting details or receiving new ones. For the distinction between interface labels and rule terms, see the Quick Reference to avoid confusing server remarks, policy names, and protocol types.
Chapter 3 · Import Methods
Scan QR Code and Import from the Clipboard
QR codes and the clipboard are input methods, not server protocols. They may contain a single server share link, a subscription address, or just plain text. Before importing, know what kind of entry the information is supposed to create, then check the result. Recognizing a QR code only means its image was read; reading the clipboard alone doesn’t prove that its contents are suitable for the current import option.
Check the QR Code and Source Before Scanning
When using Scan QR Code, keep the entire code inside the viewfinder with some clear space around it. Avoid glare and blur. If the code is on another device, try increasing its screen brightness and adjusting the distance. Don’t crop the central pattern; the positioning markers around the edges are needed for recognition. Enlarging an image that has been compressed repeatedly only magnifies blurry pixels, so use the original clear image whenever possible.
The system may ask for camera access the first time you scan. Grant the permission needed to scan, and if you previously denied it, check Shadowrocket’s permission in system settings before trying again. Camera permission only controls whether the app can use the camera; it doesn’t determine whether the QR code is valid. If scanning still fails after permission is granted, check image clarity and encoded content separately instead of toggling every system permission.
After recognition, check the type of entry the app is about to create and any visible details. If you expected a Subscribe entry but got a plain URL or a single server, stop before saving and check the source. Don’t replace an existing subscription just because a result appeared. A QR code for a login page or management task won’t become usable server details just because Shadowrocket scanned it.
Keep the Entire Text When Importing from the Clipboard
Copy the complete share text from the information you already have, then return to Shadowrocket and use the relevant clipboard import prompt or option. If the system asks to allow pasting, respond based on the action you initiated. For multiline text, check the boundaries and original format of each line so you don’t include instructions, list numbers, or quotation marks by mistake. A single invisible space in a long string can change the result.
Some chat apps automatically create a preview card for shared content. Tapping the card and copying the original text may produce different results. To import, copy the actual share link, not the card title. For a “format not recognized” message, check locally that the opening identifier is complete and the end hasn’t been cut off. Don’t upload authentication text to an online conversion site to troubleshoot; that could expose sensitive information.
If you copied multiple entries at once, check after importing that none are missing or duplicated and that each protocol matches what you expected. A few successful entries don’t mean the entire text was parsed. First confirm the import method with one complete entry, then handle a longer list. Before a batch import, note the entries that already work; afterward, check the new entries against their remarks so you can distinguish them from the old ones when cleaning up.
Verify the Connection After Import
After saving, return to Home and check the new entry’s remark, type, address, and port. Then select one server and connect. If only a name appears and key details are missing, check whether the source contains the complete share information. If all fields are present but the connection fails, check authentication, TLS, transport, and the current network. Changing the scanning distance won’t alter saved details or fix a server-side rejection.
Scanning the same QR code again may create a duplicate; it won’t repair the existing entry. Check for a matching record before scanning again. Two entries with the same name may still differ, so compare their protocol, address, port, and group before deciding which to keep. If you’re not sure, give the test entry a distinct remark rather than deleting the record that already works.
The original information may remain on the clipboard after import. You can replace it with ordinary text, and check whether any settings sync clipboard contents to other devices. Protect saved QR code images as part of your backups as well. Scanning reduces manual entry; it doesn’t make the original credentials less sensitive. Handle later updates and revocation according to whether the entry belongs to a subscription or a server.
Chapter 5 · Refreshing Data
Subscription Updates and Troubleshooting Failures
Updating a subscription requests fresh remote content and uses it to refresh the local server list. It doesn’t update Shadowrocket or reconnect the current server. The app is purchased, installed, and updated through the App Store; see how to get the app. When managing servers, first identify whether you’re working with a subscription, an individual entry, or connection status to avoid repeated attempts at the wrong level.
Use Manual Updates to Create a Checkpoint
After the first import, perform a manual update and check the result. Before updating, note the group name, currently selected entry, and key settings. Afterward, check the message, changes to the list, and whether the current selection is still there. Remote updates may add or remove servers, change names, or adjust authentication details, so a different entry count doesn’t necessarily indicate a problem. Conversely, a success message with no visible changes may simply mean the remote list hasn’t changed; the list alone can’t prove that no request occurred.
If you’ve edited an entry that belongs to a subscription, record your changes first. Don’t assume every local edit will survive an update; refreshing may recreate an entry or overwrite remotely managed fields. For test settings you need to keep, create a separate manual copy labeled with its purpose and note how it relates to the original subscription. The copy won’t track subscription changes automatically, so check it manually later.
While updating, avoid changing rules, switching networks, and deleting servers at the same time. Update once on a stable network, wait for a clear result, and then decide what to do next. If the selected server disappears after an update, choose another entry with valid details and test the connection. An enabled connection switch doesn’t guarantee that a new server has seamlessly replaced the previous selection; verify with an actual request.
Consider Device and Network Conditions for Automatic Updates
If the app offers automatic updates or related scheduling options, enable them as needed and use the options currently available in the interface. More frequent updates aren’t always better; they can use data unnecessarily and repeat temporary errors. When choosing a schedule, consider how often remote content changes, when the device is online, and whether you need to check manually before use. A manual check before an important task is often more reliable than assuming a background update has completed.
Background activity on mobile devices depends on system scheduling, network conditions, and battery status. Automatic updates don’t guarantee execution exactly as scheduled. If the app hasn’t been opened for a long time, the network has just returned, or the device is under restrictions, open the app and check the current list. Don’t assume an unobserved background refresh means the subscription has expired, or infer that the last request succeeded from the device’s clock.
If a remote address is reachable only through a particular route, the update result may depend on the current network and connection status. When troubleshooting, record whether you were connected during the update, which server was selected, and whether you were on Wi-Fi or cellular. Change one condition and try again to see whether the route is involved. Don’t keep routing changes indefinitely if their purpose is unclear.
Troubleshoot at the Request, Authentication, and Parsing Stages
For request failures, check connectivity, DNS, address spelling, and timeouts. For authentication failures, check that access parameters in the address are complete and haven’t been replaced, and verify the permission status you already have. For parsing failures, check whether the content is intended for this use or has become a login page or error message. Each stage calls for a different response. Repeatedly tapping Update won’t restore missing parameters or change the format of remote content.
If an update fails but the original list remains, don’t delete the subscription just to “start fresh.” Existing entries may still work, and deleting them can make recovery harder. Save the error message and original details, check the address, and then retry. If an update succeeds but every server becomes unusable, compare fields shared across the entries, such as authentication or transport settings, rather than changing every remark one by one.
Track subscription status and request status separately. The update time shows when the list was refreshed; Connectivity Test shows the result under a particular test condition; actual access shows what happens to the current request. Together, they help narrow down a problem. If a subscription can’t be updated for a long time, check the original information using the error stage and network conditions, with sensitive details hidden, rather than sharing the full subscription address.
Chapter 6 · Organizing Lists
Name, Group, and Select Multiple Subscriptions
When you have multiple subscriptions, the goal isn’t to merge every entry into one long list. Keep their ownership clear. Each server should be traceable to its subscription or manual record, and each subscription should have a recognizable local name. Then you’ll know which group an update, troubleshooting step, or deletion affects. The longer the list, the more useful a consistent naming scheme becomes; don’t rely on remembering a server’s current position.
Use Names to Describe Purpose, Not Authentication Details
Name subscriptions for their purpose or category, such as “Everyday,” “Testing,” or “Device migration check.” These names are for local organization and don’t rate the remote service. Avoid putting full access addresses, account details, or passwords in remarks. If you use the same information on multiple devices, you can note the relationship between devices and entries in your own records. Changing a remark doesn’t change remote access permissions.
Keep subscription names, server names, and the current selection distinct. A subscription name identifies an updateable collection; a server name identifies one entry in that collection; the current selection determines which connection object is used when a proxy policy applies. Servers with the same name may come from different subscriptions or use different authentication details. Compare ownership, protocol, address, and port; don’t delete entries just because their names match or assume similarly named records are backups of each other.
If the interface offers group collapsing, search, or other organization features, use them to reduce the number of visible entries. Search changes what you can find or see; it doesn’t remove other servers from the subscription. Clear the search and check the full list before cleaning up, so you don’t mistake filtered results for all your data. Before deleting a group that looks empty, check that it isn’t collapsed, unopened, or still waiting for an update.
Keep Manual Copies Separate from Remotely Managed Entries
Label a troubleshooting copy with its purpose and the original entry it corresponds to, such as “Check transport settings.” Keep it to test a specific variable, not as a permanent duplicate of the whole subscription. Once the problem is resolved, decide whether the copy is still needed and remove it through your backup process if not. Otherwise, repeated troubleshooting can leave many similarly named entries and make it difficult to tell which are still managed by subscription updates.
When moving between two similar subscriptions, keep them side by side long enough to compare rather than immediately giving them identical names. Select a server with known details from each, record the connection results, and then choose which subscription to use day to day. If you need both, use names that remain easy to tell apart. Don’t judge reliability by the number of entries or treat one latency test as proof of long-term availability.
If a remote update changes a name significantly, confirm ownership using the actual fields rather than searching only for the old name. The remote service may change a remark while keeping the same endpoint, or keep the remark while replacing the address. For important entries, keep a small set of identifying details in private notes, but don’t copy all authentication details to multiple places. The more copies you make, the easier it is to miss an old one when access details change or are revoked.
Check Server Selection and Routing Mode Separately
After selecting a server in Home, check Global Routing as well. Config mode uses rules in the current configuration to handle requests. Proxy mode routes requests handled by that mode through the proxy path. Direct mode handles them directly. Switching modes can help identify a request path, but it doesn’t change subscription content or make an invalid server entry work.
| Object | What it usually changes | What it doesn’t prove |
|---|---|---|
| Subscription update | The associated server list and remote settings | That all requests can access their destinations |
| Current server | The connection object used by proxy policies | That every request uses this connection |
| Global Routing | Overall request handling mode | That authentication and transport settings are correct |
| Config | Rule order and related settings | That the subscription address and server list are updated |
If a configuration refers to specific names or policy relationships, check dependencies before renaming or deleting entries. A tidy list isn’t worth breaking the current configuration. After handling one subscription, verify the current selection and routing path before moving to the next. Working in batches makes it easier to roll back and keeps changes from two updates from getting mixed together during troubleshooting.
After organizing the list, test it in a normal usage scenario rather than stopping at the list screen. Confirm that common requests use the expected route, then remove test entries that are no longer needed. For the distinction between rules, on-demand connections, and diagnostic features, see the Feature Guide. Server ownership is still determined by the local list and original information.
Chapter 7 · Diagnostic Results
Connectivity Test, Latency Tests, and Sorting
A latency test shows how a particular test request responded under the conditions at the time. It doesn’t measure sustained throughput, access to every website, or future reliability. Different test methods may cover different parts of the connection, so interpret results in light of the method used. Check the test type shown in the interface, then compare results using the same method on the same network. Don’t use numbers from different times and networks to declare one server the best long-term choice.
Keep Testing Conditions Consistent
Before testing, confirm that the device is online, pause tasks that use substantial bandwidth, and note whether you’re on Wi-Fi or cellular. If you’ve just switched networks, wait for the connection to stabilize. Wireless quality between the device and access point, network load, and remote service status can all affect the result. One fluctuation alone doesn’t mean the server settings are wrong.
Use the same method when comparing a group of servers. One method may mainly measure how long it takes to establish a connection to a port; another may also include TLS or an application-level response. Don’t compare the numbers directly. If the interface doesn’t explain the method in enough detail, treat the results as a way to screen entries in the same test run, not as a precise network report. The same server can show different results when the test target changes.
Use a server with known, correct settings as a baseline before checking entries that may be faulty. If all entries time out, first check the device network, DNS, and whether the public test target is reachable. If only one entry fails, check its address, port, authentication, and transport settings. Distinguishing shared failures from individual ones is more effective than re-entering every password and helps preserve entries that already work.
Verify the Actual Connection After a Successful Test
After using Connectivity Test, select the target server and make an actual request. A successful test means that the test path returned the expected result under those conditions; it doesn’t mean every rule in Config uses the same path. If the test succeeds but a particular domain doesn’t, check its rule match, DNS resolution, and destination service. A low latency result alone doesn’t rule out DNS or routing issues.
For a failed test, check which stage failed. An address that won’t resolve, a connection timeout, rejected authentication, and a TLS error each call for a different response. If you see an error message, record its wording with sensitive details hidden. If there’s no clear error, repeat the test on the same network, then try one changed condition. Frequent repeated tests add requests and are usually less useful than systematically narrowing down the problem.
If common requests fail while others work, compare the policies they match in the current configuration. If needed, briefly switch Global Routing to help verify the route, then restore the original mode. A change in results only indicates that the route is worth checking; it doesn’t prove that every rule is wrong. For DNS selection and resolution issues, see the DNS Setup Guide.
Sorting Changes the List, Not the Selection
Sorting by latency groups entries with faster results in the current test run, making them easier to try. After sorting, check which server is selected; the first entry doesn’t automatically become the current selection. Sorting and automatic selection are different features, so rely on the state shown in the app. List positions may change after the next update or test. Use recognizable names and ownership details in your records.
Moving entries that time out to the bottom can help prevent accidental selection, but don’t delete them based on a single timeout. Temporary network problems, a test target issue, or remote maintenance can all produce similar results. Retest one entry to confirm whether the failure persists before cleaning up. If the servers belong to a subscription, deleting entries locally may not stop them from reappearing after an update; consider their subscription ownership when making long-term changes.
After testing, select a server with clear settings that suits your current requests, restore your usual Config, and verify with actual use. If you temporarily changed DNS, routing mode, or transport settings, restore them or note which changes you’re keeping. Without this step, a “working” result may depend on a temporary combination of settings and be difficult to reproduce after switching networks.
For recurring problems, keep a few comparable records rather than accumulating logs and screenshots containing authentication details. Check whether the issue consistently recurs under the same conditions and consistently disappears after changing one setting. This helps distinguish occasional fluctuations from configuration errors and makes it easier to retest after server details are updated.
Chapter 8 · Managing the Lifecycle
Delete, Back Up, and Restore a Working Setup
Before deleting anything, identify the object and its scope. Deleting a single server, removing a subscription, removing Config, and reinstalling the app have different effects. A server is one connection entry; a subscription also includes its update address and ownership; Config may contain rules and related settings. “Delete everything and start over” isn’t a universal troubleshooting step. Deletion is manageable only when you have enough information to restore what you need.
List What You’ll Need to Restore
Consider backing up at least four types of information: subscription addresses and their local names, manually entered server details, the current Config, and notes about settings needed to reproduce the current state. An export may include only some of these. A saved file doesn’t necessarily mean everything can be restored. When using the app’s available backup or export feature, check its instructions and actual contents, especially whether authentication details and subscription access addresses are included.
Also record the currently selected server, Global Routing mode, and settings that may need to be restored manually. Restoring the server list without the correct rules and selection may still produce different results. Note On Demand and other automatic connection settings separately; after restoring, first confirm that a manual connection works, then check automatic triggers. Don’t treat system-level authorization as ordinary configuration text.
Keep backups somewhere you control with appropriate access protection. Files containing subscription addresses, passwords, UUIDs, or keys shouldn’t be shared publicly. If you use personal storage that syncs files, know which devices can access them. To limit exposure, keep routine troubleshooting notes to field differences and status; store complete credentials in as few backups as necessary.
Keep a Verified Recovery Path Before Deleting
Before removing a duplicate entry, compare its subscription, protocol, address, and port, then check whether the current selection depends on it. If a subscription manages the entry, deleting it locally doesn’t change the remote list, and an update may add it again. To stop managing an entire set of entries, check the scope of removing the subscription instead of deleting them one by one and repeatedly updating the same address.
Before removing a subscription, make sure you still have a valid address and the necessary original details. If the address has expired, keeping the old list doesn’t guarantee future connections. Conversely, a valid address won’t restore local remarks or manual edits automatically. Record changes you need to keep separately. Before deleting in bulk, handle one group and verify the result, then move on to the next so you don’t lose every point of comparison at once.
If only one entry fails, first stop using it or select another verified entry, then check its settings. There’s no need to rebuild all your data immediately. Reinstalling the app won’t fix expired remote credentials. Purchase records and server details are separate: restoring a purchased app from the App Store doesn’t guarantee that subscriptions, manual settings, and rules will all be restored. For purchases and moving to a new device, see Restore Purchases.
Restore in Order: Import, Select, Configure Rules, Verify
On a new device or after a cleanup, first confirm that Shadowrocket was installed through the App Store. System requirements are as listed on the App Store page. Then import an existing subscription or a manually entered server, check its fields, and select it to connect. If prompted to add a VPN configuration, read the system notice and grant the necessary permission. Verify the smallest working connection first, then restore other groups and settings gradually.
Once a server works, restore and select the intended Config, check Global Routing, and test how common requests are handled. Restore On Demand and other automation settings last. This order helps distinguish a connection failure from unexpected rules or trigger conditions. If you restore everything at once, it’s much harder to tell which layer caused a problem.
After restoring, don’t stop at checking whether entries appear in the list. Run Connectivity Test at least once, then verify an actual request to confirm that the current server and configuration behave as expected. Check key fields for manual entries and perform a controlled update for subscription entries to confirm that the address still works. A backup reflects one point in time; it can’t guarantee that remote authentication, server endpoints, or permissions remain unchanged.
Keep one verified, recoverable backup, then remove test copies and old sensitive files you no longer need. To review the first connection steps, return to the tutorial. To understand the difference between purchasing the app and service access, see App Purchase and Service Costs. For routine maintenance, follow the same sequence: identify the object, record its status, then update, edit, or delete it.