This guide uses an iPhone or iPad and is for readers who have installed Shadowrocket and are ready to use connection details they already have. Understand the difference between system permission and server selection, then use the Home screen status, test results, and actual access to pinpoint where your first connection is getting stuck.
First connection: Allow VPN configuration
The system prompt may not appear as soon as you open the app. To trigger it, start a connection from Home. If the device hasn’t saved the VPN configuration Shadowrocket needs, iOS will ask you to approve adding it. This VPN configuration is an operating system setting used to start the network tunnel. It is not a routing rules file in Config, and it won’t populate server details automatically.
Open Home
Launch Shadowrocket and tap Home at the bottom. First, check whether SERVER contains any entries. An empty list means there’s no server to select; repeatedly toggling the connection switch won’t add one.
Add existing connection details
If you already have a subscription URL, tap “+” in the top-right corner of Home to open the add screen. Set Type to Subscribe, enter the URL, and save. For individual server details, select the protocol specified in your information and fill in each field. A server address is not a subscription URL. Don’t post URLs containing credentials on public pages.
Select a server and connect
Return to Home and tap an available entry under SERVER. Make sure the selection indicator is on the intended entry, then toggle the switch on the Not Connected row. Selecting a server and starting the tunnel are separate actions; a selection indicator doesn’t mean you’re connected.
Approve the system prompt
When the system asks to add a VPN configuration, confirm that the request is from the Shadowrocket app you just used, then tap Allow. If asked to authenticate, follow the prompts on your device. Return to Home and check the connection status. If it still shows Not Connected, make sure authorization is complete and try turning on the switch again.
Home screen overview: status, mode, tests, and servers
- Not Connected / Connected: Shows the status of the device’s tunnel. Connected means the tunnel is running, but it doesn’t confirm that the selected server can forward traffic or that a particular website is using the proxy. If the switch turns on and quickly returns to Not Connected, check system authorization and configuration status before changing routing rules.
- Global Routing: Determines how connections handled by Shadowrocket are routed. It doesn’t add servers. The selected entry under SERVER and the route actually used to reach a website are not the same thing, even after you change modes.
- Connectivity Test: Starts a connection test. A result in milliseconds means that test received a response; it doesn’t measure download speed or replace checking access to the intended website. A timeout only means this test didn’t return in time—it doesn’t, by itself, prove that your credentials are invalid.
- SERVER: Lists the servers you’ve added. After updating a subscription, check that the entries are still there and that the intended one is selected. If entries have similar names, compare them with the address and port in your existing connection details; there’s no need to change parameters just to tell them apart.
Global Routing: choosing between the four modes
For everyday use with working routing rules, select Config. For troubleshooting, temporarily switch modes and compare results on the same network and destination. When you’re done, restore your usual mode so a temporary setting doesn’t become your everyday setup.
Config
RecommendedMatches connections against the rules in the currently enabled configuration. A match can result in actions such as PROXY, DIRECT, or REJECT. For connections that don’t match an earlier rule, check how FINAL is handled in the configuration.
Best for: Keeping different routing policies for different destinations when you already have routing rules configured.
Proxy
Routes connections handled by this mode through the proxy instead of choosing an outbound route rule by rule in Config. If a destination is reachable in Proxy mode but not in Config mode, first check which rule it matched.
Best for: Temporarily checking whether a destination is reachable through the proxy.
Direct
Routes connections handled by this mode directly, without using the selected proxy server. Direct doesn’t turn off the Home switch; the tunnel may still show Connected.
Best for: Checking whether a destination is reachable directly while the tunnel remains on.
Scene
Chooses a routing method based on your configured scenes. Network conditions and scene settings affect the route used. If you haven’t configured scenes yet, use a fixed mode for your first connection check.
Best for: Switching routing methods based on network conditions when you’ve already set up scenes.
Config vs. Settings → On Demand
Config answers, “Which route should this destination take once connected?” On Demand answers, “Under what conditions should a connection start?” If you manually disconnect and then see Connected again after switching networks, check On Demand before deleting a server or changing FINAL.
Config routing example
- Open
- Tap Config at the bottom and check which configuration is enabled
- Domain rule
DOMAIN-SUFFIX,example.com,PROXY- Fallback rule
FINAL,DIRECT
These two lines illustrate checking a domain rule before the fallback. They’re not a complete configuration, and you don’t need to replace your existing rules to make your first connection.
Automatic connection with On Demand
- Open
- In the app, tap Settings → On Demand
- Check
- Whether it’s enabled and whether the current Wi-Fi or cellular network meets the conditions you set
- First connection check
- Turn off automatic triggers first, then use the Home switch to connect and disconnect manually once
After manual connection works, restore the conditions you need and check the status on the corresponding network.
First connection failed: troubleshoot based on what you see
Change one condition at a time. Start by staying on either Wi-Fi or cellular, then note the Home status, selected SERVER, Global Routing mode, and Connectivity Test result. Retry the same destination for comparison, and don’t mistake an old page still displayed in your browser for a successful connection.
| Symptom | What to check next |
|---|---|
| SERVER is empty | First confirm that your existing connection details were saved. If you use a subscription, check whether updating it actually added entries. Troubleshoot the import first; don’t change Global Routing yet. |
| The switch returns to Not Connected | First check that system authorization is complete and that the corresponding configuration appears in the system’s VPN list. If another VPN is running on the device, check which one is active. Don’t delete system configurations unless you know what they’re for. |
| Connected, but the test times out | Keep the same server and mode, then test again on another available network. If the result changes with the network, check whether that network requires a sign-in or restricts access. If both tests time out, verify that the address, port, and protocol match your original connection details. |
| The test returns a result, but the destination won’t load | The test destination may differ from the one you’re trying to access. Keep the server and network unchanged, then compare access in Config and Proxy modes. If only Config fails, check whether another rule matches the destination domain first and what action FINAL takes when no earlier rule matches. |
After troubleshooting, restore your usual Global Routing mode and re-enable On Demand if needed. If you need to document the issue, note the conditions and error message. Hide subscription URLs, authentication fields, and other connection credentials in screenshots and text.