Shadowrocket
Complete User Guide

02 / First Launch

First Launch and System Permissions

Identify what each control does before connecting

When you first open Shadowrocket, check whether Home already contains a server entry, then review Global Routing and Config. A server entry determines where to connect, Global Routing determines how traffic is handled, and Config provides the rules used in configuration mode. The main switch only starts or stops a connection; it does not supply missing information. If the list is empty, no entry is selected, or an import failed, return to the add flow first. Toggling the main switch repeatedly will not make missing connection details appear.

Before testing, you can temporarily stop other connections that are managing system network traffic to reduce configuration conflicts. The goal is not to delete existing settings, but to create a clear test environment: know which configuration is active, when the connection starts, and whether the network returns to normal after it stops. If your device is managed by a school or organization, system restrictions may prevent adding or changing network configurations; follow the device management requirements. Do not remove organization-managed settings without understanding their purpose, or mistake a management restriction for incorrect server details.

Understand the system prompt to add a VPN configuration

When you first try to connect, the system may ask permission for Shadowrocket to add a VPN configuration and request your device passcode or other system authentication. This configuration lets the app handle traffic through networking mechanisms provided by Apple; it is part of the connection process. It does not grant access to a service or confirm that a server has been verified. Grant permission only after confirming that the prompt follows an action you just initiated and that the app identity is correct. Once authorized, you still need to test whether the server is reachable.

If you previously tapped Cancel, return to the app, verify that the current entry is complete, and try connecting again to trigger the required authorization flow. If necessary, check VPN-related items in system Settings; names and paths can vary by OS version, so follow the interface on your device. Check whether the configuration exists, whether it is allowed to connect, and whether another connection is active. Do not delete all network settings just to make the prompt reappear. That expands the scope of changes and makes it harder to identify the original failure.

A VPN status shown by the system only means the network configuration is active. It does not confirm successful server authentication or guarantee that a website is using the expected route. A configuration can be running while the selected server is unreachable; the server can also be working while the current rules route a destination through DIRECT. Record system status, client test results, and actual access results separately. That makes it easier to identify whether a later “connected but cannot access” issue is related to authorization, transport, or routing.

Grant permissions for the task at hand

When you use Scan QR Code, the app needs camera access to read a configuration QR code that you already have. If you do not want to use the camera, choose another import method suited to your source. If you previously denied access, check the camera permission in system Settings. When importing a link by copying and pasting, the system may also ask for paste access; confirm that the clipboard contains the content you intend to import. Camera permission and connection authorization are separate: camera access affects QR code input and says nothing directly about server connectivity.

QR codes, clipboard contents, and configuration text may contain authentication details. Before scanning, verify the source and purpose. After importing, check the entry type, address, and port; successful reading does not prove the parameters are correct. If the QR code comes from another device you own, check whether it represents a single server, a subscription URL, or an entire configuration. Each requires a different maintenance approach. Choosing the wrong import flow may leave content unrecognized or in an unexpected location; it does not mean all the information is invalid.

A good endpoint for initial setup is not “all permissions are enabled.” Grant only the permissions required for the task at hand, and understand why each one is needed. After system network authorization, keep one clearly identified server entry for testing; connect manually once, then disconnect. Leave automatic connection conditions off for now so you can observe changes. Once you can repeat the manual process reliably, configure On Demand in the Settings chapter. This prevents automatic triggers from obscuring problems with manual connections.

03 / Add Connection Details

Adding Servers and Existing Subscriptions

Add Server: Check Each Connection Parameter

Before adding anything, identify what you have: a single-server share link describes one server, a subscription URL retrieves a set of entries that can be updated, and a configuration file may contain rules and other settings. They are not interchangeable just because each looks like a string of text. Use details from a service you already have or your existing configuration. If you only have a hostname and password but do not know the protocol, port, or transport, verify the complete parameters first. Trying different types until an entry saves does not prove it can connect.

In Home, select Add Server, choose the type that matches your source, then enter the address, port, and authentication fields. The address field usually takes a hostname or IP address, not a webpage URL with a path; the port must match the server's listening port. The display name helps you identify the entry and is not used for authentication. Review each field when finished, especially for leading or trailing spaces, full-width punctuation, or truncated strings. Saving only means the input passed local checks; test the connection to determine whether it works.

Fields vary between Shadowsocks, VMess, VLESS, Trojan, and other types. Do not apply the instructions for one protocol mechanically to another. If the source includes TLS, Server Name, Host, or Path, enter each in its corresponding field. Server Name may differ from the connection address, and Path can be case-sensitive. Do not treat disabling certificate checks as a general fix. If the certificate name does not match, first check the device time, name, and original parameters rather than bypassing the configuration issue.

Subscribe: Import and update are separate steps

Import an existing subscription using the appropriate subscription type. Its URL is generally used to retrieve a list of servers, not as the hostname for a single server. Copy the complete URL before importing, paying particular attention to parameters after the question mark; these may contain sensitive information that identifies your account. After importing, check that the expected entries appear, groups are clear, and the number of entries looks reasonable, then test one server. A successful subscription request only means the list was retrieved; it does not mean every server in that list can connect over your current network.

An update retrieves new content from the subscription provider, so do not treat a subscription-managed entry as a permanent manually edited copy. If you need to adjust an entry temporarily, keep the original details and, if needed, save a separate test entry. Check whether a later update overwrites your changes. If you see duplicates, first determine whether the same subscription was imported more than once or whether a manual copy exists alongside a subscription entry. Do not delete entries in bulk until you have confirmed their source; you could remove your only working configuration.

If an update fails, check the request path

If a subscription update fails, first confirm that the device has a working network connection, then check the URL, current access route, and server response. If the current server is unavailable, using it to request the subscription may also fail. If you understand the implications, switch to a route that can reach the subscription URL and try once more. For authentication or permission errors, check whether the original URL has changed. If content is retrieved but cannot be parsed, confirm that it is a supported subscription response rather than a login page, error page, or ordinary information webpage.

After importing, keep track of the entry's source, current selection, and update result. See Share Links and Subscription URLs for an explanation of the differences between single-server links and subscriptions. For the next test, use one clearly identified entry. Do not update an entire subscription group while also changing rules and DNS; keep the inputs stable so you can tell what changed when you adjust Global Routing.

04 / Choose a Traffic Route

Global Routing Modes and Rule Matching

What Config, Proxy, and Direct control

Check Global Routing before testing a connection. Config handles requests according to the rules in the currently enabled configuration; Proxy sends applicable traffic through the proxy route; Direct uses a direct route. These modes select a route and do not change server authentication details. If the same destination behaves differently in different modes, check the routing path before rebuilding the server entry. Also distinguish mode names in the interface from uppercase policy keywords in rule text.

For troubleshooting, you can temporarily use Proxy to test the selected server, then restore the intended mode when you are done. If Proxy works but Config does not, there is at least a rule difference worth checking; it does not prove the subscription is broken. Direct can help compare access over the current network, but not every destination is expected to be reachable directly. Record the destination and mode with each test result. Saying only “it works” or “it doesn't” is too vague to guide the next configuration change.

Rules are checked from top to bottom; put specific conditions first

Config rules are generally checked from top to bottom, and the policy for the first match is applied. DOMAIN matches a complete domain; DOMAIN-SUFFIX matches a domain and its subdomains; DOMAIN-KEYWORD matches a keyword in a domain; IP-CIDR and IP-CIDR6 match address ranges; GEOIP uses IP geolocation data; FINAL handles requests that did not match earlier rules. The broader a condition is, the more likely it is to catch requests before later rules. Put specific conditions first, followed by broader conditions and a fallback.

The following is a teaching example of a .conf rule snippet, not a complete configuration to replace your current settings. The domains are examples, and PROXY requires an available proxy route. Before trying the example, copy your original configuration and edit the relevant section in the copy. Confirm that the configuration you want to test is enabled. Saving text to a file does not mean the current connection has loaded it; after switching configurations, make a new request to check the rule result.

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

In this example, example.com and its subdomains are routed through PROXY first. Other requests with example in the domain may be caught by the second rule. These rules are not equivalent; the latter matches more broadly. Private IP ranges and GEOIP conditions are checked next, and remaining traffic is handled by FINAL,DIRECT. If FINAL is placed at the top, the specific rules below it will not work as intended. Changing the fallback to FINAL,PROXY also changes the route for unlisted traffic; it is not just a formatting change.

Use minimal changes to test your routing intent

To route only a specified website through the proxy, you can keep its DOMAIN-SUFFIX rule and end with FINAL,DIRECT. However, a webpage may request multiple domains. Matching the main domain does not mean image, login, or API requests use the same route. If only part of a page loads, check the requests that actually failed and decide whether to add explicit domain conditions. Avoid hiding the problem with overly broad keyword rules, which may also change the route for unrelated requests that should remain direct.

Test rules with new requests and, if necessary, reconnect to avoid misreading an existing connection that continues to use its previous route. IP-based conditions may also depend on resolution results, and GEOIP cannot precisely represent every site's business location. For more on matching, see Rule Keywords Explained. For an example of routing selected sites, see Routing Selected Sites Through a Proxy. After each change, record the destination, matched rule, and final policy; this is more useful than watching the connection icon alone.

05 / Connect

Connection Tests and Troubleshooting Steps

Set up a repeatable test

Before connecting, confirm that the device can reach a known working website, that the server entry is clear, and that Global Routing is set to the mode you intend to test. For the first check, stay on the same Wi-Fi or cellular network. Do not switch networks, update a subscription, and edit rules during the same test. Record the test destination too: a webpage, login endpoint, and in-app request may use different domains. One successful request does not prove that all network activity works.

After selecting a server, run Connectivity Test, turn on the main connection, and make an actual request. The test result only indicates reachability and response time under that test method; it does not represent every protocol, destination, or persistent connection. Some networks handle the test request differently from real traffic, so a failed test does not necessarily mean all service is unavailable. Conversely, a response does not prove authentication, TLS, or access to the destination will succeed. Assess both types of evidence together.

Check “connected” and “can access” separately

After turning on the main switch, first check whether the system connection status remains active, then make a new request in a browser. If the switch quickly turns off, check system authorization, whether the configuration can load, and any error message. If the status remains active but the destination fails, check the server, route, DNS, and request details. Do not treat the system VPN indicator as a final success check: it describes the local network configuration, while the request still depends on resolution, connection, authentication, and the destination's response.

If the page opens, also check whether it used the expected route. In Config mode, inspect the rule and policy for the specific request. In Proxy mode, confirm that the selected server is the one you meant to test. If the page content came from cache, refreshing may not show whether the new route works; try a clearly new request or reopen the destination. When testing is complete, restore your everyday mode and test again so temporary global settings are not left enabled.

Choose the next check based on where it failed

First check the current network: if you still cannot reach a known working destination with the connection off, troubleshoot Wi-Fi, cellular data, captive portal sign-in, or device network restrictions. Next check the server: verify the address, port, authentication fields, and service status. Trying another entry you already have under the same conditions can show whether only one server is failing. Then check routing: if Proxy works but Config fails, review the enabled configuration, destination rules, and fallback policy. Reach a conclusion at each stage before moving to the next.

Fourth, check DNS and the destination request. If hostname resolution fails, the connection has not reached the expected server communication stage. If the name resolves but the request times out, distinguish connection establishment, authentication, and waiting for a response. For certificate errors, check the device time and the match between Server Name and the certificate; do not simply disable verification. If only one website fails, consider the destination's status, sign-in state, and related domains before declaring the entire configuration unusable.

Change one thing at a time and keep a rollback point

Troubleshooting becomes difficult when you change several parameters at once and then finally get a connection, without knowing which change helped. Keep a time-ordered note of the original value, each change, and its result. Adjust one condition at a time, and make sure each change has a clear purpose. If it does not help, restore the original value before moving on. If the result improves, repeat the same test to confirm. This also helps distinguish a genuine fix from a temporary network fluctuation.

For more steps, follow the Connected but No Internet Checklist. When describing an issue, include the network type, Global Routing mode, error category, and steps to reproduce; do not share complete authentication details. A useful report says “on this network, in this mode, this destination produced this result,” rather than providing only a screenshot of the switch. These notes will also help you interpret Data in the next chapter.

06 / Review Diagnostics

Understanding Data, Traffic, and Request Results

Check the measurement scope and time period first

Data provides traffic and connection information from the app; the items shown depend on the current interface. Before interpreting a value, check whether it covers the current session, a time period, or accumulated records. Numbers from different views may cover different ranges and cannot be subtracted directly. Local app records may also differ from a provider's billing measurements, so do not assume they show the same change in usage allowance. Check your existing service records for that information.

To make changes easier to interpret, note a starting point, open just one destination to test, and observe new records and traffic changes. Background syncing, notifications, image preloading, and requests from other apps can also generate traffic while a connection is active. An increase in upload or download data only means that data was processed; it does not prove that the page you tested loaded successfully. A failed page may still generate some traffic because resolution, handshakes, retries, and error responses all involve communication.

Review domains, policies, and errors together

If the current interface shows request details, check the destination domain, policy, and result rather than looking only at totals. In Config mode, a request may use DIRECT because it matched a direct rule or because the final FINAL rule caught it; check the match details to tell which. If the current record does not show the matched rule, narrow it down using rule order and controlled tests. Do not guess which domain rule matched based on an IP address alone.

For a resolution error, first check the DNS route and destination name. For a connection timeout, distinguish an unreachable server from an unreachable destination or a delayed response. For authentication failures, return to the server entry and verify the identity fields. Similar symptoms can have different causes: a page that keeps loading might be using the wrong route for an API domain, or the server may simply be slow to respond. Error messages help narrow down the layer involved; do not treat a single word as a reason to apply a fixed configuration change.

Use controlled comparisons to explain unexpected changes

If you suspect a page is generating ongoing traffic, close the page and related apps first and see whether similar requests continue. Then open it by itself and compare the new records. Keep the server, Global Routing mode, and network type unchanged during the test. If traffic continues after closing the page, background tasks or persistent connections may not have stopped immediately; do not assume the app is behaving abnormally. Waiting briefly and observing again preserves more useful evidence than clearing all data and starting over.

If you suspect rules are not taking effect, first confirm that you are looking at requests created after the change. Existing connections may continue using their previous route, so Data can show results from different times. End the test page's connection, then visit it again the same way. If appropriate and you understand the impact, reconnect the client too. Distinguish old records from new ones; an earlier policy still appearing in the list does not prove that the saved rule has no effect.

When traffic suddenly increases, first check for real activity such as photo syncing, media playback, or app updates. Then look for repeated failures and retries. The same destination appearing with errors many times may indicate repeated attempts, not a successful large download. Use the failure times and error types to return to the connection troubleshooting steps. Do not attribute every anomaly to server speed or change the entire configuration based on one brief observation. First identify the request type and the conditions under which it changed.

Keep useful records and limit exposure of sensitive data

When saving diagnostic information, a timestamp, mode, destination category, and brief error summary are usually more useful for routine maintenance than complete network content. Domains, request paths, and access times may also be personal information. Before sharing a screenshot, check for subscription URLs, authentication parameters, or private browsing details. Keep only what is needed to describe the issue; technical logs are not automatically free of sensitive information.

Before clearing history, save the minimum evidence needed for the current investigation, then check exactly what the clear action affects in the interface. Clearing diagnostic records does not delete servers, and deleting an entry does not reset system authorization. Check which item you are about to change. Data is most useful for testing and comparison: it links what you expected to happen with what actually happened. It cannot confirm service status or prove from a single total that every request used the same route.

07 / Adjust Common Settings

Settings, DNS, and On Demand

Identify which settings scope applies

Before changing Settings, decide whether the issue concerns app-wide behavior, the current Config, an individual server parameter, or system network permissions. Similar options can exist at different levels; do not assume they control the same thing just because their names sound alike. For example, a server's TLS field affects that server's connection, DNS conditions in a configuration affect resolution, and On Demand controls automatic triggers. Actual behavior depends on both the current interface and the enabled configuration. Note the original location and value before making changes to avoid repeated adjustments at the wrong level.

For a configuration that already works reliably, make changes to achieve a specific goal, such as reducing manual connection steps, fixing a DNS resolution failure for one domain, or testing behavior on a particular network. Do not assume a set of settings found online is universally optimal; server requirements, network conditions, and routing goals vary. If an option differs from what you see in a guide, use the current app interface as your reference. Leave settings you do not understand unchanged until a small, controlled test shows what they do.

DNS: Resolution results affect later connections and matching

DNS converts domain names into addresses, but getting an address is not the only measure of success. The route used for the DNS request, whether the result suits the current network, and how later requests connect can all affect access. System DNS, custom DNS, and DNS over HTTPS differ primarily in how and by whom resolution requests are handled; the name alone does not tell you which will be faster. Before adding a custom resolver, determine whether the original issue was a resolution failure or a connection failure after resolution.

DNS over HTTPS requires access to the relevant resolver endpoint. If reaching that endpoint depends on a proxy route that is not yet working, this can create a startup dependency. Similarly, a server address given as a hostname must resolve before a connection can be established. After changing DNS, test the server connection and destination domain separately. Opening a cached page is not enough to show that everything is working again. If the change does not help, restore the original setting and check other parts of the connection.

DNS results may also affect address-based rules such as IP-CIDR and GEOIP, but domain rules and address rules do not work under identical conditions. A website may return multiple addresses, and different requests may use different records, so one resolution result cannot represent all of its traffic. See DNS Settings for more details on choosing and testing DNS options. Record the destination, resolution result, and access behavior before and after a change so you do not mistake a cache change for a configuration improvement.

On Demand: Configure automatic triggers after manual connections work

On Demand triggers connections according to configured conditions; it does not fix incorrect server parameters. Before enabling it, make sure manual connection, disconnection, and reconnection all work reliably. Then add automatic triggers one at a time. If the interface allows conditions based on network environment, test what happens when entering, leaving, or switching between those environments. Add one type of condition at a time and observe whether the system starts the connection when expected. This avoids overlapping conditions that make automatic reconnections hard to explain.

After enabling On Demand, a connection that starts again soon after you manually disconnect may still meet an automatic trigger condition. Check On Demand first rather than repeatedly deleting the VPN configuration. To establish a direct-connection baseline, temporarily stop the relevant automatic triggers before disconnecting; otherwise, the connection may restart during the test. Restore the original conditions after troubleshooting and confirm they still support your everyday needs. Automation should extend a verified workflow, not conceal an unstable connection.

Test advanced options conservatively

For local network resources, UDP traffic, or a particular transport issue, first confirm that the server and current protocol support the requirement, then look for the relevant setting. Enabling an option cannot give the server a capability it does not have. Do not change several low-level parameters to troubleshoot an ordinary webpage issue; that adds variables and makes the original problem harder to reproduce. If an existing configuration includes special DNS or routing settings, understand their purpose and keep a copy before experimenting with a duplicate.

Once the connection works, the priority is not to keep adding settings but to make sure the configuration is understandable and every change can be rolled back. Keep server, Config, and app-level settings distinct so you can adjust only the relevant layer when the network changes. Before everyday use, check the final Global Routing and On Demand settings so temporary test options are not left enabled. The next chapter turns these checks into a repeatable maintenance routine.

08 / Keep Your Configuration Recoverable

Backups, Updates, and Routine Maintenance

Back up each item separately

The app, server entries, subscription URLs, Config, and system permissions are separate items. Saving one does not necessarily restore the whole setup. Before maintenance, list what you depend on: which entries come from a subscription, which were added manually, which configuration is enabled, and whether you have edited any rules. When using the save or export options in the current interface, check exactly what they include. If only some items can be saved, preserve the others separately; a filename alone does not prove you can restore everything.

Backup files may contain server authentication details or subscription credentials. Store them somewhere accessible only to you or people you have explicitly authorized. Public notes, shared photo albums, and publicly accessible folders are not suitable places for the original data. For your own records, you can note the backup's purpose, source, and local date, but do not put passwords in filenames. A backup is useful only if you can identify and restore the items you need, not simply because you once tapped Save.

Make a copy before editing and record the test result

Before editing Config, keep a copy of the current working version and write down the issue you are trying to fix. Keep each change focused on one goal, such as adding a domain rule, rather than reordering all rules, replacing DNS, and changing servers at the same time. After saving, confirm that the new copy is enabled, then make a new request using the connection steps in this guide. If the result is unexpected, switch back to the old configuration and test again. If it works under the same conditions, there is more reason to investigate your latest change than to blame the external network.

Maintenance notes can be simple: record the issue, original value, location of the change, test destination, and result in order. For rules, also note the expected policy and what you observed. For server parameters, note where you can verify them again, but do not save sensitive details in a document that could become public. These notes show which fixes have already been tested. Over time, they also help distinguish a repeatable fix from a one-off recovery and reduce trial and error.

Schedule app and subscription updates separately

Shadowrocket app updates are handled through the App Store; check the listing for current version information and update details. A Subscribe update retrieves the contents of an existing subscription. These are separate processes. To make problems easier to identify, avoid updating the app, refreshing a subscription, and replacing the entire configuration in the same test cycle. After each update, confirm that existing connections and common destinations still work before making another change. If the interface has moved, locate the relevant item first rather than importing again and creating duplicate entries.

After a subscription update, check whether the previously selected server is still present, whether its name or group changed, and whether manual edits were overwritten. An old entry disappearing may reflect changes from the subscription provider, not a local save failure. Check the update result and entry source before choosing a server again. If an update fails but the old list remains, remember that your test is using previously saved data. A working old entry does not mean the latest update succeeded.

Recovery after changing or reinstalling a device

When moving to a new device, first check your App Store purchase history and compatibility. Then restore your own servers and Config, and finally review system permissions and automatic triggers. Being able to redownload the app does not guarantee that local entries will reappear; handle system network authorization according to the prompts on the new device. After restoration, manually test one clearly identified entry, then check rules and DNS, and configure On Demand last. This order helps prevent automatic connections from repeatedly triggering before you have confirmed that the configuration works.

If you see duplicate content after restoring, do not clear everything in bulk. First identify what came from a backup and what was imported again from a subscription, then choose which source to keep. Before deleting a subscription group, check whether its managed entries will also be removed. For any cleanup involving multiple items, preserve the information needed to restore them and proceed step by step. For purchase checks, see Restoring a Previous Purchase. Purchase history and configuration backups serve different purposes.

Keep a short, consistent routine for everyday checks

When an issue occurs, follow a consistent order: check whether the current network works, whether the correct server is selected, whether Global Routing suits the task, whether the expected Config copy is enabled, and whether the latest subscription update succeeded. Then investigate DNS, rules, and individual requests. Once you confirm the source, you can remove test entries you no longer need; keep useful configurations clearly named. When troubleshooting is complete, restore temporary settings and test a commonly used destination again so you do not fix one case while leaving a new route in place.

For your first setup, follow the main steps in Quick Start. To understand a particular symptom, use this page's contents to find the relevant stage. The goal of a complete maintenance routine is to know where each change came from, what each test covers, and how to roll back every modification. One successful connection does not guarantee that every scenario will keep working, and a stable setup does not need to be rebuilt frequently. Keep necessary records and troubleshoot one layer at a time; this is usually clearer and more repeatable than continually adding settings.