Official Guide · First connection
Shadowrocket Setup Guide
From Import to Connection Test
Start with your existing server details, choose how to route traffic, then test access. Follow these five steps for a first-time setup, or jump to the step where you need help if you already have a configuration.
- For iPhone and iPad
- Interface labels remain in English
- Troubleshoot by where the problem occurs
STEP 01 · Add your details
Add Server: Add a server or import a subscription
First, identify what you have: a subscription URL that updates a server list, or the address, port, and credentials for a single server. Each is added differently, so you don't need to do both. Open Shadowrocket, go to Home, and tap the add button in the top-right corner to open Add Server. After saving, return to Home and check the result rather than trying to connect from the edit screen.
Have a subscription URL? Use Subscribe
In Add Server, open Type and choose Subscribe, then enter the full subscription URL in URL. Add a recognizable label, such as “Daily subscription,” but don't include a password or credentials from the URL. Confirm and save, then wait for the subscription to load. Its servers should appear in the Home list. If you see only the subscription name and no servers to select, check the update result first.
When copying a URL, check the beginning, end, and any parameters in the middle. Explanatory text, line breaks, spaces, and punctuation from a chat message are not part of the URL and should not be included. The example below shows the format of a field only; it is not a working subscription and should not be opened.
https://example.com/sub?token=xxxxAfter importing successfully, keep this subscription rather than creating duplicates because the list hasn't refreshed yet. To fetch the server list again, update the existing subscription. Treat the subscription URL like a password: it may contain access credentials. Hide the full URL and its parameters before sharing a screenshot. For details, see subscription update strategies.
Have details for a single server? Enter them by protocol
If you have server details, choose the specified protocol under Type in Add Server, such as Shadowsocks, VMess, VLESS, or Trojan. Then enter the address, port, and required authentication details. Fields vary by protocol; don't reuse a password, UUID, or transport parameter from one protocol for another. Follow the details you were given and the fields in the current form.
Before saving, check the address for extra spaces, make sure the port is complete, and confirm that no characters are missing from the credentials. If the details specify TLS, a transport method, or a server name, enter those as provided. Don't remove parameters just to simplify the form. If you're unsure about a field, ask your provider rather than trying different combinations. Saving only confirms that the form accepted the input; it doesn't guarantee the remote server is reachable.
QR codes and clipboard imports: check the content first
If you have a QR code intended for import, use Scan QR Code and grant camera access if prompted. A QR code may contain a link for one server or a subscription URL. Check the recognized result before saving: confirm the type, label, and address match the details you have. For clipboard imports, make sure you copied the complete server link, not a webpage title or explanatory text. See QR scanning and import instructions for details.
After completing either method, return to Home, find the server you added, and select it. Don't change other settings yet: next, choose how requests should be handled. A subscription provides a server list; a routing configuration determines where traffic goes. Importing a subscription doesn't automatically import or enable a routing configuration that suits your needs.
STEP 02 · Choose how requests are handled
Global Routing: Choose Config, Proxy, or Direct
On Home, open Global Routing. This setting determines how requests are handled; it is separate from choosing a server in the previous step. The three modes are Config / Proxy / Direct. Understand the selected mode before connecting to avoid assuming the server is at fault when access doesn't behave as expected.
| Mode | How it handles requests | When to use it |
|---|---|---|
| Config | Handles requests according to the rules in the currently enabled configuration. | You have a trusted configuration and want different requests handled according to its rules. |
| Proxy | Routes all requests through the proxy. | Briefly test whether the selected server can access sites. |
| Direct | Sends requests directly. | Compare basic network connectivity or check direct access. |
Before using Config, check which file is enabled
To route traffic by rules, open Config and check which configuration file is currently enabled. Make sure it's the one you intend to use. A file appearing in the list doesn't mean it's enabled, and its name alone doesn't tell you what's in it. Rules are checked in their configured order; typically, the first matching rule determines the policy, and FINAL provides a fallback. A request going through DIRECT or REJECT may be the result of a configuration rule, not a server failure.
If you're new to Shadowrocket or haven't checked your rules yet, there's no need to edit a lot of them. Temporarily select Proxy and test an ordinary webpage to confirm the server route works, then switch back to Config and compare. If Proxy works but Config doesn't, check the configuration and matching rules instead of deleting and reimporting your subscription. For an explanation of rules and settings, see Features and settings.
After choosing a mode, return to Home and confirm the server selected is the one you intend to test. If you temporarily change Global Routing, restore your usual setting when you're done. Don't change servers, DNS, routing modes, and configuration all at once to troubleshoot one issue; if access starts working, you won't know which change fixed it.
STEP 03 · Establish the system connection
Home: Connect and allow the VPN configuration
Return to Home and confirm the server is selected and Global Routing is set for your test, then turn on the connection switch. The first time you connect, the system may ask to add a VPN configuration. This permission lets the app use the system's networking capabilities to handle traffic; it does not import a server. Make sure the prompt follows your action, then tap Allow in the system interface and authenticate on your device with your passcode or biometrics.
After granting permission, return to Shadowrocket and check whether the connection switch stays on. If you didn't complete the system prompt, the app may still be disconnected. Complete the prompt and try again once. If the switch turns off immediately, don't keep tapping it or add duplicate server entries. Check for an unanswered system alert and confirm the device allows this VPN connection.
VPN configuration and routing configuration are different
The VPN configuration in system settings links the app to the system's networking capabilities. The file in the app's Config section controls settings such as rules and DNS. Both may be called “configurations,” but they serve different purposes. Removing the system VPN configuration won't fix a rule error, and changing the Config file won't replace system authorization. Identify which layer has the problem before taking action.
If you previously denied permission, try connecting again and watch for the system prompt. If device management restrictions apply or the system says it can't add a VPN configuration, check the device's management requirements; don't assume the subscription has failed. To check the system record, search for VPN in Settings and look for the entry for Shadowrocket. Confirm the target before making changes so you don't affect other network settings in use.
Once permission is granted and the switch stays on, the connection process has started or the system connection is established. That doesn't mean every site is reachable, and a system status indicator can't replace an app-level test. Keep the server and mode unchanged for the next step and test an actual webpage so you can compare results.
STEP 04 · Verify with real requests
Connectivity Test: Check real access after testing
Start with Connectivity Test to check the selected server. The result can show whether a response was received under specific test conditions, but it doesn't guarantee that every domain, protocol, or service request will succeed—or that a webpage used this server. A response time alone doesn't mean setup is complete; test real access and routing too.
Keep Shadowrocket connected, switch to your browser, and refresh an ordinary page you can usually access. Then test the service you actually need. Start with a page that doesn't involve sensitive activity; avoid using payments, form submissions, or large file transfers for your first test. If a page is cached, its old content doesn't prove that a new request succeeded. Try another page on the site to compare.
Record results in three categories
- Server test: Did Connectivity Test get a response? Did every test fail?
- Real access: Does an ordinary webpage load? Is the issue limited to one service?
- Routing: Is Config selected, and does the request use PROXY, DIRECT, or REJECT as expected?
To check a rule, look for the target domain and handling policy in the connection records or logs currently available in the app. Available details vary by interface; base your conclusion only on fields actually shown. Don't assume an unlisted item passed. With Config, a webpage may make requests to multiple domains. If the main page loads but a resource fails, check that request separately rather than looking only at the address bar's domain.
If both the test and webpage work, return to the app and confirm Global Routing is back to your usual setting. Note the server and configuration that worked. Leave On Demand unchanged during initial testing; once manual connections work, configure On Demand separately for your network needs. It starts connections under specified conditions; it won't fill in incorrect server details or fix an invalid subscription.
If only some steps work, don't clear your configuration. Keep the results and use the next section to narrow down the issue. Importing, remote responses, the system connection, DNS, and rules are separate stages; checking each one is usually more effective than starting over.
STEP 05 · Troubleshoot one issue at a time
Shadowrocket connection problems: Troubleshoot by symptom
First, note where the failure occurs: saving, updating, server testing, the connection switch turning off, or webpages failing to load after connecting. Keep your existing working configuration, change one variable at a time, and retest the same page. Don't start by deleting every server, clearing Config, or resetting all network settings; those steps remove useful clues.
Subscription update failed or no servers appear
First, confirm the device can access an ordinary webpage on its current network, then check that the URL in Subscribe is complete. If parameters are missing or the copied text includes line breaks or punctuation, get the full URL from your provider again and replace it. If the details have changed, update the existing subscription instead of adding duplicates. If it still fails, note the exact error shown in the app and ask your provider whether the URL is valid and returns content suitable for import.
A failed subscription update and whether an existing server can connect are separate issues. The list may still be available while a subscription update temporarily fails; an update may also succeed while an individual server is unavailable. Check the current list and selected server first. A successful update doesn't prove that every server works. For details on changes after an update and managing multiple subscriptions, see subscription update instructions.
Connectivity Test failed
For a manually added server, return to Add Server and compare the protocol, address, port, and authentication fields with the details you were given. Then check TLS and transport settings. For an imported server, update the subscription once and confirm the server is still in the list. If only one server fails, compare it with another one you already have. If they all fail, check the current network and any configuration settings they share. Don't repeatedly try guessed passwords or ports.
The connection switch won't stay on
Check whether you completed the system prompt to add a VPN configuration and whether any other system alert is waiting. If the system shows a specific error, resolve it before testing the server. If the issue started after switching networks, turn off the connection, wait for the basic network connection to recover, then turn it back on. Check the result before taking another step. On managed devices, follow the device management requirements; changing server details usually won't resolve a system permission issue.
Test gets a response, but webpages won't load
First check whether the issue affects every page or only a specific domain or app. Keep the server unchanged and switch temporarily from Config to Proxy for comparison. If Proxy works but Config doesn't, check the active configuration's rules and DNS first. If neither works, check the server details, remote server status, and current network. Restore your usual mode after the test; don't leave the temporary setting as your final configuration.
DNS resolves domain names to addresses. A response from the server test doesn't guarantee that every domain a webpage needs will resolve correctly. Check that the DNS settings in the current Config come from a configuration you've verified, and avoid changing multiple DNS options at once. For a step-by-step diagnosis, see DNS troubleshooting when webpages won't load but latency looks normal.
Before reporting an issue, gather only the essential details
Note your device type, current network, Global Routing mode, the step where the issue occurs, and the exact error text. Mention whether only a specific destination is affected. Don't share your full subscription URL, password, UUID, or other credentials. Check logs and screenshots for sensitive details and redact them before sharing. “It works in Proxy, but this domain fails in Config” is more helpful than “It won't connect.”
To review an earlier step, return to adding or importing, choosing Global Routing, or allowing the connection. Resume from the first step that didn't work.