To get started with Shadowrocket, import your existing service details, select a server, turn on the connection, allow the system to add a VPN configuration, and verify access. This guide uses the Home screen on iPhone and iPad as its reference. It explains the difference between the connection switch, routing modes, server tests, and configuration files—useful if you’ve just installed the app, see Not Connected, or aren’t sure the connection is working.
Before You Start: Choose How to Get the App and Gather Your Service Details
Installing the app, getting server details, and allowing the system to establish a VPN connection are separate steps. An empty SERVER list after opening the app doesn’t mean installation failed; first, import your existing service details. Get a subscription URL from your service provider. Purchasing the app does not include a service plan.
Shadowrocket is available on multiple platforms. The iPhone / iPad app is a one-time $2.99 purchase on the App Store; the developer is Shadow Launch Technology Limited. Check the App Store listing for system requirements. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free. See the download page for all platforms for instructions on getting and installing each version. The system authorization steps below apply to iPhone / iPad and should not be followed as-is in the system settings on computers or Android devices.
Use Home to select a server, choose a routing mode, and control the connection; Config to manage configuration files and rules; and Settings to adjust app behavior. For your first session, complete the basic flow on Home without changing DNS, rules, or On Demand at the same time. Changing several settings at once makes it harder to identify the cause of later issues.
First Connection: Import, Select a Server, and Grant VPN Access
Once you have a subscription URL, check that you copied it in full. Subscription URLs are usually HTTPS addresses and may include account-identifying parameters; don’t post the complete URL in public forums. The address below is an example for recognizing the format only; it won’t provide a service: https://example.com/sub?token=xxxx.
-
Add a Subscription
Go to Home → tap “+” in the upper-right corner → Type → Subscribe. Paste the subscription URL from your service provider into URL, review it, and save. Don’t enter a subscription URL as the Address for an individual server.
-
Check the List
Return to Home and wait for the subscription to load. To refresh it, use its update action; if the list supports pull-to-refresh, you can also pull down. Expand the group and confirm that server entries appear—don’t mistake the subscription name alone for a loaded server list.
-
Select a Server
Tap the server you want to use in the SERVER list and confirm the selection indicator changes. If you use Config, also check that the active configuration references this server or the relevant policy group.
-
Turn On the Connection
Turn on the connection switch at the top of Home. The first time you connect, the system asks for permission to add a VPN configuration. Confirm that the request was triggered by your action, tap Allow, and complete device authentication as prompted.
-
Verify Access
Return to Home to check the connection status, then open a website or app you use and make a new request. Consider both Connectivity Test and actual access; an enabled switch alone doesn’t confirm that the server and rules are working correctly.
Not Connected: What the Connection Switch Means
Not Connected at the top of Home means the app’s VPN connection is not currently established. This status alone doesn’t mean the subscription has expired or the server password is wrong. The switch may be off, system authorization may be incomplete, or the connection may have failed to start. First determine whether the switch won’t stay on or the connection stays on but access fails.
“Add VPN Configuration” is system authorization—not a purchase confirmation or a subscription import. After authorization, the corresponding connection appears in the VPN list in system settings. You can usually find it under Settings → General → VPN & Device Management → VPN, though names and menu paths vary by system version. Installing a configuration profile is not a substitute for this step.
- Denied the request: Return to Shadowrocket and try turning on the connection again, then follow the system prompts to grant access. If the prompt doesn’t appear again, first check existing entries and the current status in the system VPN settings.
- The switch turns off immediately: Confirm that system authorization is complete and a server is selected, then check the error message shown in the app. Toggling the switch repeatedly won’t fix incorrect server settings.
- Connected, but websites won’t load: Check the server test, Global Routing, and Config. Don’t delete the system VPN configuration right away.
- Another VPN is connected in system settings: Disconnect it before testing to avoid mistaking a switch between connections for Shadowrocket disconnecting on its own.
Consider recreating the VPN entry only if you’ve confirmed the system entry is faulty and have saved your configuration and service details. Deleting the entry affects connection authorization; it won’t fix the subscription URL, account validity, or server-side settings.
Global Routing: Config, Proxy, Direct, and Scene
Global Routing determines the routing mode used by the connection. It isn’t a protocol selector or a server speed test. When troubleshooting for the first time, note the original setting, change one mode at a time, and test with a newly opened page or connection. Existing long-lived connections may not reflect the new setting immediately.
Config
ConfigRoutes traffic according to the rules and policies in the active configuration. Matching a rule doesn’t necessarily send traffic through a proxy; the result depends on the policy the rule points to. Unmatched traffic also depends on fallback settings such as FINAL. Use this mode when you’ve checked and understand the active configuration.
Best for: Using rule-based routing with a working configuration
Proxy
Routes connections handled by the app through a proxy. This can help you temporarily rule out the effects of ordinary routing rules. It doesn’t guarantee that a server is available or bypass restrictions imposed by the server itself.
Best for: Comparing server behavior and isolating configuration routing issues
Direct
Uses a direct connection without forwarding traffic through a remote proxy server. Switching to Direct doesn’t turn off the VPN switch at the top. Check system connection status separately from whether a remote proxy is forwarding traffic.
Best for: Checking whether the local network can reach a destination
Scene
Uses the routing choice set for the active scene conditions. First check the configured scene conditions and their corresponding actions. If no scenes are explicitly configured, don’t use this mode as the baseline for troubleshooting your first connection.
Best for: Users with configured and tested scene-based routing
If the same server works in Proxy but not in Config, check the active configuration’s rules, policy group selection, and DNS settings before reimporting the subscription. If Proxy also fails, check the local network, server settings, and service status. This comparison helps narrow down the issue, but a single test can’t pinpoint the cause by itself.
Connectivity Test and SERVER: Test Results Don’t Guarantee Access
SERVER is the list of server entries. An entry name is just a label for identification; it doesn’t guarantee a location, speed, or availability. Actual connections depend on fields such as address, port, protocol, and authentication. When entering details manually, use the port provided by your service provider—don’t change every port to 443 just because TLS is in use.
Connectivity Test runs a connectivity check. Its result depends on the selected method and target; it doesn’t mean an actual app or website request succeeded. A result in milliseconds indicates that the corresponding probe returned a response. It isn’t download bandwidth and doesn’t guarantee access to every website. If a test times out, also check whether its target is reachable.
| What You See | What You Can Conclude | What to Do Next |
|---|---|---|
| SERVER list is empty | No server entries are available to select | Check the subscription URL, update errors, and returned content; import the servers first |
| Test returns a delay, but access fails | The corresponding probe succeeded; the service connection still needs checking | Check authentication, TLS, DNS, and Global Routing, then retry with a new request |
| One entry times out while others return results | The issue may be specific to that entry or its test route | Update the existing subscription and check that entry’s settings and service status |
| All entries time out | The local network, test target, or shared configuration may be involved | First check direct access on the local network, then test on another network. Avoid changing several settings at once. |
Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are different protocols. Don’t change Type while keeping fields from another protocol. If your service provider has changed the address or authentication details, update the subscription first, then check whether the selected entry is still the same one. A share link usually imports a single connection, while a subscription URL retrieves and updates a set of details; don’t confuse their purposes.
Config and Settings: Check Only What You Need at First
The active file in Config affects routing when Global Routing is set to Config. Rules are usually evaluated in order, so a broad rule near the top may take precedence over a more specific rule below it. Save a recoverable copy before editing, and avoid replacing all your rules and DNS settings before you’ve verified the server.
Rule Syntax Example
- DOMAIN-SUFFIX
DOMAIN-SUFFIX,example.com,PROXY- GEOIP
GEOIP,CN,DIRECT- IP-CIDR
IP-CIDR,192.0.2.0/24,DIRECT- FINAL
FINAL,PROXY
For syntax explanation only; the domains and network ranges are examples. PROXY must refer to a valid policy in the active configuration. Check the rules from top to bottom, with FINAL as the last fallback.
On Demand Checklist
- Setting
- Settings → On Demand
- Purpose
- Requests a connection or disconnection based on configured conditions
- First Test
- Connect manually first; don’t add automatic triggers yet
- Reconnect After Disconnecting
- Check whether any automatic connection conditions are still active
On Demand controls automatic connection behavior; it does not choose the forwarding policy for a rule in Config.
The DOMAIN-SUFFIX example above matches domain suffixes, IP-CIDR matches IP ranges, GEOIP uses geographic IP data, and FINAL determines the route for connections that didn’t match earlier rules. PROXY isn’t a server address or a custom name that works in every configuration; available policies depend on the active configuration.
On Demand and Scene are different, too: On Demand controls when to establish or disconnect the VPN automatically, while Scene is for routing based on conditions. Keep triggers simple at first. Once a manual connection is stable, add conditions one at a time for different network environments and test the results when switching between Wi-Fi and cellular data.
First-Use Checklist: Test the Connection, Routing, and Disconnect Behavior
A complete test should verify three things: the connection works, traffic is routed as expected, and the connection disconnects as expected. A VPN indicator, a Connectivity Test result in milliseconds, or a cached browser page alone can’t confirm all three. Complete these checks before changing advanced settings.
- Import complete: The subscription group on Home contains server entries, and the selected entry is clear. Don’t confuse updating a subscription with switching Config.
- Authorization complete: After you turn on the connection, the system no longer waits for authorization, and the connected status stays on in Home.
- Requests work: Make new requests to at least one website you use and one app. If needed, check the connection log to see where traffic went.
- Routing mode is as expected: If you used Proxy or Direct temporarily for troubleshooting, restore the previously verified mode to avoid leaving a test setting in place.
- Disconnect behavior is clear: If the connection turns back on automatically after you switch it off, check Settings → On Demand and the on-demand connection status in system VPN settings.
- Your information is protected: Keep a copy of your configuration. When reporting an issue, hide subscription parameters, passwords, UUIDs, private keys, and other authentication details.
When documenting an issue, include the device network, Global Routing selection, server protocol, test results, and actual access behavior; this is more useful than simply saying “it won’t connect.” For an expired subscription, changed authentication details, or an unavailable server, contact your service provider with the error details and credentials redacted. For app settings and routing concepts, see the setup guide and glossary.
Get Shadowrocket and Continue Setup
The iPhone / iPad app is a one-time $2.99 purchase on the App Store. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free. Choose your platform on the download page. If you already have the app, continue with the guides to importing subscriptions, managing configurations, and verifying connections.