Official Manual · First Use

Shadowrocket Setup Guide
Import a Subscription and Connect

Follow the sequence “Import → Routing → Connect → Verify → Troubleshoot.” First establish a repeatable connection, then adjust rules and automatic connection settings. Changing several items at once makes it harder to identify the cause of a problem.

01 · Add Server: Import Existing Details

After opening Shadowrocket, stay on Home and leave the connection switch off for now. The server list may be empty on first use. Choose an import method based on the information you have: a link that updates a server list is usually a subscription, while the address, port, and authentication details for a single server are entered manually. A subscription link and a server address are different fields; do not paste an entire subscription link into the server address field.

For a subscription link: choose Subscribe

  1. Tap the plus sign in the upper-right corner of Home to open Add Server. Tap Type, choose Subscribe from the list, then return to the entry screen.
  2. Paste the complete subscription link into URL. If you need to fill in Remarks, use a name that is easy to recognize. It distinguishes entries in the list but does not change connection parameters.
  3. Save and return to Home, then wait for the subscription contents to load. Check whether server entries appear in the relevant group, not just a subscription name. Once entries appear, select one server for the first connection.

After pasting, check for spaces or line breaks at either end of the link, especially any explanatory text included when copying. If loading fails, first confirm that the basic network works, then check that the link is complete and still valid. Loading subscription contents and connecting to a proxy server are separate processes: an updated list does not mean every server in it is reachable, and a temporary update failure is not a reason to immediately delete all saved information.

For a single server: enter its protocol details

From Home, tap the plus sign to open Add Server. Under Type, select the protocol specified in your details, such as Shadowsocks, VMess, VLESS, or Trojan. Enter the server address and port first, then check the password, UUID, or other authentication fields one by one. Different protocols require different fields; do not reuse parameters from another protocol just because the address is the same. Match capitalization, hyphens, and transport settings to the details you have.

If your details include TLS, SNI, Host, Path, or a transport method, expand the relevant settings and enter each value. The server address is used to establish the connection; SNI and Host may be used for identification at different stages. Do not substitute them for each other just because both look like domain names. Do not guess at parameters that were not provided. If you are unsure what a field means, check with your service provider before saving and testing.

If you have a compatible QR code or share link, you can also use Scan QR Code or the clipboard import option. Scanning requires camera permission; when reading from the clipboard, confirm the system prompt. Regardless of the method, open the entry after import and check Type, address, and port. Server links, QR codes, and subscription URLs may contain authentication information. Do not post them publicly or send them to public discussion forums.

This step is complete when: The Home list contains an actual server entry and one server is selected. Importing alone does not start a connection. For subscription organization, updates, backups, and other tasks, see the Subscription and Server Management Manual. For first use, continue by choosing a routing mode.

02 · Global Routing: Choose How to Handle Traffic

Return to Home and open Global Routing. This setting determines how connections handled by the client are processed. It does not import servers or fix incorrect authentication details. The three basic modes are Config / Proxy / Direct. Before switching, be clear about your goal: testing whether a server works or routing different destinations according to rules.

Config: Use the current configuration's rules

Config matches connections against the currently enabled configuration and is suitable for rule-based routing. Open the bottom Config page and confirm that the configuration you intend to use has been saved and selected. Importing a file into the list does not mean it is active. Configurations can contain different policies and rules, so selecting a server on Home does not mean every request will use that server.

Rules are usually matched from top to bottom; when a rule matches, its corresponding policy is used. PROXY sends traffic to the proxy policy, DIRECT connects directly, and REJECT blocks it. FINAL handles connections that did not match earlier rules. There is no need to edit rules on first use; first confirm the purpose of the active configuration. If you do not have a configuration ready, do not use an unfamiliar file as the starting point for troubleshooting.

Proxy: Check the proxy connection

Proxy sends traffic handled by the client to the proxy policy and can be used briefly to check whether the selected server connects. This mode is also often called “global mode,” but that does not mean the app can bypass every system restriction or handle every type of traffic on the device. For testing, keep the same server and destination. If access works in Proxy but fails after switching back to Config, check the configuration and rules first rather than repeatedly importing the subscription.

Direct: Access destinations directly

Direct lets requests handled by the client reach their destinations directly, without going through a proxy server. It can help compare basic network conditions, but it cannot verify whether a proxy server is working. If you are testing an existing server, make sure Direct is not selected by mistake. After a brief comparison, switch Global Routing back to the intended mode before continuing.

This step is complete when: You can identify whether Config, Proxy, or Direct is selected. If you use Config, you also know which configuration is active. Keep the default automatic connection settings for now and avoid changing On Demand so the first connection is easier to observe.

03 · Home: Turn On the Connection and Authorize It

Return to Home and confirm the selected server and Global Routing mode, then turn on the connection switch at the top. On the first connection, iPhone / iPad displays a system prompt to add a VPN configuration. This prompt allows Shadowrocket to establish a system network tunnel; it is not a subscription import prompt and does not mean the system has verified that the server can connect. Confirm that the request comes from the Shadowrocket app you just opened, tap Allow as prompted, and complete device passcode or biometric authentication.

After authorization, return to Shadowrocket and check the switch and connection status. If you previously canceled authorization, turn the connection switch on again and follow the system prompt; there is no need to delete all servers first. If the system does not prompt you again, check the relevant VPN configuration under “Settings → General → VPN & Device Management,” then return to the app and try again. If device management policies restrict the device, the current user may not be able to change permissions; follow the device management requirements.

If another VPN connection is already active on the device, disconnect it before testing Shadowrocket to avoid changes caused by connections replacing each other. Do not repeatedly start and stop multiple network tools while troubleshooting. A switch that turns off immediately, a removed system configuration, and an automatic connection condition being triggered are different issues. Record what actually happened instead of describing all of them as “subscription expired.”

A VPN indicator or connection status in the system only shows that the network tunnel has reached a certain stage; it does not prove that every destination is accessible. Authentication errors, an unreachable server, and DNS issues can all affect requests after the tunnel is established. After confirming that the switch stays on, continue to an actual access test rather than stopping here.

If you plan to use On Demand later, wait until manual connection and disconnection both work before configuring it. Automatic triggers affect when a connection starts or resumes. Keeping manual control during initial troubleshooting makes it easier to tell a server problem from a change in connection conditions. For more about system prompts, see VPN Configuration and System Permission Prompts.

This step is complete when: System authorization is complete, the connection switch stays on, and no error appears immediately. Next, use actual requests to check the connection and rules instead of repeatedly toggling the switch.

04 · Connectivity Test: Verify the Result

Keep the selected server and routing mode, then use Connectivity Test on Home to check whether the server is reachable. This is an initial diagnostic, not a speed guarantee: a result means the test received a response using its method, while timeout means the test did not complete within the allowed time. Different test methods and app requests may use different connection paths, so do not use a single result to judge every use case.

Next, open a browser and reload a familiar page that you can access. Make a new request instead of relying on a previously cached page. Test an ordinary webpage first, then any feature that requires sign-in or has additional access conditions. If one page fails while others work, record what happened with that destination rather than deciding that the entire connection is unavailable. Do not change networks, servers, and configurations at the same time during testing, or it will be difficult to compare results.

Check the request in Data

Return to Shadowrocket and open Data. Look for a connection record related to the action you just took, and use any visible destination, policy, or error details to help assess it. With Config, some requests going through DIRECT may be expected under the rules; “all requests must go through PROXY” is not a success criterion. If a record shows REJECT, check whether the active configuration intentionally blocked the request before changing servers.

If the expected record does not appear, first confirm that the browser sent a new request, the connection switch is still on, and Global Routing is set as intended. Traffic in the records only shows that a request was processed; check the page result too. Before sharing troubleshooting details, hide server addresses, subscription links, authentication fields, and information that could be linked to a personal account. Keep only the necessary status and error text.

Compare once to distinguish server and rule issues

If a request fails in Config, temporarily switch to Proxy and test again with the same server and destination. If Proxy works but Config does not, check the selected configuration, rule order, and DNS settings first. If both modes fail, continue checking the basic network and server parameters. After comparing, restore the intended mode so you do not forget the actual settings after testing.

This step is complete when: You can explain the connection result using both the active switch and actual requests and records. For a device using rule-based routing, test one destination expected to use PROXY and one expected to use DIRECT. The current configuration determines the actual matches; do not guess based on a website's region.

05 · Troubleshoot by Failure Stage

Start by identifying where the failure occurs: Subscribe contents do not load, a server shows timeout, the switch will not stay on, or only one page fails to open. These are different stages. Keep the current configuration or a necessary backup. Change one item at a time and repeat the same test. Do not start by deleting and reinstalling the app: reinstalling cannot fix server-side parameters and may remove useful diagnostic clues.

Check the basic network, then the subscription and parameters

  1. Basic network: Turn off the connection and confirm that Wi-Fi or cellular can access ordinary websites. Complete any required web-based network sign-in first. You can compare once using another network, but record the results before and after switching.
  2. Import results: Confirm that Home contains an actual server entry and that one is selected. If a Subscribe update fails, check that the URL is complete and valid. Do not treat a subscription name as proof that servers were imported, and do not repeatedly resubmit while an update is in progress.
  3. Address and authentication: Open the server editing page and compare Type, address, port, password, or UUID with the details you have. Extra spaces, missing characters, or selecting the wrong protocol can prevent a connection.
  4. Transport settings: Also check TLS, SNI, Host, Path, and the transport method. Do not disable certificate verification just to clear an error; first confirm that the domain, certificate requirements, and server details match.

If Connectivity Test keeps showing timeout, compare with another existing server on the same network. If only one server fails, check its parameters and status first. If several fail at once, consider the current network and shared settings. For a detailed checklist, see Node Timeout Troubleshooting Order.

Then check routing, time, and system permissions

If only certain destinations fail, check that Global Routing is set to the intended mode and confirm the active file in Config. A broad rule placed earlier may match before a more specific rule later in the list; FINAL should be the last handling rule. Avoid adding many rules while testing for the first time. First use a Proxy and Config comparison to determine whether the issue is related to routing, then read Custom Rules and Matching Order.

For TLS or certificate errors, also check that the device date, time, and time zone are correct. A time difference can affect certificate validity checks, so checking the password alone is not enough. For DNS-related symptoms, consider the failed destination and Data records together; do not replace all settings at once. If the app connects but a particular service still fails, the cause may be that service's account status, access requirements, or a server outage.

If the switch immediately turns off or the system repeatedly changes VPN connections, check that the VPN configuration is still present, whether another connection is active, and whether On Demand has automatic triggers configured. If the device is managed by an organization, first confirm that its policies allow the connection. Handle authorization issues in system settings; there is no need to regenerate a subscription or change the server password.

If these checks do not identify the issue, prepare a short record: current network type, selected protocol, Global Routing mode, Connectivity Test result, the step where the failure occurred, and the exact error text. Do not include a complete subscription link or authentication details. Check server parameters and status with your service provider. For client settings and common system issues, see the FAQ.

After troubleshooting: Keep a record of the working server, current routing mode, and active configuration. Back up any necessary details before adjusting subscription updates or On Demand. More detailed steps for QR code and clipboard imports, subscription organization, deletion, and backups are in the Server Management Manual. There is no need to complete every setting during the first connection.