Shadowrocket Quick Start
Add an existing configuration → Choose a routing mode → Connect → Verify the result → Troubleshoot issues.
For your first setup, focus on getting one connection working and verifying it. First, identify what you have: a single server entry contains the address, port, and authentication details for one connection; a subscription URL retrieves a server list. A configuration file determines how requests are routed. These are different types of information and shouldn’t be entered in the same field. After each step, return to Home and check the result before continuing.
01 · Add Server / Subscribe: Add Your Existing Details
Choose the right option for your details, then confirm the server appears on Home after saving.On Home, tap Add Server near the SERVER section to open the server editor. For a complete set of server details, select the matching Type and fill in the corresponding fields. For a subscription link, choose Subscribe under Type, enter the full URL, and save. Don’t enter a subscription URL as a single server’s Host.
When entering server details manually, make sure Type matches the protocol in your existing information. Shadowsocks, VMess, VLESS, Trojan, and other protocols use different authentication fields; don’t switch types just because the server address is the same. The screenshot shows an editor with Type, Host, Port, Password, and Method. Available fields may change when you select a different Type, so fill them in using the details for that protocol.
Host is the server address; Port is the port number. Copy all authentication details exactly, checking for leading or trailing spaces and line breaks. Match Method and other parameters to your existing server configuration; don’t guess. For TLS, server names, or transport settings, follow your existing configuration details as well. If a field is unclear, check the glossary before continuing.
If you have a QR code, use Scan QR Code to import it, then check the recognized fields. Import from Cloud JSON is a separate import option, not the same as Subscribe; use it only if you already have data in the corresponding format. Whichever option you use, verify the server type, address, and authentication fields before saving rather than relying on a familiar name.
After saving a subscription, check the server list—not just the name
When importing with Subscribe, copy the full subscription URL, including any query parameters at the end. Some URLs contain information used to identify your account; removing parameters may change the response or prevent access. This guide doesn’t show real subscription URLs. Use your own existing link, and don’t share it in public screenshots, chat logs, or support requests. After saving, wait for the app to retrieve the contents, then return to Home and check for server entries.
If you see a subscription group but no selectable servers, check the retrieval or update result before turning on the connection. Make sure the URL is still valid, copied in full, and reachable on your current network. If it needs updating, use the update action for that subscription. After updating, check the list again—server names, order, or contents may have changed. Select the server you intend to use from the SERVER list and verify the selection indicator; don’t assume the first entry is selected.
Before moving on, make sure you can answer two questions: Is there usable server information in the list, and which entry is selected? A successful subscription import only means the list was retrieved; it doesn’t mean every server in it works. Confirm both points before choosing a routing mode so you don’t mistake an import issue for a rules issue.
02 · Global Routing: Choose How Requests Are Handled
Confirm the mode first, then decide whether to check the rules.Return to Home and tap Global Routing to see the current selection. The three options are Config, Proxy, and Direct. This setting controls how requests are handled; it doesn’t fill in server details or change the authentication information for an existing service.
Config handles requests according to the rules in the current configuration file. Use it when different destinations should follow different policies, after confirming the correct configuration file is selected. Proxy is useful for temporarily checking how requests behave through the current proxy mode, but it doesn’t replace verifying your configuration rules. Direct connects directly; don’t expect requests to go through the proxy in this mode.
To use Config, open Config at the bottom and find the active configuration file. Open it and check Rule. The official screenshot also shows General, Hosts, URL Rewrite, and HTTPS Decryption. For an initial setup, just confirm which file is active and whether its rules look right; you don’t need to edit every section to establish a connection.
Rules are matched in order, and the first matching rule determines the policy. DOMAIN and DOMAIN-SUFFIX match different sets of hosts; FINAL is usually placed last as a fallback. PROXY, DIRECT, and REJECT are rule policy keywords. PROXY in a rule and Proxy under Global Routing are separate settings—check whether you’re editing a rule or changing the global mode.
Understand Config with a Short Rules Example
This is a syntax example, not a complete configuration to replace your existing file. The first rule sends example.com and its subdomains to PROXY; the second sends other unmatched requests to DIRECT. The example domain only illustrates the syntax—it doesn’t indicate how your actual destinations will behave and contains no server authentication details.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTIf a fallback rule comes first, later rules may never be checked. When reviewing a real configuration, check both the rules and their order. For your first test, keep your existing configuration and note the selected Global Routing mode. If the connection is established but a specific destination behaves unexpectedly, return to this section. For detailed explanations of rules, policies, and configuration sections, see Rules and Configuration Field Reference. This guide covers only the basic mode check.
Before moving on, identify whether you’re using Config, Proxy, or Direct. If you chose Config, note the active file as well. Return to Home, check the Global Routing value again, and confirm your selection took effect before connecting.
03 · Home: Approve and Start the Connection
Before connecting, check both the selected server and Global Routing mode.Return to Home, confirm the intended server is selected in the SERVER list, and check that Global Routing shows the mode you chose. Not Connected at the top means the app connection isn’t established yet. Turn on the switch beside it to start connecting.
The first time you connect, iOS may ask to add a VPN configuration. Confirm the prompt is from Shadowrocket, then allow it and complete any authentication required by your device. This authorization creates the configuration needed for the connection; it doesn’t confirm that a subscription was retrieved or that the server authenticated successfully.
If you dismissed the system prompt, return to the app and try connecting again, then check the relevant configuration under the system’s VPN settings. Don’t keep switching servers before confirming whether authorization is complete. System authorization and server authentication are separate checks: the device handles the first; the imported fields and existing server determine the second.
After approving the configuration, return to Home and check whether the connection status and switch remain on. If the switch turns off immediately, the status stays disconnected, or an error appears, note its exact wording and continue to the troubleshooting steps. Don’t rely on the status bar icon alone to determine whether the remote service is working: the icon, the app’s connection status, and successful requests are different things.
If another VPN configuration is already on your device, check which one is active to avoid testing through an unexpected connection. For your first test, leave On Demand unchanged. Its conditions can affect connection behavior, making it harder to tell whether the manual switch or an automatic condition triggered the connection. First establish a clear manual connection and verify it works; configure On Demand later if needed.
Once the connection is stable, leave the configuration as it is for now. Keep the same server and Global Routing mode as you move to verification. That way, if the next step produces an unexpected result, you can tell whether it’s the test method, destination matching, or server—not several changed settings at once.
04 · Connectivity Test: Verify the Connection and Routing
[Rule]Check test results alongside real-world access.On Home, tap Connectivity Test and wait for the result. See Test Method under Settings to understand how the test works. Different methods check different parts of the connection; a single result doesn’t prove that every site, protocol, or app will work. If a test fails, confirm the method and conditions before deciding the server is at fault.
Server reachability, an established app connection, and requests handled according to the intended policy are three separate things to verify. A response in the server list test doesn’t rule out incorrect authentication or later transport issues. Even if the top switch stays on, a rule may send a particular destination to DIRECT or REJECT. Before testing, note the server, Global Routing mode, and active configuration so you can repeat the same check.
Open a browser or the app you plan to use and visit a destination you know and are authorized to access. Check that the page finishes loading, not just that the first screen appears. With Config, also test one destination expected to use DIRECT and another expected to use PROXY. If the app shows connection records, check the destination, matched rule, and final policy. Whether a page opens alone doesn’t reliably show how its requests were routed.
If the result isn’t what you expected, return to Config and check the rules for that destination, including any rules above them. Domain suffixes, full domain names, and IP addresses use different matching conditions. A page may also load resources from other domains, so if the main page opens but some resources fail, check the specific failed requests—not just the domain in the address bar. For questions about rule syntax, see DOMAIN-SUFFIX explained and the configuration field reference.
To narrow down the issue, note your original settings and temporarily switch to Proxy to test the same destination. If it works in Proxy but not as expected in Config, check the active configuration and rule order first. If both modes fail, recheck the server details and connection status. This is a troubleshooting technique, not a recommendation to leave Proxy enabled. Restore the mode you need when you’re done, then test again.
Before moving on, confirm that at least one real request completed and that the current mode suits your intended use. If you have only a test result and no real-world access check, verification isn’t complete. If the configuration works, keep the result as a baseline. If it still fails, note the specific symptoms for the next step.
05 · Settings / Diagnostics: Troubleshoot by Failure Point
Check the network and imported details first; save advanced settings for last.Return to Home, disconnect, and check that the device can access the internet over its basic network connection. If the network itself is having issues, resolve those before testing Shadowrocket. Switching between Wi-Fi and cellular can help identify whether the issue is network-specific. Keep the server and mode unchanged so you don’t alter multiple variables at once.
If a subscription can’t be retrieved or the list is empty, check the full URL, its validity, and the update result. If a server is imported but won’t connect, open its editor and compare Type, Host, Port, authentication fields, and transport settings against the original details. Check capitalization, missing parameters, and extra spaces carefully; changing rules won’t fix incorrect authentication fields.
If the switch won’t stay on, check that system VPN authorization is complete and read the exact error shown by the app. If the connection is established but destinations behave unexpectedly, check Global Routing, the selected server, and the Config file. In particular, make sure you haven’t left the mode on Direct after testing or switched to a different file after updating the configuration. Only move on to more detailed settings after these basics check out.
Open Settings and find options such as Test Method and Diagnostics. Test Method helps you understand or adjust how tests run; Diagnostics provides diagnostic information. Settings also includes options such as On Demand, Proxy, TCP, and UDP. Don’t switch through them one by one when troubleshooting for the first time. Change only settings related to the current symptom, and note their original values so you can restore them after testing.
Match the Symptom to the Next Check
| What You See | Check First | Next Step |
|---|---|---|
| No servers appear after saving Subscribe | Full URL, validity, retrieval result | Check the details, update again, then recheck the SERVER list |
| Connection switch turns off immediately | System VPN authorization, error message | Confirm authorization, then check the server fields against the original details |
| Connectivity Test fails | Test Method, basic network, server status | Keep other conditions unchanged and test again with real-world access |
| Proxy works, but Config behaves unexpectedly | Active file, Rule order, matched policy | Check whether an earlier rule matches the destination first |
| Only some requests fail | Specific failed destination, protocol requirements, connection records | Troubleshoot the affected requests; don’t reset all settings |
If you need to confirm the status of an existing service, write down the symptoms, when they occur, and the checks you’ve already completed, then contact the service provider. You can include the protocol, current Global Routing mode, test method, and exact error message in your report. Don’t include your full subscription URL, password, or other authentication details. Check Diagnostics output and screenshots for sensitive information before sharing; include only the error details needed.
After basic troubleshooting, if the issue clearly involves rule matching or configuration fields, continue with the Rules and Configuration Field Reference. If you just need a term explained, check the relevant entry in the glossary. You’re done with this quick start when you can explain what you imported, which mode you selected, whether the connection was established, and whether requests were handled as expected—not when you’ve changed a certain number of settings.