Official Guide · Server Management

Shadowrocket Subscription & ServerManagement Guide

For your first connection, follow the setup guide to import a server, connect, and verify the connection. This page is a reference for looking up specific details when you already have subscription or server information and need to check fields, update entries, or migrate records. Interface labels refer to iPhone / iPad; on other platforms, use the equivalent options shown on your device.

Get Shadowrocket: iPhone and iPad users can buy it on the App Store for a one-time payment of $2.99; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free, with installers available from this site at /dl/. The one-time app purchase is not a service subscription. This site does not provide, sell, or recommend servers or subscriptions; this guide covers only information you already have.

Subscribe: Add a subscription and check its entries

In Home, open Add Server and choose Subscribe to add a subscription URL you already have. Get the URL from your service provider. This saves a subscription source that can be fetched again; server entries become available after it is read. Don’t enter a single server share link in the subscription URL field, and don’t assume that a URL will work in Subscribe just because it opens in a browser.

First, identify what kind of information you have

A service may provide a subscription URL, an individual server link, and a list of parameters. They serve different purposes: a subscription maintains a changing set of entries; a single link shares the settings for one server; and a parameter list is for entering fields one by one in Add Server. Manage configuration files in Config; they mainly contain routing rules and related settings. File extensions, QR code appearance, and labels don’t tell you which type of information you have. If in doubt, check the source’s description of the data.

Information you haveWhere to enter itWhat to check after saving
Subscription URLSubscribeCheck that the expected servers appear under the subscription
Single server share linkScan the QR code or import from the clipboardCheck that the entry’s protocol and address match
Server parameter listAdd ServerCheck each required field against the list
Rules configuration fileConfigCheck that the active configuration and rules are correct

Check the list after saving, then connect

Copy the complete URL, including its original protocol prefix, path, and query parameters. You can remove a trailing line break or extra space accidentally included when pasting, but don’t delete characters from the URL just because they look meaningless. Use a short, recognizable label for the subscription; don’t use an account name, credentials, or the full URL. To identify the same subscription on multiple devices, use a consistent label and note its purpose in each device’s own records.

After saving, return to Home and expand the subscription. Check familiar entries by label, protocol, and address. If you see the subscription name but no entries beneath it, first check whether it’s expanded, then see whether an update has completed. Once the entries check out, select a server you recognize and are authorized to use, then verify it with an actual connection. Entries appearing in the list, a server being selected, and a successful request are three separate outcomes; one doesn’t prove the others.

Handle subscription read errors separately from connection errors

If the first fetch fails, make sure the device’s regular network connection works, then compare the copied text with the original source. Check whether a chat app split, truncated, or quoted the text. If the fetch completed but no entries appeared, first check that you chose the right type of information and that the returned content is compatible with Subscribe. If an update returns an account prompt or an ordinary web page, check access to the subscription itself. Repeatedly changing Global Routing won’t turn a web page into an importable list.

If the list is complete but the selected server won’t connect, troubleshoot the server itself. In Home, confirm that the selected entry is the one you just checked, then test another known-working entry in the same subscription on the same network. If only one entry fails, keep a record of it and check its address, port, and protocol. If several entries in the same subscription fail, check the network, subscription status, and routing. Change one thing at a time and record the result so you can tell what worked if a retry succeeds.

Add Server: Enter server details by protocol

Use Add Server to enter details manually only when you have the complete server parameters. Choose the protocol first, then enter the address, port, authentication, and transport settings exactly as provided. If you choose the wrong protocol, the form may still save values in the wrong fields. If you already have a working entry, keep it and create a separate test entry. Decide whether to replace it only after confirming the new entry works.

Separate common fields from protocol-specific fields

Enter a hostname or IP address in the address field, and the port number specified by the server in the port field. Unless the interface explicitly asks for a complete URL, don’t put the protocol prefix, path, query parameters, and port together in the address field. If the information includes an IPv6 address with a port, distinguish the address from the port. Square brackets that enclose the complete endpoint aren’t part of the address, and you shouldn’t split an IPv6 address at an arbitrary colon. A label is only for identifying the entry; it doesn’t affect the connection.

ProtocolAuthentication or key settingsDon’t enter these in the wrong fields
ShadowsocksThe encryption method and password must match the serverThe encryption method is separate from the password
VMess / VLESSUUID and the specified transport settingsUsing the same UUID format doesn’t make protocols interchangeable
TrojanPassword and the specified TLS settingsDon’t use the label or address field for the password
Hysteria2Authentication and the specified TLS settingsDon’t copy settings from an entry using a different protocol
WireGuardKey, interface address, and peer parametersPublic key, private key, and peer address serve different purposes

Distinguish address, SNI, Host, and Path

The server address determines where the connection goes. When TLS is enabled for a protocol and transport that support it, SNI is the server name sent during the handshake. The information may also include Host or Path for the relevant application-layer transport. For example, a server address may be an IP while TLS uses a domain name; that doesn’t mean you should enter the same value in every field that accepts a domain. Reuse a value only when the source specifies that it applies. Select the right transport first, then fill in its required fields. If a field isn’t shown, check the protocol and transport rather than entering the value in a similarly named field.

Leaving a field blank is a valid choice. Don’t enable optional settings that the source doesn’t specify. A default value isn’t necessarily right for every endpoint. If the source explicitly specifies an empty value, leave it empty rather than copying a parameter from another entry. When copying a password, UUID, or key, check for accidental spaces or line breaks, but don’t change capitalization. Saving only means the client accepted the input; it doesn’t confirm that the server accepts the authentication, transport, or certificate name.

Troubleshoot based on when the error occurs

After saving, select the new entry in Home and test it on the same network. If it times out completely, check the address, port, and whether the current network can reach the endpoint. If the endpoint is reachable but authentication fails, check the protocol, password, or UUID. If the handshake starts but TLS or the upper-layer transport fails, check the relevant SNI, Host, Path, and other parameters. Error messages don’t always identify the cause precisely, so don’t change a password based only on a generic timeout. When comparing with an imported entry for the same server, first confirm that both entries point to the same endpoint.

Change one field at a time and retest the same request after each change. If the old entry connects but the new one still fails, compare their visible protocol and transport settings; this is easier than rebuilding the entire subscription. If the new entry works, give it a clear label and note which values came from the source and which were left at their defaults. This record, without sensitive values, will help you identify the fields to update if the port or credentials change later.

QR code and clipboard imports: Check the imported data

A QR code and the clipboard are just ways to carry data; the content determines what gets imported. A QR code may contain a single server link, a subscription URL, or a web page. A successful scan doesn’t mean a server has been added. First identify what kind of information the code or text contains, then import it using an option available on your device. If the app is using another connection, note the selected entry’s label before importing so you can restore the previous state afterward.

Use Scan QR Code and check the result

In Home, open Scan QR Code. When scanning a code on another screen, keep the entire code and its surrounding margin visible. Avoid cropping, glare, or displaying it too small. If the system asks for camera access, grant it only if you intend to scan with the camera, following your device’s prompts. If the QR code is on your device and the scanner offers image selection, choose the saved image. If it doesn’t support images, use the original text instead. Don’t upload the image to an online decoding site.

After scanning, review the content shown in the app before continuing. If it’s an ordinary URL, an unexpected subscription, or an unfamiliar protocol, cancel and check the original source. Some QR codes appear on pages with explanatory text, and a separate code nearby may simply open a web page. Don’t mistake the code that scans successfully for a server entry. After saving, return to Home and check whether you added a single entry or a subscription containing several entries. Confirm that the address and label are recognizable and match the source.

Import one complete entry from the clipboard

Copy only the data for the entry you want from the original text. Don’t include its heading, number, code fence, or surrounding explanation. A chat app’s visual line wrapping may not add actual line breaks, while manual line breaks can corrupt the link. Check both ends of the selection, then use the app’s clipboard import option. If the system asks permission to paste, continue only if the clipboard contains what you just copied. Don’t restore old server credentials from clipboard history when you don’t know where they came from.

For bulk text, test with a single entry first; don’t assume every format supports importing a whole block. If the text contains multiple addresses, notes, or labels, copy the target entry on its own from the original source, then check that it wasn’t added to an existing subscription by mistake. Don’t import the same link by both QR code and clipboard just to make sure it works. Importing it twice can create duplicate entries and make it hard to tell which one you tested.

Distinguish between unread data, data that wasn’t added, and an entry that won’t connect

If the data wasn’t read, scanning may do nothing or the pasted text may not even be recognized as having a protocol prefix. Try another way to import the same original data. If it was read but not added, check what type of content was recognized, whether all fields are present, and whether you completed the save step. If it was added but won’t connect, select the imported entry and check its protocol, port, authentication, and transport settings. Scanning again can repeat the import, but it can’t fix an unavailable endpoint.

An import may succeed but the new entry remain out of sight because its group is collapsed, a filter hides it, or its imported label differs from the original display name. Expand the group and look by type, then open the entry and check its actual address. Don’t delete a same-named entry just to move the new one to the top of the list. When reporting a failure, say whether you used a QR code or the clipboard, which confirmation step you reached, and how the list changed before and after saving. Don’t include the actual link or QR code in your report.

Update subscriptions: Compare changes before switching

Updating a subscription fetches its server list again. It doesn’t update the Shadowrocket app or download a new rules configuration. Before updating, note the entry currently in use and one verified backup entry, using identifying information that doesn’t include credentials. After the update, check the list for changes, then verify the connection and rules. If important work is underway, don’t change the URL, refresh the subscription, and switch Config all at once before preparing recovery information.

When updating manually, change only one item at a time

In Home, find the target subscription and use its update option. If you have several subscriptions, first confirm that the group label and URL identify the one you intend to update. Wait for the fetch to finish; don’t repeatedly tap or refresh other groups while it’s still loading. If the URL has changed, confirm that the new information corresponds to the original subscription, keep the original record, and test the new URL separately. Don’t mistake a temporary troubleshooting URL for a permanent setting.

After a successful refresh, compare entries that were added, removed, or changed. A new entry isn’t necessarily the right one to switch to immediately; an entry with the same name may have a different port or transport. Check whether the currently selected server is still present after the update, and verify its selection in Home. If the app didn’t keep the previous selection, choose a verified entry manually and make an actual request on the same network. An unchanged total count doesn’t prove the previous connection still works.

Schedule updates around the pace of changes

If you’ve been told about a change or need to test a configuration adjustment, manually refresh the target group and allow time to verify it. If the current interface offers automatic subscription updates, schedule them based on how often things change and when a suitable network is available. Don’t treat automatic updates as a troubleshooting tool. A sleeping device, unavailable network, or unmet background execution conditions may prevent an update from running when expected. If you need to act soon, bring the app to the foreground and check the result rather than relying on the configured interval.

If the server you’re using is also required to fetch the subscription, verify the two paths separately when an update fails: whether the network can reach the subscription URL and whether the existing server still handles regular traffic. Either or both may fail. For example, if regular requests work but fetching the subscription returns an access prompt, check the subscription status and response rather than clearing the server list. If the update succeeds but new entries won’t connect, check their protocol and endpoint fields one by one.

After updating, verify servers and routing separately

First confirm the actual selection in Home, then check Global Routing. If you use Config, verify not only that the individual server works but also that the active configuration sends the expected requests to the right policy. If a rule refers to a named policy or group, check that the reference still works if the update changed that object. Don’t assume an old reference updates automatically just because a new entry has a similar name. Use a consistent test request to avoid differences in the sites themselves.

If an update affects just one group, pause updates to the others and keep a working group as a reference. If switching back to a known-working entry restores requests, focus on changes in the latest list. If the known-working entry also fails, check the device network, DNS, or routing. See the troubleshooting guide for when Shadowrocket is on but there’s no internet access for comparison steps. After resolving the issue, note what recovered and what still needs checking so temporary changes aren’t mistaken for normal settings next time.

Organize multiple subscriptions: Labels, duplicates, and Config references

When you have multiple subscriptions, identify their groups before resolving entries with similar names. A subscription label, a server name within a subscription, and a policy name in Config are three different identifiers. Even if the text happens to be the same, it doesn’t mean they refer to the same object. Before organizing entries, note the currently selected server, its subscription, and the active configuration. If you plan to change groups or remove duplicates, keep records that can be restored first.

Use labels that make the same entry easy to find later

Give each subscription a stable, recognizable local label, and record its purpose separately from server display names. Server names may change on refresh, so don’t rely on them alone for long-term identification or change every original display name to match. For a manually entered diagnostic copy of an entry from a subscription, use an unmistakable test label and remove it when testing is done. That prevents it being mistaken for an entry maintained by the original subscription.

If the interface lets you collapse groups, leave open only the groups you’re using or working on. Collapsing a group doesn’t change whether it’s updated or disconnect it. An inventory can track group labels, entry labels, protocols, use cases, and the last verification result; there’s no need to copy full access URLs or keys. Dates in your notes track maintenance actions; they don’t tell you whether the server has completed a change.

The same name doesn’t mean duplicate, and the same address doesn’t either

Two entries with the same name may use different ports, transports, or authentication. Conversely, entries with different names may point to the same endpoint while being maintained by separate subscriptions. Compare the protocol, address, port, and required transport fields, then confirm which subscription each belongs to. If you can’t safely verify sensitive fields, keep both entries and mark them for review. Even if their current parameters match, separate subscription entries may update at different times when credentials rotate.

If the same subscription was added twice, first check which copy is in use and which has recoverable information in a backup. Switch the active connection to the copy you plan to keep and test it before considering deleting the other. If similar entries only appear because of filtering or sorting, return to a view where their group associations are clear. Don’t use proximity, matching names, or similar latency as a reason to remove duplicates.

Check Config policies; don’t use rules to manage the server list

Subscriptions provide server entries; Config determines which policies handle requests. The following Shadowrocket .conf snippet illustrates rule matching. It contains no server credentials and won’t add, update, or delete entries. Before editing the active configuration, save a copy and make sure you’re modifying an existing rules section rather than adding a duplicate section to the same file.

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

When Global Routing is set to Config, rules are checked in order. Matching requests go to PROXY; if no earlier rule matches and the destination IP meets this GeoIP condition, the request goes to DIRECT. Connections not matched by the preceding rules fall through to FINAL. Here, PROXY is a policy value, not a subscription named PROXY. See the guide to rule keywords for more on matching behavior.

Before cleanup, if Config uses a specific policy group, check how it selects working entries and whether the record you plan to delete is referenced. After making changes, verify both requests expected to go direct and those expected to use a proxy. One page loading doesn’t prove that the other policy works as intended. If only some requests behave unexpectedly, restore the original configuration or relevant references; there’s no need to rebuild the entire subscription right away.

Connectivity Test: Compare latency and verify connections

Latency helps identify entries worth trying right now, but it can’t determine the best long-term choice on its own. Connectivity Test results depend on the current network, test method, target, and server conditions. A successful test means the entry passed that measurement; it doesn’t guarantee every app can reach every destination through it. A timeout simply means that one test didn’t return a result. Set up conditions for a repeatable test before deleting a server.

Keep the network and test conditions consistent

In Home, find the entry or group you want to compare and use Connectivity Test. Start with a small number of known entries, and note whether you’re testing over Wi-Fi or Cellular. If the current settings let you choose a test method or target, keep it unchanged during the comparison. Record the method, network, and server labels; don’t save addresses or authentication details. If you change networks or test targets, start a separate set of results instead of combining the numbers into one ranking.

Test a recently verified entry first, then one that was just imported or updated. If results vary widely, wait for the current test to finish and repeat the round. Check whether the order stays consistent and whether timeouts recur. Avoid large data transfers during batch testing; competing traffic on the device and network can skew results. If only one entry repeatedly fails, focus on it. If all entries, including the reference, fail, check the network and test target first.

Treat sorting, selection, and routing as separate things

If the list supports sorting by latency, use it to bring promising entries to the top, but still check the selected entry in Home. The top entry isn’t necessarily the one actually being used, and manual sorting doesn’t mean a policy group will select a different entry automatically. Newly refreshed entries may not have valid results, and a timeout shouldn’t be treated as an ordinary number to compare with successful measurements. Retest entries without valid results before deciding to set them aside.

Interface labelHow requests are handledWhat to verify
ConfigChoose a policy using the active configuration rulesCheck the matched rule and the server actually selected
ProxyHandle connections using a proxyConfirm the selected server can handle the target request
DirectHandle connections directlyCheck direct access on the current network

Verify with a real request, not just a test result

After choosing a candidate, check Global Routing and then visit a destination you normally use and are allowed to test. If you use Config, confirm the request actually matches the policy you’re checking. Otherwise, a page may load directly, which doesn’t prove the new server works. If you temporarily change modes for troubleshooting, restore the original setting afterward. In particular, don’t leave a temporary Proxy setting in place instead of your usual Config. Compare the same request each time rather than using different destinations to judge server performance.

If a test succeeds but the actual request fails, first check whether the test and request used different paths. If they didn’t, check the destination’s DNS, the handshake, and any Config rules affecting the request. If the only issue is speed, determine whether it’s intermittent latency, an unstable transport, or a slow response from the destination. Keeping a known-working entry on the same network as a reference makes it easier to identify what changed than repeatedly switching the selection.

Delete and back up: Verify recovery before removing entries

Before deleting anything, identify whether it’s an individual server, an entire subscription, or a Config file. Each has a different impact. An individual server is one connection entry; removing a subscription may also remove the entries it manages; removing Config affects rules and policies. If you’re deleting the item currently in use, note the current selection, switch to an item you plan to keep, and verify that it works before deleting. If you’re unsure what will be affected, keep the item or switch temporarily rather than clearing multiple items.

Prepare backups for each type of information

A subscription backup should let you add the original subscription again; a screenshot or list of current server names isn’t enough. Keep the parameters needed to re-enter manually added servers and individual share links. Save rules in a Config file or a copy that can be imported again. Your backup inventory can also note the selected entry, its subscription label, and the Global Routing mode; these settings may not transfer with the file. Don’t assume one export includes every server, subscription URL, policy selection, and system permission.

If the current interface offers export or sync, check that the export scope matches the available restore process. Some files restore rules but not the Home server list; exported data may contain credentials and shouldn’t be sent as an ordinary document. Store backups somewhere you control, and keep the non-sensitive inventory separate from the backup itself. Use filenames that distinguish purpose and order; don’t put a full subscription URL, account name, or server key in a filename.

Before deleting, check ownership and dependencies for each item

In Home, identify the subscription group containing the target before deleting it. If it’s an entry within a subscription, it may return on the next update if the remote list still includes it. If you only want to stop using it temporarily, select a different entry instead of repeatedly deleting it. Before removing an entire subscription, confirm that you no longer need it and don’t plan to keep receiving its updates. Before removing a configuration file, check the current mode and replacement, and keep a copy that can restore normal routing.

After each deletion, return to the list and check the result. Test the connection if needed instead of confirming multiple deletions at once. If the current selection points to a deleted entry, switch to a known-working one first, then confirm Global Routing and Config are still set as expected. If you deleted a subscription by mistake, add it again from your backup information and fetch it. If you deleted a manually entered entry, recreate it from the saved parameters. Deleting a local entry doesn’t revoke server credentials or invalidate links already sent elsewhere.

Restore on a new device and verify each group of items

When moving to a new device, get Shadowrocket on it first, then check subscriptions, standalone servers, and Config in turn. Restore one subscription and fetch it, then select a known-working entry and test it. Next, restore standalone entries and the configuration in use, then check Global Routing and On Demand. Device-level connection permissions or on-demand triggers may need to be confirmed again on the new device. Restoring an app purchase and restoring server information are separate tasks; restoring the purchase doesn’t guarantee the server data migrated. For store and device migration issues, see the guide to restoring purchases.

If duplicate groups appear on the new device, first check whether one was synced and another added manually. Once you’ve confirmed that one copy can be updated and the active configuration works, remove the extra entries. Test an actual request at least once on a normal network. If you regularly switch between two types of networks, also check the relevant trigger behavior on each. Deal with data on the old device only after verifying the servers, configuration, and current setup. For other questions about getting, connecting, and using the app, see FAQ.

Back to contents