Official Manual · First Connection

Shadowrocket Getting Started Guide

Follow the steps in order: import, choose a route, connect, verify, and troubleshoot. For your first use, establish one verifiable connection before adjusting rules or automatic connection settings. Avoid changing multiple conditions at once.

Before you begin, confirm whether you have a single server share or a subscription URL that can update multiple entries. They use different fields, and you cannot identify the type from the URL alone. If unsure, ask the provider of the details to confirm. Subscription URLs, passwords, and QR codes may contain access credentials; do not include them in public screenshots or comments.

01 · Add Server / Subscribe: Add existing details

Open Shadowrocket and go to Home. On first use, the list may not contain any server entries; this is normal before importing details. Tap the plus sign in the upper-right corner to open Add Server, then choose an import method based on the information you have. Complete either of the options below; there is no need to add the same details more than once.

Existing subscription URL: Choose Subscribe

In Add Server, choose Subscribe under Type, enter your complete subscription URL in URL, set a recognizable name, and save. When pasting, check that no spaces, line breaks, or explanatory text have been added before or after the URL. Do not remove parameters after the question mark; they may be needed to identify your subscription. Save, wait for the update to finish, then return to Home and check the subscription group and its server entries.

Seeing the subscription name does not necessarily mean that the servers were imported successfully. Expand or open the relevant group and check that selectable servers actually appear. If there is only a group with no entries, check the subscription update result before turning on the connection switch. If an update fails, keep the original URL for reference, confirm that the subscription is still valid and that your current network can access it, and ask the provider to confirm that its output format is compatible with Shadowrocket. Do not change URL parameters at random just to make entries appear.

Existing single server: Enter the details for its protocol

If you have server parameters, first choose the matching Type in Add Server, then enter the address, port, and authentication details. Fields vary by protocol; for example, some types use Password while others use UUID. These values are not interchangeable. Server addresses, TLS-related names, and transport paths can also serve different purposes. Enter each value as provided rather than combining fields that look similar. For details about protocol fields, see the Protocol Technical Reference.

If your provider has supplied a QR code, use Scan QR Code from the add menu on Home. After importing, review the entry details and check the type and address. Scanning reduces manual entry but does not confirm that the details are still valid. Save, return to Home, and select the server you plan to use. Confirm that it is selected. This completes the import; next, decide which connections it should handle.

02 · Global Routing: Choose how connections are routed

Tap Global Routing on Home and choose Config, Proxy, or Direct. These options determine how connections are routed; they are not server protocols or speed tiers. For your first test, note the current selection. Otherwise, different results with the same server under different routing modes can make it seem as though the server details have suddenly stopped working.

Config: Route traffic using existing rules

Choose Config for everyday rule-based routing. It handles connections according to the currently enabled configuration, so first open Config and confirm that a usable configuration is present and the intended one is selected. Rules are generally matched from top to bottom; once a rule matches, its associated policy applies. DIRECT uses a direct connection, PROXY passes traffic to a proxy policy, and REJECT blocks the connection. If the configuration uses policy groups, also check which option is selected within each group. Selecting a server on Home alone does not mean every policy group will use it.

If you do not have a valid configuration of your own, do not assume that selecting Config is enough to enable rule-based routing. Test the server using the next mode first, then review your configuration. Do not overwrite an existing Config without understanding its contents. If you already have a configuration, keep a copy and change only the rules that need checking. For more detail about Rule matching and restoring configurations, see the FAQ.

Proxy and Direct: Use to identify the connection route

Proxy is useful for a brief check of whether the selected server can handle real requests. It generally routes connections handled by the app through the proxy, helping separate rule-related issues from server-related ones. Server availability still depends on its address, parameters, and network. After testing, switch back to Config if you want to use rules, and test again. A successful Proxy test does not prove that your routing configuration is correct.

Direct sends connections handled by the app through a direct route; it does not confirm that the proxy server is working. Use it to compare against your baseline network if needed, and remember to restore the intended routing mode afterward. Once you have chosen Global Routing, return to Home, check that the correct server is selected, and then connect for the first time.

03 · Home: Turn on the connection and allow the VPN configuration

Return to Home, check the selected server and Global Routing, then turn on the connection switch at the top. When connecting for the first time, iPhone / iPad may show a system prompt to add a VPN configuration. Confirm that you initiated the request by opening Shadowrocket, allow the configuration, and complete verification using your device passcode or biometric authentication if prompted. This authorizes the device to create a local VPN configuration; it does not purchase or activate a server.

After authorization, return to Shadowrocket and check whether the connection switch stays on and the app shows a connected status. A VPN status in system settings only indicates that the system-side connection configuration is enabled; it does not report whether the server is usable. An incorrect server password, a domain lookup issue, or unexpected rule routing can still occur while the connection appears active, so complete the real-world access check in the next section.

If the switch turns off immediately, consider whether you dismissed the initial system prompt. Open system Settings, search for VPN, and check whether the relevant configuration exists and whether device management restrictions apply. If the device is managed by a school or employer, follow its requirements. Do not delete other VPN configurations or profiles without understanding their purpose. Another active VPN may also affect the connection; before testing, identify which configuration is handling it.

For your first setup, use a manual connection and do not rush to enable On Demand. Automatic connection can reconnect the device after network changes, making it harder to compare results after turning the connection off. Read about the conditions for using On Demand after manual testing succeeds. You also do not need to toggle the switch rapidly while connecting: wait for the status to settle, note any error, and then continue. This preserves useful troubleshooting information better than repeated retries.

04 · Connectivity Test: Test and verify real-world access

First, use Connectivity Test on Home to check whether the server entry is reachable and whether the selected entry returns a result. This is useful for spotting obvious timeouts, but the test method and target affect its results. Do not treat a single displayed value as a complete measure of performance, or assume that one timeout means every request will fail. After the test, keep the server and Global Routing unchanged and check real-world access in a browser.

Open a familiar webpage that should be working, check whether it loads, then try a different site. Testing only one page can be misleading due to an issue with the site itself, cached content, or a logged-in session. A page loading does not prove that it used the proxy route. Check Global Routing and the current Config Rule to confirm whether the request should use DIRECT or PROXY.

If the app's connection records show matching information for the request, check the destination domain, matched rule, and policy. With Config enabled, a site that connects directly may be following the rules as intended; do not assume the connection has failed just because it did not use the proxy. Conversely, if a request expected to use PROXY is not handled as planned, check the rule order, selected configuration, and policy group rather than immediately replacing the server details.

For a clear comparison, note three results: the current routing mode, whether Connectivity Test returned a result, and whether the browser request succeeded. If needed, switch to Proxy once and test the same target again. If Proxy works but Config does not, check the rules or policy configuration first. If both fail, continue checking the server parameters and network. After testing, restore the mode you need for everyday use so you do not leave a temporary diagnostic setting in place.

Finally, close and reopen the target page in the browser to reduce the chance of a misleading result caused by old cached content. Do not infer the connection status of every app by repeatedly refreshing the same page; apps may keep existing connections and need to initiate a new request before changes take effect. The first test is complete when you can explain what you selected, how the request was routed, and what the result was.

05 · Common issues: Check each layer without changing several things at once

When a connection fails, start with the earliest step that did not meet expectations. If the import has not succeeded, fix that first. If the server test keeps timing out, check the parameters. If only Config behaves unexpectedly, check the rules. Breaking the problem into layers avoids changing something that was already correct and turning one error into several.

  1. No server to select on Home: Check whether the subscription contains actual entries, whether the update returned an error, and whether you entered details for a single server under Subscribe by mistake. A subscription name alone does not mean its contents have been parsed. Ask your provider to confirm the format and validity; there is no need to change Global Routing yet.
  2. An entry exists, but Connectivity Test times out: Open the entry details and check the address, port, Password or UUID, TLS settings, and transport parameters one by one. Check letter case, the slash at the start of a path, and any trailing text missed while copying. Do not change the port to a common value based on guesswork; use your original details.
  3. Both the test and requests fail: Check that the device date, time, and time zone are correct. Turn on automatic system settings and try again; an incorrect time can affect certificates or authentication. If possible, test on both Wi-Fi and cellular data, keeping the server and parameters unchanged for each test. If only one network fails, note the difference instead of rebuilding the entire configuration.
  4. The connection switch will not stay on: Return to the system VPN settings and check the authorization and active connection configuration. Also check whether another VPN is handling the connection. If device management restrictions apply, ask the administrator. Resolve conflicts only when you understand the impact and have preserved the original configuration. Do not delete certificates or reset all network settings without cause.
  5. Proxy works, but Config does not behave as expected: Confirm that the correct file is enabled in Config, then check which Rule matches the request and which policy it uses. A broad rule listed earlier may prevent a more specific rule below it from running. A policy group pointing to an unavailable entry can also cause real connections to fail even when the server test succeeds.
  6. Only one webpage or app has an issue: First distinguish an issue with the target service from a domain lookup failure or an incorrect connection route. Do not immediately disable TLS verification or make broad DNS changes. Note the affected domain, error message, current network, and routing mode, then read the FAQ troubleshooting guide for rules and connection issues and continue based on the symptoms.

After each change, test the same target again and note whether the result changed. When checking with your provider, share only the necessary symptoms, protocol type, and redacted parameters. Do not disclose your full subscription URL, authentication details, or QR code. For details on why protocol fields differ, see the Protocol Technical Reference. You do not need to learn every protocol before establishing your first connection.

When finished, keep a clear record of the setup: which details were imported, which entry was selected, which Global Routing mode was used, and the results of the test and real-world access check. When updating a subscription or adjusting Config later, change one layer at a time and repeat the test. This makes it easier to troubleshoot from the last known working state, even when network conditions change.