Shadowrocket Complete User Guide

01 / APP STORE

App Store Purchase and Authenticity Checks

Verify the app before you buy

Shadowrocket is a paid client available exclusively on Apple platforms, and the App Store is the only place to get it. Before you begin, visit our App Store authenticity check to verify the app name, developer, and app ID, then open the store listing to make your purchase. Don’t rely on search result names alone to identify the app. Similar names or icons are no substitute for checking the product page. The listing’s description, compatibility details, price, and purchase confirmation show the current terms.

Check all three details to verify the app: the developer is Shadow Launch Technology Limited, the app ID is 932747118, and the icon matches the official icon used on this site. You can identify the app ID at the end of the product page URL as id932747118. Check the developer name on the App Store product page itself, not in a search snippet or another page’s description. Then confirm which account is signed in for purchases and check the amount shown at checkout. This keeps app identification and account verification as separate steps.

What a one-time purchase includes

A one-time client purchase is not a service plan. Buying Shadowrocket gives you the right to use the client; connecting still requires your own subscription or server details. This manual explains how to import, configure, and troubleshoot them. It does not provide or sell servers or subscriptions. The client reads settings, establishes connections, and applies routing rules. Server availability, access authorization, and connection capacity are separate matters and cannot be inferred from having purchased the app.

The US store price is about $2.99 as a one-time purchase. The actual amount, currency, and purchase terms depend on the App Store listing. Prices and availability can vary by storefront, so check the checkout screen for your account before paying. Don’t confuse a subscription link’s validity period with the client purchase: the former describes access authorization for a remote service, while the latter is tied to the app purchase record. Keep records of each separately and troubleshoot them as separate issues.

Check device compatibility and storefront

This manual focuses on iPhone and iPad. To check compatibility with Mac, Apple TV, or Apple Vision, see the compatibility section on the same App Store product page. System requirements and purchase eligibility are as listed on the App Store page. The same Apple ID does not guarantee that every device and system combination is eligible. Before switching devices, check that the listing shows compatibility on the target device, then confirm the purchase record belongs to the account currently used for App Store purchases.

If you can’t find the app, first distinguish between no search results and a product page that says the app isn’t available in your current storefront. Check the account’s storefront, reopen the correct product page, and note the exact message. Repeatedly changing network settings usually won’t resolve a storefront availability issue. Your account’s storefront and your device’s language are separate settings; changing the interface language doesn’t change the store where you can make purchases. See App Store storefront and availability for details.

After installation

After installation, first make sure the app opens normally, then configure permissions and connections. Completing a purchase does not import a subscription or establish a system connection; those are separate steps. App updates are managed through the App Store, where you can also view update details. There’s no need to change a lot of settings on first launch. Keep the initial setup simple and verify store acquisition, app launch, server import, and connection separately. If something goes wrong, this makes it easier to identify the affected layer.

02 / PERMISSIONS

First Launch and System Connection Permissions

Distinguish app controls from system authorization

After first launch, check whether Home already shows any server entries. An empty list is normal when no details have been imported; it does not mean the app is malfunctioning. Shadowrocket uses the system’s VPN configuration capability to establish a system-level connection. When you first try to connect, the system may ask to add a VPN configuration. This approval lets the app create a network tunnel on the device; it is not a remote server login and does not provide a working server or subscription.

When the system confirmation appears, make sure it refers to the Shadowrocket app you’re using, then follow the device prompts to approve or authenticate. Your device passcode, biometric authentication, and server password have different purposes; don’t enter one in place of another. If you previously denied permission, try connecting again and check whether the system prompts you again. To review an existing configuration, look for VPN-related items in system Settings. The exact path varies by system version, so follow what appears on your device.

When permissions fail, identify where the failure occurs

If the app’s connection switch immediately turns off, check for an incomplete system confirmation, device management restrictions, or another VPN connection in progress. Don’t assume the subscription has expired: the app may not have reached the remote server yet. Network permissions on managed devices may be controlled by an administrator. If you encounter a restriction, check the device policy first. Avoid repeatedly tapping the switch. Cancel the current connection attempt, wait for the system state to settle, and note the exact message.

If a system configuration already exists but the app still reports a permission issue, disconnect first. Check that the corresponding system configuration belongs to Shadowrocket and that you haven’t selected a different one by mistake. Before changing or removing a system configuration, save your server and configuration details and make sure you understand that you may need to authorize again. Deleting the app is not the first step in permission troubleshooting: local app data and system configurations have different lifecycles, and reinstalling prematurely can turn a simple permission issue into a data recovery problem.

Grant other permissions only when needed

When you use Scan QR Code, the system may request camera access. You only need to grant it if you’re importing by scanning a code. If you previously denied camera access, check the app’s permissions in system Settings rather than scanning repeatedly. Scanning an image from Photos and using the camera may trigger different permission prompts; grant access as needed for the action you’re performing. QR codes often contain complete connection details, so verify their source and don’t share the raw code publicly while troubleshooting.

When you paste a subscription link, the system may show a clipboard notice. Make sure the clipboard contains the content you intend to import, not chat text, line breaks, or extra punctuation. To read a local or cloud file, locate it in the system file picker, then check the import result. Permission only allows access to a resource; it does not verify that the file is correct. After granting access, check that the number and names of the server entries and their key settings match your expectations.

Establish a clear baseline on first use

For your first setup, use a stable local network and avoid enabling complex On Demand conditions or changing multiple DNS settings at once. Add one clearly identifiable server entry, select a Global Routing mode, and then try connecting. This lets you troubleshoot “can’t import,” “can’t establish a system connection,” and “requests fail after connecting” as separate issues. If the device already has network filters or other VPN configurations, note their current state and keep only the conditions needed for the test.

After authorization, don’t focus on whether a particular icon appears. Check whether the app’s connection state, system VPN state, and actual request results agree. Status indicators vary between devices, so the absence of a persistent status bar icon isn’t proof of failure. Note the network type, selected server, and authorization result. You can return to this baseline after importing more details and determine whether a change came from new data or a system-level setting.

03 / SERVER & SUBSCRIBE

Add Servers and Import Existing Subscriptions

Identify the type of details you have

Before importing, identify whether your existing details are for a single server, a share link, a QR code, or a subscription link that returns multiple server entries. These formats aren’t interchangeable just because they look similar: a server address identifies a connection destination, a subscription URL retrieves a set of entries, and a configuration file may also contain rules and other settings. Entering a subscription URL in the server address field won’t work as intended, even if the URL is complete. If you’re not sure what the details are for, check the original instructions instead of trying every field.

To add a server manually with Add Server, choose the protocol that matches your details, then fill in the corresponding fields. The address should usually contain only the hostname or IP address; enter the port in its own field. Don’t append a webpage path to the address. Check passwords, UUIDs, encryption methods, and other options one by one, paying attention to capitalization, spaces, and punctuation from your keyboard. Give each entry a name that makes its purpose clear. Duplicate names can lead to selecting the wrong entry, and a name can’t fix incorrect connection settings.

Check the required settings for each protocol

The protocol determines how each field is interpreted. The same port number or password is not necessarily interchangeable across protocols. Shadowsocks requires the matching encryption method and password. For VMess and VLESS, check identity fields and transport settings together. Trojan passwords are tied to TLS settings. Enter HTTP and SOCKS5 authentication details according to the information you have; don’t assume they use the same fields as another protocol. For WireGuard, Hysteria2, and other types, use the complete original settings rather than guessing defaults from the protocol name.

Import a Subscribe link and check the result

To import an existing subscription, select Subscribe on the add screen, enter the complete subscription URL, save it, and update it. Check that the expected server entries appear. Query parameters in a subscription URL are often part of its access credentials; don’t delete, reorder, or replace them. When copying, check that the final characters haven’t been dropped and that a chat app hasn’t truncated the URL or added explanatory text at either end. After importing, select one entry to test. Seeing the list does not mean every entry has been verified.

If a subscription update fails, distinguish between an inaccessible URL, an unrecognized response, and expired remote authorization. Keep the error message, check the full URL, and see whether the subscription can be retrieved on your current network. Sometimes existing servers remain usable even when a subscription update fails temporarily; updating the subscription and connecting with existing entries are separate processes. Don’t delete the whole group right away. Keep any working entries, then check the subscription retrieval conditions so you don’t lose both a usable connection and useful troubleshooting evidence.

QR code imports, updates, and data protection

After importing with Scan QR Code, check the protocol, address, port, and authentication fields. A successful scan only means the text was read; it doesn’t confirm that the text is complete or still valid. Subscription updates may change entry names, counts, or order, so don’t rely on list position to remember a frequently used server. Before editing an entry manually, check whether the next subscription update will overwrite your changes. If needed, save a clearly named separate copy so you don’t mistake a temporary edit for a permanent change to the subscription.

Subscription URLs, share links, and QR codes may contain access credentials and should be treated accordingly. When troubleshooting, you can describe the protocol, error type, and stage without sharing a full password, UUID, or subscription query parameters. At minimum, make sure the imported entries have a clear source, their key settings match the original details, and you’ve selected at least one entry. Then configure Global Routing. For a walkthrough of the full process, see the Subscribe import section in the quick-start guide.

04 / GLOBAL ROUTING

The Three Global Routing Modes and Rule Order

Choose a mode first, then check which rule matches

Global Routing determines how requests are handled. Its three modes are Config, Proxy, and Direct. Config selects a policy according to the active configuration’s rules; Proxy sends requests in its scope to the currently selected server; Direct connects without using a proxy. These are request-handling modes, not three groups of servers, and they don’t change the remote account. When troubleshooting, note the current mode first. The same rule can appear not to work in different modes.

When using Config day to day, confirm which configuration is active, not just whether a file appears in the Config list. Saving, editing, and enabling a file are separate actions. After changing rules, save and apply them as the app requires, then send a new test request; existing connections may still use their previous state. Proxy can help isolate some rule issues, but switch back to your normal mode when testing is done so a temporary troubleshooting setting isn’t left in place.

Rules are evaluated in order; the final rule is the fallback

Rules are evaluated in the order shown in the configuration. Put more specific targets before broader rules. DOMAIN matches a full domain, DOMAIN-SUFFIX matches a domain suffix and its subdomains, and DOMAIN-KEYWORD checks for a keyword in the domain. IP-CIDR and IP-CIDR6 match address ranges, while GEOIP uses IP geolocation data. The rule type determines what is matched; the policy determines how a match is handled. Don’t confuse a policy name with a matching condition.

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

The snippet above illustrates rule order; it is not a complete configuration for every network. For a request to api.example.com, the first rule matches, so the suffix rule below it doesn’t determine how that request is handled. Other destinations under example.com may match the second rule. FINAL is the fallback policy for requests that match no earlier rule and belongs at the end. The example domain is for demonstration only. Before copying the rule, identify the actual targets you want to handle; don’t treat the example as a verified rule for a real service.

Understand policies, resolution, and rule scope

PROXY, DIRECT, and REJECT are common policies. Rules may also refer to policy groups defined in the configuration. Referenced names must match an existing definition; writing a nonexistent name won’t create a policy group. To reject a target, first narrow the match and check whether the target also serves login, verification, or other resources. This helps avoid disrupting normal functions with a broad rule. When troubleshooting, start with a specific domain instead of expanding the match to a keyword or an entire address range.

Domain rules and address rules rely on different information. Requests that include a domain can be evaluated by domain; requests that provide only an address may be evaluated by address-related rules. Some rules may also involve additional resolution. DNS responses, caching, and request type can all affect what you observe, so you can’t infer the matching rule from the destination name alone. Conditions such as USER-AGENT also have limitations; don’t assume every encrypted request exposes the same application-layer fields.

The more complex the configuration, the more important it is to keep a basic file you can restore. Add one set of rules at a time, record the intended target and resulting policy, then decide whether to continue. If something goes wrong, check that the file is active, rule order is correct, and policy names are valid before making broader changes. Understanding why a request matched a rule is more useful for maintenance than accumulating a large number of rules.

05 / CONNECT & VERIFY

Establishing and Verifying a Connection

Set up a repeatable test

Before connecting, keep three conditions constant: the selected server, the Global Routing mode, and your local network. Confirm the server comes from your own valid details, select a specific mode, then turn on the connection and complete any pending system authorization. Don’t switch servers, update subscriptions, and change DNS during the same test; even if requests start working, you won’t know which step made the difference. Start with a small number of repeatable requests to establish a baseline for comparison.

A complete check covers at least three things: whether the system connection is established, whether the target request completes, and whether the actual handling policy matches your expectations. A connected status only indicates that the local tunnel is active; it doesn’t prove the remote server can authenticate or reach the target. A webpage opening also doesn’t prove that it used the selected server. Under Config, it may match DIRECT. Record both whether the target is reachable and which policy handled it, rather than noting only success or failure.

How to use Connectivity Test results

Connectivity Test can help compare basic reachability between entries, but first check which test method is selected. Methods may check only connection establishment, a response from a specific target, or part of a protocol handshake. Don’t treat the result as a direct measure of everyday download speed. A timeout may be caused by the test target, a temporary network change, or the way the server handles that test. Repeat a small number of tests under the same network and conditions, then compare the results with real requests.

Low latency doesn’t guarantee high throughput, and a successful connection doesn’t mean every request will work. If a basic test succeeds but a particular page fails, check its target domain, rules, DNS, and related resources instead of immediately ruling out the whole server. Conversely, if multiple independent targets fail and requests also fail in Proxy mode, prioritize checking the address, port, authentication, and remote server status. Testing tools provide clues; they don’t replace identifying where the request failed.

Choose the next check based on the symptom

If you can’t access the internet, first disconnect and check whether the local network itself can handle normal requests, then reconnect to the same server and compare. If the local network requires web-based authentication, complete it first. When comparing Proxy and Config, change only the mode: if Proxy works but Config doesn’t, check the rules, policy references, and whether the configuration is active. If both fail, check the server and connection conditions. This comparison won’t cover every cause, but it can significantly narrow the search.

Distinguish slow speeds from connection failures

Analyze speed only after the connection is working. Keep the test content and time of day constant, then distinguish between the remote server, local network, transport settings, and limitations of the target service. Large file transfers and short webpage requests measure different things; the response time of a small request doesn’t predict sustained transfer performance. For a fair comparison, avoid other devices or apps using the network at the same time, and don’t keep changing protocol options during the test.

After testing, note the server, mode, configuration name, and network type. Restore your usual settings and send another request. For more troubleshooting, see step-by-step checks for a connection with no internet access. If speeds remain low, see how to isolate server, route, protocol, and local network issues. Record the symptoms and test conditions without including full access credentials.

06 / DATA

Understanding Data Usage and Request Logs

Check the measurement scope and time period first

Data shows traffic and connection details reported by the app. Before interpreting the numbers, check whether the current view covers the active connection, a specific time period, or cumulative usage, and whether a reset was performed. You can’t directly compare figures based on different measurement scopes. Changes after reconnecting don’t necessarily mean all historical records were cleared. Available sections depend on what the app displays; don’t assume your device has the same usage view or retention behavior as a screenshot from another device.

Upload and download describe the direction of data transfer, not simply uploading and downloading files. Opening a webpage sends requests, and sending a file also receives acknowledgments and responses. Protocol overhead, retransmissions, keep-alive traffic, and name resolution can all contribute to usage, so the app’s figures may not match a file’s size. To estimate the change caused by an activity, note usage before and after while other activity is minimal. Treat the result as an estimate, not an exact record for remote billing.

Client statistics aren’t a substitute for remote account records

Shadowrocket reports activity visible to the client, while a remote subscription may measure usage differently. The figures are even less comparable if the device has other direct connections, multiple devices share a remote account, or the measurement periods differ. Remaining subscription data may come from information returned by the remote service, and its update frequency may differ from the client’s live counter. If the figures don’t match, compare the time period and device scope first, then investigate whether the data is actually unexpected.

To check whether an app used the expected policy, look at the request target and rule match rather than just the total traffic increase. A change in the total only shows that network activity occurred; it doesn’t identify which foreground action caused it. Background sync, page preloading, and other apps refreshing may happen at the same time. To reduce interference, pause unnecessary activity, perform one short, clearly defined action, note the time, then check nearby requests and their policies.

Use request details to investigate rules and resolution

If the current view provides connection or request details, check the destination domain or address, policy, associated server, and failure stage. A domain and an address are different kinds of evidence: the domain helps you check domain rules, while the address helps you check address ranges and resolution results. A page often requests several destinations; a successful main document doesn’t mean images, login checks, and other resources followed the same route. If part of a page is missing, look for the specific failed resource instead of adding only the page’s main domain.

After changing a rule, send a new request before checking the result. Existing browser connections, app caches, and DNS caches may preserve the previous state and make a new rule appear ineffective. End the current test and, if needed, close and restart the request before checking its new record. Save useful error stages and timestamps before clearing records. If you clear everything and the issue temporarily disappears on retry, you may lose the only clue that explains the problem.

Investigate rising usage and background activity

If background traffic keeps increasing, check how long the connection has been active, which sync tasks are running on the device, and whether On Demand conditions apply. A persistent connection may include maintenance traffic, but an increase in the total alone doesn’t show that a setting is wrong. Shorten the observation period to a time you can reproduce, then compare the change with screen use, background sync, and network switching. Don’t explain battery use by traffic figures alone: connection wakeups, wireless conditions, and device tasks also matter. Track them separately.

When describing an issue to someone else, share a concise timeline, destination type, policy, and error text. Request records may reveal browsing habits, full URLs, query parameters, or authentication details; remove anything unnecessary before sharing. Don’t send all logs and subscriptions for convenience. After troubleshooting, return any detailed logging settings to the level you normally need. This makes future records easier to read and avoids accumulating unnecessary information.

07 / SETTINGS

Settings, DNS, and On Demand

Identify which layer each setting affects

Settings don’t all apply at the same scope. Some control app behavior, some affect the current connection, and others are defined by a Config file or a specific server entry. Before making a change, identify what the setting applies to and note its original value. If a configuration already contains a related setting, don’t assume another control in the interface overrides it. Check the description for the current option, then verify its effect with a real request. Keeping a working baseline is more important than enabling lots of options that seem useful.

Handle settings in three groups: first, what’s needed to connect; next, On Demand and name resolution; finally, advanced options for specific networks. Change one related group at a time and test the same target after saving. If the result gets worse, restore the group’s original values rather than adding more changes to compensate. For switches whose purpose you don’t understand, keeping your current working settings is usually easier to maintain than guessing.

DNS affects name resolution; it doesn’t replace connection authentication

DNS resolves domain names to the addresses needed for requests. A failed lookup, an unexpected address, or an unreachable resolver can make a webpage unavailable, but these issues occur at a different stage from an incorrect server password. First determine whether the failure happened before or after resolution, then decide which layer to change. Connecting to an IP address doesn’t prove that all requests to the service’s domains will work. Many services depend on hostnames, certificates, and multiple resource domains, so testing by IP alone isn’t a substitute for a complete request.

When choosing or changing DNS, consider whether the resolver is reachable under the current connection conditions and how DNS requests are routed. Don’t replace an address without checking its path, and don’t keep adding addresses from unknown sources. Record the domain, result, and time while keeping other conditions unchanged. Encrypted DNS doesn’t mean every request uses the same route. Verify DNS routing and application request policies separately; one setting can’t tell you whether the whole connection path is working.

On Demand starts connections based on conditions

On Demand uses configured conditions to decide when to start or maintain a connection; it doesn’t repair a remote server. Before setting it up, define the behavior you want: whether to connect when joining a network, stay connected after leaving it, or use the local network directly in certain situations. Available conditions depend on the app’s current interface. Check their order and matching scope one by one. Similar network names don’t necessarily mean the same conditions. Save the settings and verify them during an actual network switch.

If the connection turns back on after you switch it off, check whether On Demand is still active before assuming the manual switch is broken. An On Demand rule may trigger a new connection when a network request starts or the network changes. During troubleshooting, you can temporarily disable the relevant conditions, verify a manual connection, then restore them one by one. On networks that require web-based authentication, complete the local sign-in first and then check whether the On Demand conditions are appropriate. This avoids connection timing interfering with initial access.

Connection trade-offs and advanced options

On-demand and persistent connections involve different trade-offs in usability, background activity, and recovery after network changes. There’s no single setting that works best for every device. Frequently entering or leaving trigger conditions may also cause additional connection attempts. To assess battery use, compare similar usage periods under similar network conditions rather than relying on a single system report. For a more detailed comparison, see On Demand settings and background battery use, then choose what fits your actual usage.

Before changing IPv6, UDP, connection timeout, or other network settings, confirm that the option is relevant to the symptom. One failed request isn’t enough to justify globally disabling a feature; the broader the change, the more likely it is to affect requests that were working. Test a narrow change first and save the results from before and after. Once you’re done, test a reconnection and a network switch to make sure the fix isn’t limited to an existing connection that hasn’t ended yet.

08 / MAINTENANCE

Maintenance, Device Transfers, and Troubleshooting Notes

Maintain the app, subscriptions, and configurations separately

Handle app updates, subscription updates, and Config file changes as separate maintenance tasks. App updates come from the App Store; subscription updates retrieve server entries from your own URL; configuration changes affect rules and related behavior. These changes may affect one another, but they aren’t the same operation. To make troubleshooting easier, avoid doing all three before the same test. First confirm the connection works and note its state, then make changes one at a time and run a brief check after each.

After a subscription update, check the number of entries, whether your frequently used servers are still there, and whether the selected entry changed. A matching name doesn’t guarantee that the settings are unchanged, and a different list order doesn’t necessarily mean an entry is missing. If an entry is managed by a subscription, manual edits may be overwritten by the next update. Keep temporary tests separate from your everyday entries. Periodically remove duplicates and entries you’ve confirmed are no longer needed, but avoid deleting data in bulk before you’ve identified a problem.

Keep configurations and data recoverable

Before editing a Config file, save a working copy and give it a useful name. There’s no need to add a string of hard-to-distinguish “final” labels. A backup should include the rule text and identify which settings come from server entries and which are provided by subscription updates. Store passwords, UUIDs, and complete subscription URLs securely; don’t put them in public notes. Before restoring, check what the backup applies to. Don’t copy every setting from one device to another without checking first.

Before switching devices, check separately that you can access the App Store purchase account, existing server details, and configuration files. Restoring an App Store purchase and restoring in-app data are different tasks: the former lets you get the client again; the latter determines whether you can recover your previous connection settings. In the App Store, use the account that made the purchase to find Shadowrocket in your purchased items. System requirements and purchase eligibility are as listed on the App Store page. See how to restore a previous purchase for details.

Before reinstalling, create a minimal troubleshooting record

If something goes wrong, note when it happened, the device’s network type, Global Routing mode, configuration name, server protocol, and failure stage. Specify whether a subscription couldn’t update, the system connection couldn’t be established, or a target failed after connecting. Narrow the issue down to a repeatable action and compare results instead of resetting everything and hoping for the best. Refer to servers by a custom label in your notes to avoid exposing real addresses or authentication details.

Reinstalling isn’t usually the first step. Removing the app may make local data, records, and saved troubleshooting clues unavailable, while remote authentication errors, network conditions, or rule logic may remain unchanged. First try restoring the last working configuration, disabling recently added conditions, and following the connection checks in order. If you do need to reinstall, make sure you can retrieve all the necessary details before proceeding. The fact that the app is still available in the store doesn’t mean your in-app configuration has been backed up.

Follow a repeatable maintenance routine

Use the same sequence for each maintenance task: confirm the baseline, save your data, make one change, test representative targets, check the actual policy, and record the result. Choose targets that cover the kinds of access you actually need instead of opening many unrelated pages. Briefly record successful results, too; if something goes wrong later, you’ll need to know which conditions last worked. If you switch to Proxy temporarily for testing, restore your usual mode afterward and confirm that On Demand conditions still match your plan.

Before sharing troubleshooting details, check screenshots, logs, and copied text for sensitive information, especially subscription query parameters, authentication fields, and request history. Others usually need the failure stage and steps to reproduce it, not full account details. If you can’t find a purchase after switching or reinstalling a device, see how to restore a purchase on a new device or after reinstalling. To set up the app again, return to the quick-start guide, establish a working connection using the main steps, then restore your preferences one at a time.