Shadowrocket Setup Guide
Import an existing subscription → choose Global Routing → authorize the connection → verify requests → troubleshoot common failures.
This guide focuses on first-time setup on iPhone and iPad. Start by establishing one connection you can verify, then move on to more complex rules. You don't need to change every setting the first time you open the app. The official screenshots help identify screens and fields, but their layout may change with the app interface. Follow the English labels shown on your device. Don't copy server details from screenshots or assume that a configuration shown there is required.
01 · Add Server: Add or Import
Open Shadowrocket and go to Home. Under SERVER, tap Add Server or use the add button on the screen. First identify what information you have: a subscription link retrieves and maintains a list of servers, while individual server details require you to enter the protocol and authentication settings. These are different input types. Don't enter a subscription URL in the server's Host field.
Have Server Details? Select Type First
After opening Add Server, tap Type and choose the protocol that matches your server details. Enter Host and Port, then fill in the authentication fields shown for that Type. For example, a Shadowsocks setup usually requires Password and Method. Other protocols use different fields, so don't reuse the settings for another protocol.
Enter the server's domain or address in Host and the corresponding port in Port. Copy the authentication fields exactly as provided. Check for extra spaces, line breaks, and capitalization. Enter TLS, transport, server name, and other fields according to your existing configuration; don't guess based on similar-looking names. Save, return to Home, and confirm that the new item appears in the SERVER list. Its presence only confirms that it was saved. Test it in the following steps.
Have a Subscription Link? Select Subscribe
If you have a subscription link from your service provider, set Type to Subscribe on the add screen, enter the complete link in the URL field, add a note to help you identify it, and save. The path and query parameters are part of the URL, so copy the entire link—not just the domain. An account-management page URL usually can't be imported as a subscription. Return to Home, wait for the subscription to load, then check its group and server entries.
If you have a QR code, use Scan QR Code. Check the detected type and content before saving. Import from Cloud JSON is a separate import option; it doesn't mean that any web address will work. Choose the method that matches the format of your information. Don't cycle through unrelated types just to force an import.
After this step, you should see at least one selectable server on Home. If the list is still empty, go to Subscription Import Troubleshooting rather than treating a connection failure with an empty list as a VPN authorization issue. Subscription links may contain account information. Keep them somewhere secure; don't include them in public screenshots, articles, or messages.
02 · Global Routing: Choose a Routing Mode
After saving a server, return to Home and open Global Routing. This setting determines how requests are handled; it is separate from selecting a server in the SERVER list. Decide whether you're testing one server or using existing rules, then choose Config, Proxy, or Direct.
Config: Follow the Active Rules
With Config selected, the client uses the active configuration and its rules to determine where requests go. Open the Config page, confirm which configuration file is selected, and review its rules. In the official screenshots, General, Rule, and Hosts are separate configuration sections. Seeing a file in the list doesn't mean it's selected or active.
For a first-time setup, focus on the rule order, policy names, and final fallback behavior in Rule. For example, DOMAIN-SUFFIX matches domain suffixes, and FINAL handles requests that didn't match earlier rules. If a rule points to DIRECT, the request bypasses the selected proxy server. If it points to REJECT, the request is blocked. Neither outcome alone means the server is unavailable.
Proxy and Direct: Choose the Right Test
Proxy routes requests handled by the proxy through the selected proxy path. It's useful for troubleshooting because it reduces variables from rule-based routing, though behavior still depends on app settings and the system's traffic scope. Direct connects without a proxy, so it can't tell you whether the selected server works. A connected switch doesn't mean every request uses the proxy. Check Global Routing alongside the actual policy.
Note your current routing mode before making changes. If you don't have rules you need to keep, use Proxy to test an individual server, then switch back to Config as needed. If you already have a working configuration, keep the original file and don't overwrite it before trying to restore it. Don't enable HTTPS Decryption or configure additional certificates for a basic connection test; neither is required for this guide. For protocol settings and trade-offs, see the Protocols Guide.
03 · Home: Connect
Return to Home and tap the server you want in the SERVER list. Confirm that the selection indicator is on the right entry. If a subscription group contains several entries, don't mistake the group name for a server. Check Global Routing again to make sure it matches your choice in the previous step, then turn on the switch at the top of the screen.
The first time you connect, the system may ask to add a VPN configuration. Read the system prompt. Once you've confirmed that Shadowrocket initiated the request, allow it as prompted and complete any identity verification required by your device. This authorizes the system to manage a VPN configuration; it does not mean you should enter your device passcode in the server's Password field. If you cancel, the connection won't be established as expected. Try again and complete authorization.
After authorization, return to the app and check whether the status at the top changes from Not Connected and whether the switch stays on. If it immediately disconnects, note any message and move to the troubleshooting steps. Don't rapidly toggle the switch. If the status shows connected, continue to verification. This only confirms that the connection process started; it doesn't prove that the service you need is available.
If another VPN connection is running on your device, first check which configuration is currently handling the system connection. This helps avoid mistaking another connection's status for the result of this test. Keep the network conditions stable during testing; don't switch Wi-Fi, change protocol settings, and change servers at the same time. Keep your existing On Demand settings for the first verification. Configure automatic connection triggers separately after a manual connection works. See the On Demand Reference for details.
04 · Connectivity Test: Verify the Connection
Once the switch stays on, run Connectivity Test from Home and review the result. Identify the test method before interpreting the result: different methods check different network layers and targets. A latency result doesn't confirm that authentication, TLS, and all requests to the target service are working. Likewise, a timeout may be caused by the test target, your current network, or the test method; don't delete the entire configuration based on one result.
Next, open the app or page you actually need and perform a specific action, such as reloading a page. Don't rely on previously cached content. Avoid opening many pages at once, so you can match failed requests to their records. If you're using Config, check which policy should match the target, then compare it with the available connection logs. If the target uses DIRECT, a successful load doesn't prove the proxy path works.
Data: Check Traffic Changes
Open the app's Data section and compare upload and download statistics before and after testing. Use the timestamps in available logs to check for new requests. Traffic changes can help confirm that the client is handling data, but they don't prove that a particular page loaded successfully; background apps, retries, and other requests may also count. Cumulative traffic isn't the same as your service provider's remaining allowance; their measurement scope and billing rules may differ.
Use the same sequence each time you verify a connection: note the server and routing mode, run Connectivity Test, visit an actual target, check the related traffic and connection logs, and record the result. If only one target fails while others work, check that target's rules, DNS, or service status instead of importing the entire subscription again. If all targets fail, check the server details and basic network connection.
05 · Settings: Common Issues
First identify where the failure occurs: no servers in the list means an import issue; a switch that won't stay on points to a connection or system configuration issue; a connected status with failed requests calls for checks of the server, DNS, and routing. Note the network, server, Global Routing mode, and any message shown when the issue occurs before changing anything. Change one variable at a time and repeat step four to see whether it helped.
Subscribe: Import Failed or Server List Is Empty
First confirm that the device can access the internet over a working network. Then check that the subscription link is complete, has no extra spaces, and points to the subscription endpoint. If it returns a login page, error text, or empty content, changing the server Type won't fix it. Check your existing provider's instructions for the link status, supported format, and account validity. Don't post screenshots that show the full subscription URL.
An existing entry doesn't mean the latest update succeeded. Check the result of the latest fetch and review the actual entries in the group. If the import failed, don't delete the only subscription you can use. Keep the current state and find the cause first so you still have a point of comparison.
Update a Subscription: Refresh It, Then Select a Server Again
To refresh an existing subscription, find its group on Home, use the group's update action, and wait for the result before checking the server list. An update may change entry names, counts, or settings, so confirm the selected server again rather than assuming the previous one is still selected. If your provider has changed the subscription URL, update the saved address according to their instructions. Repeatedly refreshing the old URL won't retrieve new content.
Before editing server settings generated by a subscription, remember that the next update may overwrite your changes. If you need to troubleshoot a field, note its original value and why you're changing it. Restore it after testing, or keep a separate test entry if you understand the implications. A subscription maintains server information; Config contains settings and rules. Updating the subscription doesn't update the rules in Config.
Server Connection: Check Each Setting, Not Just Latency
If the server list looks correct but the connection fails, open the entry in Add Server and check Type, Host, Port, authentication fields, transport, and TLS settings in order. The domain and server name fields may serve different purposes; don't swap them just because their values look similar. Make sure the device's system time is accurate, as a significant time difference can affect certificate validation. If you don't have complete server details, ask your existing provider to confirm the fields instead of guessing.
If the connection behaves differently on another network, retest with the same settings and target to distinguish a network path issue from a configuration problem. Test Method in Settings affects how to interpret the result. Diagnostics can show additional available information. Don't disable TCP or UDP just because you see those options; check the configuration instructions to see which transport the protocol requires.
DNS: Connected, but Domain Names Won't Load
DNS resolves domain names to addresses. If the connection stays active but a specific domain won't open, first check whether the failure is consistent and look for related errors in the available logs. With Config, check the active configuration's DNS settings, Hosts entries, and rules for the target. Don't edit a file that isn't active. Note the original settings, then make changes according to the configuration instructions. Avoid layering on settings until you can no longer tell which one is in effect.
A request to a specific target may also fail because a rule matches REJECT, a policy points to an unavailable server, or the service itself is having an issue. Temporarily switching Global Routing to Proxy can help you compare the effect of rules, but restore the previous mode after testing. If Proxy works and Config doesn't, check the configuration and routing first; don't assume you need to delete every rule. For protocol details, see the Shadowrocket Protocols Guide. This page focuses on the checks needed for a first-time setup.
After Troubleshooting: Restore Your Everyday Settings
Once you've confirmed that the target works, restore the Global Routing mode you plan to use and verify it again. If you changed On Demand or Test Method during testing, check each one and restore its intended setting. To disconnect, return to Home, turn off the top switch, and check the status. If it reconnects automatically, review the On Demand conditions instead of repeatedly disconnecting manually.
A successful first setup isn't about changing as many settings as possible. Your server details should be correct, the active configuration clear, connection authorization complete, and the target request consistent with its policy. Keep a brief checklist without passwords, full subscription URLs, or other authentication details. If a problem comes up later, start with the last known working state and what changed; this is usually easier than entering every field again.