This guide is for people who have just installed Shadowrocket and already have a provider and configuration, but haven’t connected for the first time yet. Using the iPhone / iPad interface as an example, it distinguishes system VPN permission from server configuration, explains the Home screen’s connection toggle, routing modes, test options, and server list, then walks through a connection check in order.
Before you start: installation, configuration, and the three main screens
Installing the Shadowrocket client and configuring a connection are separate steps. The iPhone / iPad version is available on the App Store for a one-time $2.99 purchase. Check the App Store page for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. See the download guide for options on each platform.
Buying the client does not include a connection plan. This guide assumes you already have a provider and subscription. This site does not provide, sell, or recommend servers or subscriptions. An empty list after opening the app doesn’t mean installation failed; it means you haven’t imported a usable server configuration yet.
- Home: Choose a server, start or stop the connection, select Global Routing, and run Connectivity Test.
- Config: Manage rule configuration files. Importing a server subscription doesn’t automatically select a suitable rules file.
- Settings: Manage options such as DNS and On Demand. When getting started, leave unfamiliar settings unchanged and avoid changing several options at once.
Allow VPN configuration: granting permission for the system network extension
During initial setup, the system asks for permission to let Shadowrocket add a VPN configuration. This prompt may appear the first time you turn on the connection; it doesn’t necessarily appear as soon as you open Home. Permission lets the app create a system-managed network tunnel so eligible device traffic can pass through the client. It does not fill in a server address, account, or subscription for you.
The system warning that network traffic may be filtered or monitored is a standard VPN permission notice. Decide whether to proceed based on whether you installed the app yourself and intend to use a configuration you already have. On managed devices, VPN configurations may also be restricted by organizational policies.
-
Confirm the configuration
Go to Home, import and select your server, then check its name and protocol. Avoid repeatedly toggling the connection when the list is empty.
-
Start the connection
Tap the connection toggle next to Not Connected at the top of Home. If the required VPN configuration hasn’t been saved by the system, you’ll be taken through the permission flow.
-
Allow the configuration
When the system asks to add a VPN configuration, choose Allow and confirm using your device passcode or the required authentication method.
-
Return and check
Go back to Home, check the connection status, then test a webpage. Granting permission only allows the tunnel to start; it doesn’t confirm that the remote service is available.
If you previously chose Don’t Allow, return to Home and try connecting again, watching for the system prompt. Don’t delete all network settings as a substitute for troubleshooting VPN permission. If your device is managed by a school or employer, check its management policies first.
Not Connected: check connection status and real-world access separately
Not Connected at the top of Home means there isn’t an active client connection. When you turn it on, the app attempts to start a tunnel using the current configuration. A change in connection status tells you whether the local tunnel is running; by itself, it doesn’t confirm server authentication, DNS resolution, or access to the destination website.
Check connection status separately from access results
Still shows Not Connected
- Check that VPN permission was granted.
- Make sure a valid server is selected on Home.
- Check whether another VPN connection is competing for the system tunnel.
Connected, but can’t access websites
- Check the current Global Routing mode.
- Check that the service is available and the authentication details are complete.
- Compare the Connectivity Test result with the webpage access result.
First check whether the tunnel started, then check whether requests succeed. Don’t draw conclusions based only on the toggle or a single latency result.
If the connection turns back on after you manually disconnect, check Settings → On Demand. This feature starts connections automatically when its enabled conditions are met; it doesn’t automatically test server latency. For initial troubleshooting, leave On Demand off until you’ve completed a manual connection test, then enable it if needed. Existing configurations or migrated settings may change the current value, so check what’s actually shown rather than assuming a recommended setting is the default.
Global Routing: choose a mode, then check the rules
Home → Global Routing determines how requests are routed. This is separate from server selection: routing determines how traffic is handled, while server selection determines which server to use when a request needs a proxy. The comparison below covers Shadowrocket’s four routing modes. Actual behavior also depends on protocol support, app settings, and system network restrictions.
Config
ConfigRequests are matched against the rules in the currently enabled configuration, with results such as PROXY, DIRECT, or REJECT. Config is recommended for everyday use when you have a working rules file; it doesn’t mean that every unmatched request goes DIRECT.
Use when: You’ve imported and checked a rules file and want to route traffic by domain or IP address.
Proxy
Routes traffic handled by the client through the proxy mode, instead of following the usual rules in Config. This is useful for temporarily ruling out routing rules as the cause of a problem, but it doesn’t guarantee that every app and protocol can connect through the selected server.
Use when: You want to temporarily check whether routing rules are affecting a request to the same destination.
Direct
Routes traffic handled by the client directly, without using the selected remote proxy server. Direct does not turn off the connection toggle; the system tunnel may still be running.
Use when: You want to compare with direct access over your current network.
Scene
Uses the routing setup for the selected Scene. You need to understand and configure the relevant Scene first. This isn’t a button for automatically choosing the fastest server, and there’s no need to select it if you haven’t configured a Scene.
Use when: You’ve configured a Scene and want to switch routing according to its settings.
In Config, rules are generally checked from top to bottom, and the policy for the first matching rule is applied. DOMAIN-SUFFIX matches domain suffixes, GEOIP matches IP addresses by geographic classification, IP-CIDR matches IP ranges, and FINAL handles requests that didn’t match earlier rules. The snippet below illustrates how the rules work; it isn’t a complete importable configuration:
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXYIn this example, requests that don’t match the first three rules use PROXY through FINAL, rather than going DIRECT by default. For details, see the rules section of the options manual. If you don’t have a working rules file, check the configuration source and contents before using Config as your everyday routing mode.
Connectivity Test: a test result doesn’t verify the entire connection
Home → Connectivity Test checks connectivity for servers in the list and displays the results. The test method and target affect the outcome. A test value can’t be directly converted into download speed, and it doesn’t prove that every website will load.
| What you see | What it tells you | What to do next |
|---|---|---|
| The test shows a latency value | The test path received a response | Turn on the connection, then visit a known working webpage |
| The test times out | No response was received within the test’s time limit | Check the server address, port, network, and test method |
| Latency looks normal, but webpages keep loading | A successful test doesn’t cover every step involved in real requests | Check DNS, authentication, Global Routing, and the rule that matched |
| Wi-Fi works, but cellular data doesn’t | The result depends on the network you’re connected to | Keep the configuration unchanged and record test and access results on both networks |
Change only one variable at a time while troubleshooting. For example, keep the same server, Global Routing mode, and destination website, and switch only between Wi-Fi and cellular data. Don’t change servers, DNS, and subscriptions all at once, or it’ll be difficult to tell which change affected the result.
SERVER list: importing, selecting, and updating are separate actions
The SERVER section on Home shows the servers you can select. A server name is just a label, not proof that it works. Import a server, select it, and then start the connection. Editing a server’s settings doesn’t automatically make it the currently selected server.
- Add a server manually: Go to Home → tap “+” in the top-right corner → Add Server. Choose a Type based on your existing service details, then enter the address, port, and authentication details. The port must match the server settings; don’t assume it should always be
443just because the connection uses encryption. - Import a subscription: Go to Home → tap “+” in the top-right corner → Type → Subscribe. Enter a subscription URL you already have, save it, and wait for the results.
https://example.com/sub?token=xxxxis only a format example and can’t be used to connect. - Select a server: Return to Home, expand the relevant group, and tap the server you want to use. Confirm that it’s selected before using the connection toggle at the top.
- Update a subscription: Update the subscription group from Home. If the interface supports pull-to-refresh, pull down to refresh. After updating, check that your selected server is still there. A successful update doesn’t mean the connection works.
Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are different protocols with different required fields. Enter the details provided by your service; don’t keep only the server address and port and then switch Type at random. Manually edited subscription entries may be overwritten by the next update. Before making changes you need to keep, check how the configuration is managed.
Tokens in subscription URLs, server passwords, and keys are sensitive. Hide these details in troubleshooting screenshots, but leave the protocol type, error message, and steps taken visible. Don’t post a complete subscription URL in a public discussion.
First connection checklist: from Home to a webpage
After importing your configuration, run through these checks in order. Don’t treat “VPN permission granted,” “test returned a latency,” and “toggle is on” as the same result: they refer to system permission, the test path, and tunnel status, respectively.
- Check the inputs: A server is listed on Home, the right entry is selected, and the protocol and authentication details match the service information you already have.
- Check routing: Make sure the Global Routing mode on Home matches your test. If you’re using Config, confirm that the expected rules file is enabled on the Config screen.
- Check permission: Turn on the connection and complete the system permission prompt. If it won’t connect, address the system prompt first rather than changing DNS immediately.
- Check access: Run Connectivity Test, then open the destination webpage. If the results differ, continue troubleshooting DNS, rules, and authentication.
- Check automatic connections: Once manual use works, go to Settings → On Demand to set automatic connection conditions if needed.
- Record what happens: Note the network, routing mode, test result, and error message. Change one setting at a time so you can compare results and revert changes.
For step-by-step instructions on adding a server, see Quick Start. If you’re connected but can’t access websites, see connection troubleshooting. When describing a problem, specify the step where it fails; that’s more useful than simply saying “it won’t connect.”
Get Shadowrocket and follow the first-time setup steps
The iPhone / iPad version costs $2.99 as a one-time App Store purchase. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free. The download guide lists options by device, and Quick Start explains how to import a configuration you already have.