Shadowrocket · Official Manual

Shadowrocket User Manual

For your first setup, follow the quick start guide to import your details, connect, and verify access. This manual is a reference for the full workflow: it explains not only what to do, but how to confirm each step worked and where to resume if something goes wrong. Instructions use the iPhone and iPad interface; the installation chapter also covers other platforms.

Getting the App and Installing

iPhone and iPad: Get Shadowrocket from the App Store

Shadowrocket is a closed-source commercial app. The iPhone and iPad version costs $2.99 as a one-time App Store purchase; versions for Mac (Apple silicon and Intel), Windows, Android, and Linux are free. Prices outside the US App Store vary by storefront. Check the App Store listing for current iPhone and iPad system requirements. Follow the App Store link on the download page to open the product listing, then verify the developer, Shadow Launch Technology Limited, the official app icon, and the app ID 932747118 in the product URL. Matching app names alone are not enough to verify a listing.

If you’ve already purchased Shadowrocket on one device, you can look for it under your App Store account’s purchased items on another device and install it from the product page. If you still see a purchase prompt, check which account is signed in to the App Store, your purchase history, and whether the app is available in that storefront. You can redownload the app through your account, but that does not restore server details, subscriptions, or local settings from an old device. Save those separately before switching devices.

A one-time app purchase is not a service plan. Installing Shadowrocket does not include a server you can connect to. This site does not provide, sell, or recommend servers or subscriptions. Before setup, have your own server details or subscription link ready.

Mac and Windows: Check Your Architecture and Download Source

Get desktop and Android installers from the downloads for all platforms page. Download URLs should be under /dl/shadowrocket/ on this site. On Mac, check About This Mac: choose the Apple silicon build for an Apple chip, or the Intel build for an Intel processor. Open the installer, copy the app to Applications, and launch it from there; opening it directly from a disk image does not complete installation. If macOS says the developer cannot be verified, first confirm you opened the file downloaded from this site, then check Privacy & Security in System Settings for an Open Anyway option. If macOS says the file is damaged, download the build for your architecture again. Do not assume every damage warning can be bypassed.

On Windows, check System Information for your system type, then download the matching file. If SmartScreen warns about an installer downloaded from this site, verify the download URL and file, then check More info to see whether Run anyway is available. This is a one-time confirmation for that installer; you do not need to disable system protection. Stop if an organization’s policy blocks the app or Windows explicitly reports malicious content. Do not treat an administrator restriction or malware alert as a routine first-run prompt.

Android and Linux: Choose the Right Package

On Android, check that your device supports an architecture listed on the download page, then open the installer. If Android asks you to allow your browser or file manager to install unknown apps, grant permission only to the app you are using to open this file. You can revoke it after installation. If installation still fails, check that the download completed, the architecture matches your device, and you have enough storage; then check whether Android reports a conflict with an existing app. Removing an existing app may also delete its local settings, so do not make uninstalling your first step.

On Linux, choose a package format that matches your distribution and package manager: install a local deb or rpm package with the corresponding package manager. For an AppImage, grant execute permission in the file properties, then launch it. Missing dependencies, an incorrect path, and missing execute permission are different issues. If the package manager reports missing dependencies or an architecture mismatch, check the system and package against the error instead of repeatedly launching with elevated permissions. See the installation instructions for platform-specific download and security prompts. By the end of this chapter, the app should open; a connection is not required yet.

First Launch and Permissions

Check the App and Your Network Connection First

When you first open Shadowrocket, look at Home to find the connection switch, Global Routing, and server list, then open Config to see which configurations are available. An empty server list or a connection switch that is still off does not mean installation failed. First, return to the system and make sure your device is connected to working Wi-Fi or Cellular. With Shadowrocket disconnected, try opening a regular website you can normally access. If public Wi-Fi requires a web sign-in, complete it first; otherwise, subscription downloads and connection tests may both fail later.

If another VPN configuration is already on your device, check whether it is connected, managed by work or school, or likely to affect access if disabled. Do not delete an existing configuration or management profile just to make a new one work. You can disconnect another connection if you are authorized to do so, then return to Shadowrocket. On a managed device, follow your organization’s instructions. A VPN status indicator does not necessarily mean Shadowrocket is handling traffic; check System Settings to see which connection is active if needed.

Allow Shadowrocket to Add a VPN Configuration on First Connect

When you first try to connect, your iPhone or iPad may display a system prompt asking whether Shadowrocket can add a VPN configuration. Make sure the prompt appeared after you turned on the connection from Home, then authenticate as requested. This permission lets the app establish a system connection to handle network traffic; it does not verify the server address, account, or subscription. After granting permission and returning to Home, check the connection status and test actual access to confirm it worked.

If you previously denied permission, return to Home and try connecting again, then follow the prompt. If no prompt appears and the switch quickly turns off, check whether the corresponding configuration already exists in VPN settings, whether Home shows an error, and whether another VPN is connected. Do not keep tapping the switch to force the prompt to appear, and you do not need to reset all network settings. If a system control is dimmed or settings cannot be changed, distinguish a device-management restriction from a connection failure. Updating a subscription cannot change device permissions.

Distinguish Camera, File Access, and Local Network Permissions

You only need to grant camera access when using Scan QR Code to scan a server QR code you already have. Manually entering server details or pasting a subscription link does not require camera permission. If you prefer not to grant it, enter the connection details you already have instead. When importing a file, choose the configuration you prepared. Even if the filename looks familiar, confirm who provided it and what it is for. A configuration can change server options, DNS, or rules, so files from unknown sources are not a sound troubleshooting tool.

If a test involves devices on the same local network and public internet access works, first check that the target device is online, both devices are on the same network, and guest Wi-Fi is not isolating them. Then check whether the feature you are using has requested local network permission from the system. A local network failure is not the same as a proxy server sign-in failure. Similarly, if Cellular data is disabled for the app, a subscription that cannot update after you leave Wi-Fi is not necessarily expired. Note which network you were using and where the error appeared to avoid changing settings at the wrong level.

Before connecting, check three things: the device has internet access, the app opens, and the system allows the required connection. Check server availability during import and rule behavior during verification.

Importing Servers and Subscriptions

Add a Server Manually

From the add button on Home, open Add Server. Choose the protocol used by your existing server, then enter the details as provided. The form fields vary by protocol; the same address and port do not make authentication methods interchangeable. Enter the hostname or server address in the address field, the port in its own field, and a note to identify the entry. Do not paste an entire link into the address field or include explanatory text, a protocol prefix, or copied spaces in the parameters. If your details include transport or security settings, match them to the server instead of substituting options with similar names.

Check the Details for Your Protocol
ProtocolDetails to Check
ShadowsocksServer address, port, encryption method, and password.
VMess / VLESSServer address, port, UUID, and the transport and security settings specified in your details.
Trojan / Hysteria2Check the address, port, authentication details, and applicable TLS settings for each protocol.
HTTP / SOCKS5Address and port; enter a username and password only if the server requires them.
WireGuardLocal address, key, peer address and port, and Allowed IPs. Do not interchange the public and private keys.

After saving, find the new entry on Home, check its note and protocol, then select it. If entries have the same name, use clear notes to distinguish manually added servers from subscription imports. This helps avoid testing one entry and connecting through another. For certificate or identity verification errors, check the server details and device time, and verify the hostname against the specific error. Do not routinely disable verification as a fix. If an existing connection still works, keep it for comparison rather than overwriting it with test values.

Import and Update an Existing Subscription

A subscription link is an address the app uses to retrieve a set of server entries. If you have your own link, open the add menu on Home, choose Subscribe, and paste the complete link into the address field. Check that no spaces or line breaks were added at either end, and do not omit the part after the question mark that identifies the subscription. The example below only shows the format of a link; it cannot import real servers. Treat your actual link like a credential. Do not paste it into public posts, screenshots, or online checking tools.

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

If saving the link does not show any entries, first use that subscription’s update action to retrieve the list. Then determine whether retrieval failed or the returned content is unsupported. For a download error, check the device’s network, the link, and the subscription status. If content was received but no entries can be recognized, confirm the address is a client subscription link, not an account sign-in page or a regular website. If the list appears but one server cannot connect, troubleshoot that server and the current network separately; the subscription itself may have updated successfully.

Keep Server Lists and Config Files Separate

Server entries contain connection details; Config files define rules and related settings. Adding a subscription does not select routing rules, and importing a rule file does not ensure that its referenced policies can find an available server. Identify what you have before choosing where to import it. If you have both a subscription and a configuration, import the subscription first and confirm its list loads, then handle the configuration separately. This makes it easier to tell whether a failure occurred while retrieving the list or enabling the configuration.

Before switching subscriptions, you can keep the old entries temporarily for comparison, but do not assume entries with the same name are identical across lists. Recheck the selected server, and if your configuration uses policy groups, confirm they still refer to the right entries. Note your current selection and test results before updating, then test again afterward. For a changed address, an empty list, or updates that fail only on certain networks, look up the symptoms in the FAQ.

The Three Global Routing Modes

Choose a Mode, Then Check What Determines the Route

Open Global Routing on Home. Config, Proxy, and Direct determine how the app handles traffic. They are not server names or connection protocols. Choose Config for rule-based routing. To temporarily rule out the effect of your rules, compare with Proxy or Direct. When you are done, switch back to the original mode; otherwise, you may not see the expected results from later edits to Config.

Mode, Route, and What to Test
Interface OptionHow It WorksWhat It Helps You Check
ConfigMatches traffic against rules in the active configuration.Check which rule matched a particular request.
ProxyRoutes traffic handled by the app through the proxy.Temporarily excludes custom routing rules from the test.
DirectRoutes traffic handled by the app directly.Compare direct access while the app remains connected.

Direct does not turn off the connection on Home. If you suspect the device’s basic network connection, turn off the connection and test again. If Proxy reaches a destination but Config does not, check the active configuration and where the request was actually routed. If both modes fail, that alone does not prove the server is at fault; check whether the destination responds over your regular network. To confirm where these labels appear, see the interface terminology guide.

Make a Copy Before Editing Rules in Config

Rules are generally matched in the order they are written. For a given request, the first matching rule applies; matching does not restart to look for a more specific rule. For example, if a domain-suffix rule comes first, it can route a specific host under that suffix before the request reaches a later exact-match rule. To add a small number of exceptions, check for broader rules above them and place the exceptions appropriately. Rule keywords specify match conditions; the final item specifies the policy. Do not treat the mode names on Home as rule conditions.

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

This is an example of rules you can add to a copy of your configuration, not a complete configuration file. It routes the specified host through DIRECT first, then matches other targets under the same suffix. Swap the first two lines and the exact-match exception will no longer work. GEOIP classifies the destination IP; it does not identify a target by its domain suffix. An IP rule can match only if the destination address is available when matching occurs. Requests that do not match an earlier rule fall through to FINAL. This example uses DIRECT as the fallback; changing it to PROXY changes the route for every unmatched request, not just the site being tested.

Trace Why a Specific Request Did Not Match

A webpage may request resources from several hosts, such as the page itself, image sources, and sign-in services. The domain in the address bar does not necessarily represent every request. If only images or sign-in fail, identify the host used by the failing request before deciding whether to add a DOMAIN exception for one host or use DOMAIN-SUFFIX for an entire suffix. DOMAIN-KEYWORD has a wider scope and may match unrelated targets. IP-CIDR and IP-CIDR6 apply to their respective address ranges and should not replace domain rules.

After saving a copy of the rules, confirm that the edited file is active and select Config on Home. Retest with a new request, reloading the target page if needed to avoid old connections or local cache masking the change. If an edit affects unrelated sites, revert to the previous configuration, narrow the rule, and check FINAL. For a complete example focused on a small set of targets, see how to route selected sites and order the rules.

The interface uses Proxy and Direct; policies in configuration files use PROXY and DIRECT. REJECT blocks a request; it is not an alternate route that automatically takes over when a connection fails.

Connect and Verify the Results

Compare Results on the Same Network

Stay on a stable Wi-Fi or Cellular network. With Shadowrocket off, visit a site you can normally access and note how it performs. Then return to Home and check the selected server and Global Routing mode. If you use Config, also confirm which configuration is active. Turn on the connection and wait for its status to settle. Do not change the server and network during the same test. If a system permission prompt appears, grant permission, then check whether the connection stays active. A switch that remains on means the system connection is established; it does not confirm that every request will succeed.

You can run Connectivity Test for the selected server, then visit the website or app you want to verify. A test result measures only its particular test target under the conditions at that time. A successful result does not guarantee access to other targets, and one failure does not mean the server fails for all targets. When retrying, keep the network and options unchanged so you do not mistake a network change for a change in server performance. To compare two servers you already have, use the same network, target, and mode for a more meaningful test.

Choose the Next Step Based on the Scope of the Problem

No websites load: Turn off the connection and test again. If access still fails, check Wi-Fi sign-in, Cellular data permissions, or the device’s basic network connection first. If access returns, check whether the issue also occurs with another server that normally works. If only one server fails, verify its address, authentication, and security settings. If several fail, check what they have in common, such as the current network, configuration, or name-resolution settings. When the error occurs also matters: a connection that drops as soon as it starts is different from a request timing out after the switch stays on.

Only some destinations fail: Keep the same server and compare Config with Proxy. If a site works in Proxy but not Config, check whether a broad rule matched the request earlier than expected or whether it fell through to an unsuitable FINAL policy. If both modes fail and the site also fails with the connection off, consider a problem with the destination service or the underlying network. If it fails only over the proxy route, check whether that route works for the destination rather than expanding proxy routing across the entire configuration.

Host not found or page keeps waiting: Record the exact error. A host lookup failure may involve name resolution; a timeout can occur during connection setup or data transfer, so a long wait alone does not prove a DNS issue. Compare two domains you can normally access to see whether only one target is affected, and check whether you recently changed DNS or related rules. For a certificate error, check the system time and connection settings; do not ignore verification and continue. For a step-by-step workflow, see troubleshooting no internet while connected.

Retest After Switching Networks and Resuming Use

After testing successfully on a stable network, verify the other network you plan to use. Switching between Wi-Fi and Cellular may interrupt downloads, video, or sessions; verify with a new request instead of relying on a page that loaded before the switch. If the problem occurs on only one network, record behavior both with Shadowrocket connected and disconnected. Check whether that network requires sign-in and whether the app is allowed to use Cellular data. If both networks are stable but problems often occur when returning to the app, check automatic connection conditions and whether another VPN configuration is taking over.

A successful verification is more than a switch that stays on: you should be able to explain the result of a representative request. The current network works, the selected server is available, the mode is what you expect, and the target follows the intended route. After a comparison test, restore the Global Routing mode and server you plan to use. To reproduce a problem later, note the network type, mode, rules, and error; you do not need to include sign-in details.

Check Traffic in Data

Check the Statistics Scope Before Comparing Numbers

Data shows network traffic recorded by Shadowrocket. Before reading the figures, check the dimension and time range shown: a specific period, traffic for one server, or a cumulative total. These are not directly comparable. If the page separates sent and received traffic, record them separately; do not compare a receive-only figure with a later total for both directions. Historical traffic may already be present when you connect. Note the baseline, then check the increase over the test period rather than treating the current total as traffic from this connection.

Traffic recorded by the app is not the same as system Cellular data statistics or a service provider’s billing records. The system counts mobile data for the device or app in its own way, and providers may use different billing periods, units, or traffic directions. Similar-looking figures on the app’s page are not necessarily measuring the same traffic. If they differ, align the time period, network type, units, and upload/download scope before comparing. Use system statistics to check mobile data usage, and your existing provider’s records to check account usage. Use Data to identify roughly when the figures changed.

Run a Short Test to Get a Meaningful Traffic Change

Choose a stable network and keep the same server and Global Routing mode. Pause tasks that generate substantial background traffic, such as active syncing or downloads, then note the starting figure shown in Data. Perform one easy-to-repeat action, such as reloading a lightweight page. Once it loads, return to the same statistics view and check the difference. A cached page may generate little traffic; try a new request or consider the connection status and diagnostic information. There is no need to download a large file just to make the numbers change.

If you are testing a new rule, an increase in total traffic does not prove the target went through PROXY. A browser may preload unrelated resources, and background apps may refresh. Proxy traffic can occur during the test without coming from the target. Limit the test to one action, then correlate the time, target, and policy using request or policy diagnostics if available. Without diagnostic details, you can only say that the statistics changed during the test; you cannot conclude that a particular domain rule matched.

Explain Unexpected Spikes or Unchanged Readings

If traffic keeps increasing when you are not actively browsing, check for syncing, app updates, auto-loading media, or long-running transfers on the same device. Compare two similar time periods: pause known tasks for one, then resume them for the other. This makes background traffic easier to identify than repeatedly changing servers. If you notice the increase only after switching from Wi-Fi to Cellular, also check the system’s mobile data statistics, since Data may show more than Cellular traffic alone.

If the reading does not change, refresh the view or wait for the current request to finish. Check whether the page is showing cached data and whether the dimension you are viewing includes that request. If routing uses DIRECT, traffic statistics for a proxy server cannot tell you whether a direct request completed. If you cleared records or changed the statistics scope, establish a new baseline before comparing; the old and new readings may not be comparable. Clearing records does not change rules or reduce provider usage.

Keep Brief Notes for Comparison

For longer-term tracking, note the test period, network type, mode, statistics scope, and approximate increase. Keep short tests separate from all-day background usage, and track Wi-Fi and Cellular separately. This lets you reuse the same test conditions to compare changes after updating a subscription or editing rules. Before sharing a Data screenshot, hide identifying account or server details. Troubleshooting notes usually only need to distinguish a short-term increase from a cumulative total and describe the conditions when the issue occurred.

Common Settings and How to Adjust Them

Find Settings by What They Affect

Settings controls general app behavior, but not every option is there. Check Home for the selected server, connection status, and Global Routing mode. Check Config for rules and DNS settings in a particular configuration. VPN permission, Wi-Fi, and Cellular data access are managed by the system. First identify which layer you need to change, then go to the right place. Otherwise, you may change a general setting while testing with an old configuration, or mistake a system permission issue for an app setting conflict.

Before making a change, keep a working baseline and note the current option and what you plan to verify. Change one setting at a time, then retest on the same network, mode, and server. If the problem disappears, restore the original value first to see whether it returns, then decide whether to keep the change. Changing several options at once may temporarily fix the issue, but it makes it hard to tell which one mattered. The next time a similar problem occurs, you will not know where to start.

On Demand: Verify Manual Connection First

On Demand affects whether the system starts a connection when specified conditions are met. Before enabling it, connect manually on the Wi-Fi or Cellular network you plan to use. Confirm that the server, mode, and target behave as expected, then configure the conditions shown in the interface. Start with one easy-to-repeat scenario, such as joining a known working Wi-Fi network. Switch to that network, make a new request, and check whether the connection starts as expected. Then test a scenario that does not meet the conditions; do not test only the trigger case.

Public Wi-Fi may require web sign-in first. If On Demand interferes with sign-in, temporarily disable automatic triggering, sign in to the network, then restore and test the setting. If the connection turns back on after you switch it off, check On Demand and any existing VPN configurations in the system before assuming the switch is broken. If networks have different requirements, add conditions one at a time and note which network triggers the connection. Automatic actions cannot replace checking server availability; repeated triggers will not fix sign-in or routing problems when no server is available.

Connectivity Test and DNS: Check Testing and Resolution Separately

Connectivity Test helps check a specific test target. If its behavior or results seem wrong, first consider whether you changed a related setting. If the interface lets you set a test address, use one you understand and can normally access. Keep the address the same when comparing results. Changing only the test address and seeing success does not mean other requests are working again. Avoid pages that require sign-in, redirect frequently, or depend on account status as routine test targets.

DNS settings handle name resolution; they are not simply a switch to make connections faster. If symptoms point to name resolution, first check the active Config and any relevant settings on the device, and note the normal behavior. Then adjust one factor in a copy of the configuration. A local network name may resolve only on that network; changing the resolver can make it unavailable even while public domains still work. Retest both the domain that originally failed and one that worked before. Do not rely on a single target that happens to recover.

Keep Only the Diagnostic Details Needed to Find the Issue

If you use logs or other diagnostics, first decide whether you need to distinguish name resolution, rules, connections, or system triggers, then reproduce the issue briefly. Note the order of errors and the general type of target. Avoid leaving debug features on and retaining full logs long-term. Before reporting a problem, remove server addresses, account identifiers, sensitive configuration contents, and subscription details. Browsing history can also reveal personal information. After diagnosing the issue, restore any test-only options to their original values, then verify access to a site you normally use.

Updates, Backups, and Routine Maintenance

Handle the Three Types of Updates Separately

App updates, subscription updates, and configuration updates address different things. An app update replaces the program; a subscription update changes the server list; a configuration update may change rules, policy references, or DNS settings. Check for app updates in the App Store on iPhone and iPad. On Mac, Windows, Android, and Linux, go to the downloads for all platforms page and choose the installer for your platform and architecture. Do not uninstall the app just to update a subscription, or update the app when you only need to refresh the list. If you changed system permissions, check after an update that they still work before deciding whether to grant permission again.

When possible, perform these three types of updates at different times. Save the current working state, update one item, then verify that Home connects and your usual targets follow the expected routes before proceeding. After refreshing a subscription, do more than check whether the list changed: confirm the selected server and the policy groups referenced by your configuration. If one server stops working, compare it with another existing entry in a controlled test. If the entire list is empty, troubleshoot the subscription update first rather than rewriting rules with no entries available.

Back Up Configurations and Record Settings for Recovery

A useful backup is more than a saved filename. Record which configuration is active, the Global Routing mode, the server or policy in use, and any On Demand or DNS settings you changed. Save configurations you may need to restore in a secure location you can access, and keep them separate from experimental copies. If you can export a configuration, confirm the exported file is retrievable. Keep the old file safe; do not overwrite your last working copy with an edited, untested version.

A configuration file may not contain all your data. When switching devices, reinstalling restores only the app itself; check the server list, subscriptions, configurations, and system permissions separately. Restore in the same order as first-time setup: first confirm the new device can access the internet normally, then install the app and grant system permission, and finally import your own details and verify access. If you still have the old device, keep its configuration until the new device is working. Files, links, and QR codes may contain authentication details, so do not place them in public folders or post them in discussion areas.

After an Error, Return to the Last Working State

If a problem started after editing rules, activate the last working Config first and check whether switching configurations resolves it. If it began after a subscription update, check the selected entry and policy groups; do not repeatedly import the same link and create duplicate lists. If it started after enabling automatic connection, disable the relevant conditions and verify a manual connection. This rolls back the latest change without resetting accounts, files, and permissions all at once. If the app has not changed but suddenly stops working, first rule out changes to the current network, destination service, or existing servers.

If rollback does not restore access, make a reproducible note: device type, network, mode, whether all sites are affected, whether turning off Shadowrocket restores access, and whether the app, subscription, or configuration was updated recently. Remove sensitive details before checking the FAQ. If you are unsure which data is backed up, do not clear app data casually; deleting it and reinstalling may remove configuration you could still use for comparison.

Verify Maintenance with the Same Test Requests

Keep two test targets with clear expected routes: one that should use the proxy route and one that should go direct. Know which rules each should match in Config. If you mainly use Proxy or Direct, keep a comparison target to verify actual access. After maintenance, make new requests rather than reusing old sessions, then check whether connection and traffic behavior match your expectations. Finally, restore your usual mode and automatic connection conditions. Consistent test conditions are more useful than repeatedly changing settings: they let you start with the specific change the next time something goes wrong instead of reinstalling from scratch.