Before using Shadowrocket for the first time, have your own valid subscription or server details ready. Then import them, select a server, allow the system to add a VPN configuration, and test the connection. This guide uses Home on iPhone and iPad to explain system permission, connection status, routing modes, and server tests. Follow the steps in order to connect for the first time and identify whether an issue involves permission, server details, or routing. The permission prompt usually appears when you start your first connection, not necessarily when you open the app.
1. Before you begin: client, subscription, and configuration
Shadowrocket is a closed-source commercial app developed by Shadow Launch Technology Limited. Its App Store ID is 932747118. The iPhone and iPad app costs $2.99 as a one-time purchase; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. See the download page for all platforms. The system permission steps below apply to iPhone and iPad; menu paths differ on other systems.
Buying the app does not include a service plan. This guide assumes you already have your own service provider and subscription. This site does not provide, sell, or recommend servers, subscriptions, or providers. Installing the app does not automatically add usable servers. If the list on Home is empty, import your existing details rather than repeatedly toggling the connection.
- Server details: These specify the connection destination and authentication method, such as the address, port, password, UUID, or key. Required fields vary by protocol.
- Subscription: Retrieves and updates a set of server details. A subscription URL is not the address of an individual server and cannot be entered directly in the server's Port field.
- Configuration file: Defines rules, policies, and related settings. Importing a subscription and selecting a Config are separate tasks. Servers appearing in the list do not mean that routing rules are already configured.
2. Allow VPN configuration: from import to first connection
The system prompt to add a VPN configuration asks for permission to let Shadowrocket create a local network tunnel. This only grants local permission; it does not mean the server has been tested. After granting permission, connect to a server in the app. Access to a destination depends on your network, server details, and routing settings.
-
Prepare your details
Open Home and make sure you have a complete subscription URL or server details. Subscription URLs may contain access tokens. Do not post the full URL in public forums or share it in an unredacted screenshot.
-
Import a subscription
Go to Home → tap “+” in the upper-right corner → Add Server. Set Type to Subscribe, paste your full subscription URL into URL, and save. The example
https://example.com/sub?token=xxxxonly illustrates the field format; it cannot be used to obtain servers. -
Select a server
Wait for the subscription to load, then select an entry in the Home server list. If you added a single server, check its Type, Address, Port, and protocol-specific authentication fields before saving and selecting it.
-
Allow the configuration
Turn on the connection switch at the top of Home. When the system asks to add a VPN configuration, confirm that the request is from Shadowrocket, tap Allow, and complete device authentication as prompted. Do not share your device passcode with a website or in a chat.
-
Check the connection
Return to Home and check whether the status changes from Not Connected to Connected. Run Connectivity Test, then verify access in an app you actually use. Keep the selected server and Global Routing setting unchanged so you can reproduce any issue.
3. Home screen sections: status, tests, and server list
Home is where you manage everyday connections. Check the screen from the status at the top downward; do not rely only on latency figures in the list. Not Connected means the client has not established a VPN connection. It does not indicate whether a subscription is valid or whether every server is unavailable.
| Section | Purpose | What to check on first use |
|---|---|---|
| Not Connected / Connected | Shows the current connection status; use the switch beside it to connect or disconnect. | After turning it on, does the status remain Connected or immediately return to Not Connected? |
| Global Routing | Sets the overall routing mode and determines how traffic is handled by rules or the proxy. | Is the selected Config, Proxy, Direct, or Scene the one you expect? |
| Connectivity Test | Tests connectivity for list entries using the current test settings. | Which entries return a result and which time out? These results are not download speeds. |
| SERVER list | Shows saved servers and servers retrieved from a subscription for selection and editing. | Check the selected marker, which subscription an entry belongs to, and whether its details match your existing information. |
Connectivity Test results are not bandwidth
Results shown in milliseconds measure elapsed time during the test, not how much data can be downloaded per second. The test method and target affect the result: a successful test does not guarantee that every website, protocol, or UDP flow will work. A timeout should be assessed alongside your current network and test settings; it does not by itself mean the subscription is invalid.
- Test entries in the same list first, then connect using a server that returns a result. Avoid changing servers and rules at the same time.
- Retest using the same webpage or app. If the test returns a result but the destination still does not load, check Global Routing, rule matching, and DNS rather than comparing milliseconds alone.
- Do not enter a test result as the Port. Port is the port number in your existing server details. Enter
443only if the details specify443; do not infer it from whether a website uses HTTPS.
4. Global Routing: decide what you are testing
Global Routing changes the routing mode; it cannot correct an incorrect password, port, or transport setting. For initial setup, first verify that the server works, then use a checked configuration for everyday routing. The recommendations below assume you already have a valid configuration. Config does not inherently correspond to any particular set of routing rules.
Config
RecommendedRoutes connections according to the rules and policies in the current configuration file. Which requests connect directly and which use the proxy depends on the rules, their order, and the selected policy.
Best for: everyday rule-based routing after checking the configuration.
Proxy
Routes traffic handled by the client through the proxy path, which can help compare behavior and identify rule-related differences. This does not confirm that the destination server is available, nor does it guarantee that all special system traffic uses the proxy.
Best for: briefly testing the proxy path to distinguish server issues from rule issues.
Direct
Uses a direct connection without forwarding through the selected proxy server. Connection status and proxy use are separate; Connected alone does not mean a request is passing through the server.
Best for: comparing behavior over your local network without a proxy.
Scene
Applies routing behavior based on the configured scene conditions. Check each scene's conditions and actions before use; selecting Scene alone does not tell you whether a request will use the proxy or connect directly.
Best for: setups where you understand and have configured scene-switching conditions.
For example, if the same server reaches a destination in Proxy but fails in Config, focus on the current configuration's rule match, policy target, and DNS settings. This comparison narrows down the cause but does not prove that a specific rule is wrong. Keep the network and destination unchanged, repeat the test, and then make changes.
5. Home, Config, Settings: keep each setting at the right level
Use Home to import and select servers and control the connection; use Config to manage and select rule configurations; use Settings for app preferences. Keeping these areas separate during initial setup helps avoid confusion about which setting is in effect when a server is selected.
Setup order: verify the connection, then check routing
Connection details: Home
- Import your existing subscription or individual server.
- Check the server's Address, Port, and authentication fields.
- Select an entry, run Connectivity Test, and start the connection.
Routing settings: Config / Settings
- In Config, confirm which configuration file is active.
- In Home → Global Routing, confirm the routing mode.
- In Settings → On Demand, check the on-demand connection settings.
Change only one variable at a time and keep a copy of the configuration that worked. Updating a subscription does not automatically replace all routing settings.
Rule keywords only apply in the relevant configuration context
The following shows the syntax for a configuration file's [Rule] section; it is not a complete, ready-to-use configuration. The domains and network ranges illustrate the format. PROXY refers to a proxy policy, which must exist and be valid in the current configuration. Rules are evaluated in order; FINAL handles connections that did not match an earlier rule.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY
DOMAIN-SUFFIX matches domain suffixes; IP-CIDR matches IP ranges; GEOIP relies on IP geolocation data; FINAL handles connections not matched earlier. These rules matter only when the routing mode matches the configuration in use. Testing in Direct does not show that the configuration’s PROXY rules are working.
On Demand does not fix server details
Settings → On Demand manages on-demand connections. Depending on its settings, it may start a connection automatically. During initial troubleshooting, note whether it is enabled so you can avoid an automatic reconnect after disconnecting manually. Test with a controlled manual connection first, then configure on-demand behavior separately. Enabling On Demand does not fill in a missing password or refresh an expired subscription token.
- When adding Shadowsocks, VMess, VLESS, Trojan, Hysteria2, or WireGuard manually, set Type to match your existing details. Do not mix fields between protocols.
- Even when the protocol name matches, the settings may differ. Check TLS, transport, and authentication details against the original information; a port number cannot replace the full set of parameters.
- After updating a subscription, check whether the currently selected entry is still there. If server names are similar, verify the source and details instead of choosing by name alone.
6. First-use questions: troubleshoot by symptom
The app opened without a VPN permission prompt. Is the installation incomplete?
Not necessarily. First import and select a server in Home, then turn on the connection switch at the top. The system may request permission when you start the first connection. If a valid Shadowrocket VPN configuration is already saved on the device, it may not ask again. Do not reinstall just because no prompt appeared at launch.
It says Connected, but access still does not work as expected. Why?
First check Home → Global Routing. Direct does not use the selected proxy; Config requires checking the configuration and policies; Proxy can be used for a brief comparison. Then run Connectivity Test and retry the same destination. Connected describes the connection status; it does not prove that every destination is reachable.
The SERVER list is empty. Will granting VPN permission populate it automatically?
System permission does not create servers. Go to Home → “+” → Add Server and add your existing details. For a subscription, choose the Subscribe type and enter the full URL. If no entries appear after saving, check whether the subscription is reachable, the token is complete, and the response contains data the client can recognize.
The connection comes back after I turn it off. What should I check?
First check Settings → On Demand and note the current conditions. Temporarily turn off on-demand connections and test again. If the device is managed by an organization, also check its system VPN management policies. Avoid changing multiple settings at once, or you will not know what triggered the reconnect.
Shadowrocket downloads and setup guides
The iPhone and iPad app costs $2.99 as a one-time App Store purchase; check the App Store listing for system requirements. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free. Buying the app does not include a service plan. Choose your platform on the download page or continue to the subscription and configuration guides.