OFFICIAL MANUAL / GETTING STARTED
Shadowrocket Setup Guide: Import and Connect
Import your existing connection details, choose a routing mode, then test with a real request after connecting. This guide follows the first-use workflow and is intended for iPhone and iPad.
If this is your first time, follow the steps in order. If you're connected but having trouble accessing something, jump to testing and troubleshooting. Interface labels remain in English; exact locations and available options may vary by app version.
STEP 01 / ADD SERVER
Add a Server or Import an Existing Subscription
First, identify what you have: a subscription URL that returns a list of servers, or the complete connection details for a single server. Both use the same Add Server entry point, but the fields differ. A subscription URL is not a regular website or account management page. If you're unsure what it's for, ask the provider who gave it to you instead of trying random URL changes.
Have a Subscription URL? Choose Subscribe
Open Shadowrocket and go to Home. Tap the plus button in the upper-right corner to open Add Server. Tap the type selector, choose Subscribe, and paste your subscription URL into URL. If you want to add a note, use a name that helps you recognize it; the note only identifies the source and does not change how the server connects.
After pasting, check that the URL is complete from beginning to end. Line breaks in a message, extra spaces copied with the text, or missing query parameters can prevent the URL from being read. The credentials in a subscription URL are often access credentials: keep them intact, don't remove any part, and never post the full URL in a public forum. When you're ready, use the page's save control, return to Home, and wait for the subscription to load.
After it loads, check that the SERVER list contains the servers included in the subscription—not just a subscription name. If you see a source entry but no selectable servers, check the update result and any error message. Don't turn on the connection before the server details have loaded. Routing settings can't make up for missing server details.
Have Details for a Single Server? Choose the Matching Type
If you have a server share link, copy the complete link and follow the import prompt shown in the app. If you have a QR code, use Scan QR Code to read it. After importing, check the type and address; a successful import doesn't guarantee that the details are correct. Keep credentials in QR codes private, too.
To enter details manually, choose the matching type in Add Server, such as Shadowsocks, VMess, or Trojan, then enter the address, port, and credentials in the corresponding fields. Required fields differ by protocol. Match the encryption, transport, and TLS settings to the original details; don't apply the setup for one protocol to another.
After saving, return to Home and select the server you want to use under SERVER. Start with one verified entry and organize names or groups later. At this point, you've added the details to the app, but you haven't connected yet. Next, choose how those details will be used for requests.
STEP 02 / GLOBAL ROUTING
Choose One of the Three Global Routing Modes
Return to Home, tap Global Routing, and choose Config, Proxy, or Direct based on your needs. This controls how the app handles requests; it doesn't select a different server. After changing the mode, return to Home and check which mode is shown before continuing. Keep server selection and routing mode distinct.
Config: Handle Requests According to the Current Configuration
Choose Config when you want rules to determine how requests are handled. Open the app's Config page and confirm that the configuration file you need is present and selected. Seeing a file in the list doesn't mean it's the active configuration; check its selected state in the app. The rules, policies, and related settings in the file determine how requests are routed in this mode.
For example, rules may use DOMAIN-SUFFIX to match domain suffixes and IP-CIDR to match address ranges, with FINAL handling requests that haven't matched earlier rules. You don't need to edit these rules when getting started, but keep in mind that a working server doesn't mean every rule behaves as expected. Policies referenced in the configuration must also be valid; checking rule keywords alone isn't enough.
Proxy: Check the Proxy Route
To check the current proxy route on its own, temporarily choose Proxy, confirm that the server you want to test is selected in SERVER, then connect and access the same test target. This helps you distinguish whether the server connection works from whether a rule matches the expected policy. Don't assume this mode handles every app or type of traffic in the same way.
If the target is accessible in Proxy but not in Config, check the active configuration, rule order, and final policy before removing the server. After troubleshooting, switch back to the mode you need. Don't leave a temporary diagnostic setting in place unless you intend to use it.
Direct: Check the Direct Connection
Direct uses a direct connection and doesn't route the corresponding requests through the selected proxy server. It can help you check access over your underlying network, but it doesn't show that the proxy is working. Even if the system shows a VPN status in this mode, that doesn't mean requests are using the proxy server. System connection status and the policy applied to a request are separate things.
Before continuing, check two things: whether the current Global Routing mode suits your purpose, and, if you've chosen Config, whether the configuration is selected. For details on rule syntax and configuration file sections, see the complete guide. This page focuses on completing a connection you can test.
STEP 03 / VPN PERMISSION
Turn on the Connection and Authorize the VPN Configuration
Return to Home. Before turning on the connection switch, check the selected server under SERVER and the current Global Routing mode. If the page shows Not Connected, the corresponding connection hasn't been established. Tap the connection switch and follow the prompts in the app and system.
When the System First Prompts You to Add a VPN Configuration
The first connection may trigger a system prompt to add a VPN configuration. Check the app name and permission details in the prompt. Once you've confirmed that you're setting up Shadowrocket, allow it as required by the system and complete device authentication. This permission lets the app create the required system VPN configuration; it won't create a server, fix a subscription URL, or confirm that your connection details work.
After authorizing, return to Shadowrocket and check whether the connection switch and status have changed. If the system denies the request, try connecting again from the app and follow the prompts shown. If needed, check the corresponding VPN configuration in system settings. Don't delete every VPN configuration on your device to troubleshoot, especially if any are used for work or device management.
System Connection Status Doesn't Confirm Server Availability
A VPN indicator or a switch that stays on means the corresponding system connection is active, but server authentication, DNS resolution, or access to a destination can still fail. If the switch turns off immediately or an error appears, address the authorization, current configuration, or error shown in the app first. Repeatedly refreshing a browser can mix several different issues together.
For your first test, keep the connection manual and avoid changing automatic connection settings such as On Demand at the same time. Automatic triggers affect when a connection resumes, so they're best left alone until the basic connection is confirmed. You can explore these settings later based on how you use the app.
When you leave the app to test access, keep the current server and routing mode selected. If you need to change an important setting, disconnect first, then edit and save it before reconnecting. This makes it clear which settings were used for each test. The next question isn't whether the switch is on, but whether the request to your target actually succeeds.
STEP 04 / CONNECTIVITY TEST
Test Connectivity and Real-World Requests
Check three things together: the app or server test result, the system connection status, and whether you can access the actual target. A successful test doesn't confirm access in every app, and a failed request to one target doesn't mean all your connection details are unusable.
Run Connectivity Test, Then Try the Actual Target
In Home, find Connectivity Test and run the test using the controls available in the current interface. Make sure it's testing the item you want to check. If the app offers different test methods, use the same method when comparing results; results from different test conditions aren't directly comparable.
Once the test responds, open a browser or the app you want to use and load a specific target page. Don't rely on content that's already open, as it may be cached. Verify one target first, then test others. Opening many pages at once makes it harder to match requests to their results and identify which change made a difference.
Match Requests to Policies in Data
Return to Shadowrocket, open Data, and find the request that matches the time and target of your last test. If the details show the matched rule, policy, or connection, use that information to see which route the request took. With Config, check whether the matched rule is the one you expected instead of drawing conclusions from a change in total traffic.
For example, if a request should use a proxy but its entry shows DIRECT, check the rule match and order. If the policy is correct but the connection fails, check the server referenced by that policy and its settings. A request appearing in the log only means the app observed the activity; it doesn't necessarily mean the remote server returned the complete content.
Make the Test Repeatable
Confirm that the target works as expected—for example, reload a page or check that the app retrieves the content you need. Note the mode, selected server, and test target. There's no need to save the full subscription URL or credentials. If an issue comes up later, test again under the same conditions so the results can be compared.
If Connectivity Test succeeds but access to the target fails, continue to the next section and check DNS resolution, rules, and server settings one at a time. If access works but a particular test fails, first check the test method and target. Don't change a working configuration just to make every test result match.
STEP 05 / CHECK ONE CHANGE AT A TIME
Find the Cause and Change One Thing at a Time
Start troubleshooting at the earliest step that failed. Note what happened, change just one condition, then repeat the same test. If you update a subscription, switch servers, edit rules, and change networks all at once, you won't know what fixed the issue—and you'll have less to go on next time.
Subscription Won't Load or Entries Look Different After an Update
Disconnect first and confirm that your underlying network can access pages you normally use. Then check that the subscription URL is complete and still valid, along with any update error shown by the app. If the subscription requires authentication or the service details have changed, check with your existing provider. Don't edit credentials in the URL or try connection details from an unknown source just because loading failed.
Before updating, note the name of the selected entry. If it was removed or renamed, select an available server from the updated list. A subscription update changes server details; it doesn't necessarily update rules or policy references in the current Config.
Connection Switch Won't Stay On or System Configuration Error
Read the error shown in the app first, confirm that you've authorized the initial VPN configuration, then check the corresponding item in system VPN settings. If another configuration that affects the system VPN is enabled, check which connection is active and try again with fewer variables. Follow device management requirements if restrictions apply; don't remove managed configurations without checking first.
If you need to recreate Shadowrocket's system VPN configuration, keep your server and configuration details in the app and change only the corresponding system item. The system VPN configuration and the app's server list are separate. Deleting a system connection won't fix server details.
Connected, but the Target Won't Load
First, make sure you haven't left Direct selected for troubleshooting, then check the selected server. For manually entered entries, compare the type, port, credentials, and transport settings one by one, paying close attention to fields that may have been missed when copying. Don't disable TLS verification as a substitute for checking the details. Investigate certificate errors using the original connection details and the error shown in the app.
Next, compare the same target in Proxy and Config. If it works in the former but not the latter, check that the configuration file is selected, the rule order, and the referenced policy. If both fail, check the server, underlying network, and target. When you're done comparing, restore the mode you normally need.
Some Targets Fail, or Issues Start After Switching Networks
For a failing target, find its request in Data and check DNS resolution, the matched rule, and any connection errors. A page may request content from other domains, so don't assume every request follows the same route just because the main domain does. Identify the failing request before deciding whether to change a rule.
If the issue occurs only on a particular Wi-Fi or mobile data network, keep the server and configuration unchanged and test on the other network. After switching, disconnect and reconnect manually, then check whether the error returns. This comparison can help narrow down the cause, but it doesn't prove that a particular network is at fault or guarantee long-term server availability.
After completing these steps, you should be able to distinguish importing connection details, establishing the system connection, and testing actual requests. To learn about On Demand, configuration file sections, and routine maintenance, continue to the complete guide for beginners and advanced users. To review the basics, return to the add and import steps in this guide.