Shadowrocket Quick Start
Add, Connect, and Verify
Start with existing server details or a subscription link, then import, choose a Global Routing mode, and check the connection. If this is your first time, follow the steps in order. If you have already imported your details, skip to the connection steps.
Before you begin: Shadowrocket is installed, and you have your own subscription link or server details. The iPhone / iPad version is available on the App Store for a one-time purchase of $2.99; Mac (Apple Silicon and Intel), Windows, Android, and Linux versions are free to install from this site's download page. This tutorial uses the iPhone / iPad interface. Check the App Store page for system requirements.
The one-time app purchase does not include a service plan. This site does not provide, sell, or recommend servers or subscriptions; the steps below explain how to import and use a configuration you already have. If Shadowrocket is not installed yet, start with the download guide.
01 · Add Server: Add an existing server
Open Shadowrocket and go to Home. Find Add Server in the SERVER section, or use the add button on the page to open the editor. First identify the type of details you have: if they include a server address, port, password, and protocol parameters, follow this step. If you have a subscription link that updates a server list, go to Subscribe instead. These are alternative import methods; do not add the same details twice.
In Add Server, tap Type and choose the protocol specified in your details, such as Shadowsocks, VMess, VLESS, or Trojan. Type determines which fields appear below, so do not enter a password and then switch protocols at random. For Shadowsocks, enter the server domain or IP address in Host, the port in Port, and the corresponding password and encryption method in Password and Method. Authentication fields vary by Type. Follow the details you have rather than copying fields from another protocol.
Host usually contains only the hostname, such as example.com; do not enter a complete web address with a path. Port is a separate numeric field. When pasting a long password, check for leading or trailing spaces and line breaks. Method must match the server settings exactly. If your details include TLS, SNI, or transport parameters, enter them as specified and do not disable required options just to reduce the number of fields. If you are unsure what a parameter means, confirm it with the source of your server details instead of trying different values at random.
If you have a server QR code, use Scan QR Code to read it, then check the detected Type, Host, and Port. Import from Cloud JSON is another way to import configuration; it is not a field for arbitrary subscription links. Use it only if you have a file in the required format. After checking the fields, tap the save button and return to Home. Confirm that the new entry appears under SERVER. Its appearance confirms that it was saved, but does not mean the connection works; you still need to select a mode, connect, and verify it.
02 · Subscribe: Import an existing subscription
If you have your own subscription link, go to Add Server from Home, tap Type, and select Subscribe. Paste the complete link into the URL field. Subscription links provide a set of server details and often contain personal access credentials; do not post them publicly in comments, screenshots, or group chats. Add a note to help you identify the subscription if needed. There is no need to edit query parameters in the link, and a provider's login page URL is not a substitute for a subscription link.
After saving, wait for the subscription request to finish, then return to Home and check the relevant group. A successful import displays selectable server entries in the group. If you see only a group name and no entries, first check whether the update has completed instead of turning on the connection immediately. Some subscriptions may return an error or unsupported content. Check that you copied the complete link and that it is still valid. Importing a subscription does not import rule files; check Config separately in the next step.
To refresh the list later, use the update action for that subscription group and wait for the request to complete before checking the entries. The server list is determined by the subscription response, and local changes may be overwritten during the next update. For personal changes you want to keep, first determine whether they belong to a subscription entry, a standalone server, or a rule configuration so you do not confuse the three. If you already have a single server and do not use subscriptions, skip this step.
If an update fails, first check that the device's current network can access the subscription address, then make sure the link is complete and has no extra spaces. Avoid repeatedly deleting and recreating the same subscription, as this can make it harder to compare its previous state. A successful subscription update does not mean every server entry can connect; select one and continue with the connection checks below. For more details, see connection troubleshooting in the FAQ.
03 · Global Routing: Choose a mode and rules
After saving a server, return to Home and tap Global Routing to view the routing modes. The three options are Config, Proxy, and Direct. This setting determines how requests are handled; it does not select a server protocol. Changing it does not fill in missing server details or automatically fix an expired subscription. Before connecting for the first time, understand the selected mode to avoid misjudging the route your traffic takes.
| Mode | Purpose and requirements |
|---|---|
| Config | Matches requests against rules in the selected configuration and applies strategies such as PROXY and DIRECT. A suitable configuration must already be selected. |
| Proxy | Forwards requests handled by the app through a proxy. Useful for testing a server connection, but does not mean that a rule file is routing traffic. |
| Direct | Handles requests as direct connections. Useful for comparison with the local network, but does not confirm that a server proxy connection works. |
For rule-based routing, first open Config and confirm that a configuration file exists and is selected. Then return to Home and choose Config. Open the configuration to view sections such as General, Rule, and Hosts. For your first setup, check that the Rule strategies suit your needs; there is no need to change URL Rewrite or HTTPS Decryption at the same time. These features are not required for an initial connection and should not be enabled just to test it.
Rules are usually matched from top to bottom, and the corresponding strategy is applied when a rule matches. PROXY uses a proxy strategy, DIRECT connects directly, and REJECT denies the request. FINAL is the fallback when no earlier rule matches. Do not assume that FINAL sends every request along the same route; the result depends on whether an earlier rule matches. If your existing configuration works, leave it unchanged while completing the connection steps. For rule syntax and priority, see the Config › Rule manual.
If you do not have a rule configuration yet, use Proxy to compare a server you know is available, then set up rule-based routing afterward. Once you have chosen a mode, return to Home and confirm that the Global Routing row shows the selected option before continuing. Change only one condition at a time so you can tell whether a problem comes from the server or the rules.
04 · Home: Turn on the connection and allow the VPN configuration
Return to Home, select the server to use under SERVER, and confirm that it is selected. Then check Global Routing. Do not confuse “the entry has been added” with “the entry is selected.” If the list contains multiple groups, confirm which group the current selection belongs to. Note the server and mode you use so you have clear conditions for the tests that follow.
Turn on the connection switch in the row showing Not Connected at the top of the page. The first time you connect, the system may ask for permission to let Shadowrocket add a VPN configuration. Follow the prompt to allow it, then confirm using your device passcode or the authentication method required by the system. This permission lets the system establish a network connection managed by the app; it is not another purchase. If you denied permission, return to the app, turn on the connection again, and follow the system prompt.
After authorizing, return to Shadowrocket and check whether the status at the top changes. If the switch turns off immediately or the status never shows a connection, stop tapping it repeatedly and go to troubleshooting. Also check for conflicts if another VPN connection is already active. Avoid letting multiple apps repeatedly take over the connection while troubleshooting. If device management policies may restrict this, first confirm whether the device allows this type of configuration.
Once the connection is established, continue by checking actual access. The system VPN indicator only shows that the relevant network connection is active; it does not confirm that every destination is reachable or replace DNS and rule checks. To disconnect, turn off the switch at the top. If it reconnects automatically, check On Demand in the next troubleshooting step instead of deleting all your server details.
05 · Connectivity Test: Verify the connection
Tap Connectivity Test on Home and wait for it to finish. First check whether the selected server has a test result, then open a browser and visit a website you normally use. Confirm that the page actually loads. Connectivity Test results depend on the test method and destination. They do not prove that the entire access path is working: a successful test does not guarantee that domain resolution, website certificates, login sessions, or every app request will work.
For comparison, use the same page on the same local network before and after connecting. Record the result with the connection on, then disconnect and test again if needed. Do not change the Wi-Fi network, server, mode, and DNS at the same time; if access returns, you will not know which change helped. With Config, different domains may use PROXY or DIRECT. A page that opens directly does not confirm that the server used by the proxy strategy is available.
If the test fails but websites work normally, check Test Method in Settings and confirm that the method is supported by the server instead of deleting an entry based on one result. If the test succeeds but a website will not open, check domain resolution and rules. If necessary, compare Proxy and Config temporarily, then restore the intended mode. Keep the same server during the comparison so that differences between servers are not mistaken for differences in rules.
After verification, keep the settings that produced a repeatable result and add your own rule changes or On Demand conditions one at a time. Normal use does not require frequent changes to the test method, and a single test value should not be treated as a long-term performance measure. For more on why test results and web access can differ, see the connection FAQ.
06 · Settings: Troubleshoot based on symptoms
Turn off the connection first. Confirm that the device can access the internet and complete any login required by the current network. Then check, in order, whether the details are correct, whether the connection can be established, how requests are routed, and whether domains resolve. Change one setting at a time, retest, and record the result. Do not start by reinstalling the app or clearing all configurations; doing so removes context that can help identify the problem.
Subscription import fails, or a server cannot be tested
Check that the full subscription link is valid and that the current network is working, then review the individual server's Type, Host, Port, and authentication fields. Common mistakes when adding a server manually include selecting the wrong protocol, adding a space to a password, or omitting a transport parameter. If the subscription updates but a server cannot connect, treat the subscription address and server connection as separate issues; an update completing successfully does not guarantee that a server is available.
The switch turns off immediately, or reconnects after disconnecting
If the switch turns off immediately, check that the system VPN configuration permission was granted and that another VPN is not using the connection. If the app reconnects after disconnecting, open Settings and check On Demand. You can temporarily turn it off while troubleshooting, then connect manually and test again. On Demand controls when a connection is established; it does not fix a password, server address, or rules. Once a regular connection works, configure it for your network conditions.
Connected, but webpages will not open
First check whether Global Routing is set to Direct by mistake, or whether rules in Config are sending the destination to an unexpected strategy. If Proxy works but Config does not, focus on rule matching and the selected configuration. If both modes fail, continue checking DNS and server details. Do not attribute every access failure to DNS or paste multiple unfamiliar DNS addresses at once.
The DNS location and options may vary with the configuration and platform interface. Note the original values before making changes. If you do not understand how overrides work, keep the current configuration and follow the Settings › DNS manual to check each item. Settings also includes options such as Test Method, On Demand, Diagnostics, Proxy, TCP, and UDP. These serve different purposes and should not all be enabled. For your first setup, address only the options relevant to the current symptom.
Record the conditions before sharing troubleshooting details
If you need to check Diagnostics or share logs, reproduce the issue first and record the local network type, current mode, step where the error occurred, and whether all destinations fail. Hide subscription links, passwords, personal server details, and identifiable browsing records before sharing. Descriptions such as “imports but cannot connect” or “connected and test succeeds, but a specific page will not open” help distinguish issues more than a screenshot of the switch alone. For more cases, see the connection troubleshooting FAQ. For setting definitions, see the settings manual.
