This guide is for first-time Shadowrocket users who already have a service provider and subscription. Follow the steps in order: get the app, add your subscription, connect, choose Global Routing, check your rules, and troubleshoot. The instructions use the iPhone / iPad interface; menu locations may differ on other platforms. Understand the difference between connection details and rule configuration, then test each step to avoid mistaking a failed subscription update for a connection-switch problem.
1. Does Shadowrocket work on desktop and Android? Where can I get it?
Shadowrocket is available for iPhone / iPad, Mac, Windows, Android, and Linux. Get the iPhone / iPad version from the App Store for a one-time purchase of $2.99; the developer is Shadow Launch Technology Limited. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Check the App Store listing for current iPhone / iPad system requirements.
Visit our download guide, choose your platform, then select the option for your device architecture and operating system. Mac downloads differ for Apple silicon and Intel; on Linux, choose the package format for your distribution. Get desktop and Android installers from the download links on this site.
A one-time app purchase is not a service plan. This site does not provide, sell, or recommend proxy servers or subscriptions. The steps below assume you already have your own service provider and subscription.
2. What do Home, Config, and Settings do?
Home shows your connections, lets you select one, and provides the connection switch. Config manages rule configuration files. Settings contains app options, including On Demand. Connection entries from a subscription and rule files in Config serve different purposes: the former determine where to connect; the latter determine how requests are routed.
- Home: Check which connection is selected, then check its status. Seeing an entry does not mean the remote service is available.
- Config: Check which configuration file is selected and review its
[Rule]section. Downloading a file to the list does not select it for use. - Settings: Adjust app behavior. Before troubleshooting, note any options you have changed so you can identify the cause if something goes wrong.
For your first session, complete a simple test: add an existing subscription, select an entry, connect, and open a website. Once that works, adjust routing and automatic connection settings.
3. Where do I add a subscription link?
Add the link as a Subscribe entry. Do not paste it into the server address, password, or rule editor. This sample shows the format only: https://example.com/sub?token=xxxx. It is not a working service URL. Use the complete link provided by your own service provider.
-
Copy the full link
Copy your existing subscription URL, including everything after
?. Check that there are no spaces or line breaks at either end. A provider's website login URL is not a subscription URL. -
Choose the entry type
Go to Home → tap “+” in the upper-right corner → Type → Subscribe. Once you have selected the type, enter the subscription URL and a name you can recognize.
-
Save and update
After saving, return to Home and update the subscription. Pull down to refresh, wait for the request to finish, then check whether connection entries appear under the subscription group.
-
Check the entries
Expand the relevant group and check that the names and number of entries match your service details. Then select an entry and test the connection.
A subscription URL's token often acts as an access credential. Before sharing a troubleshooting screenshot, hide the full URL, QR code, passwords, and keys. Never post them publicly.
4. Where is the connection switch? Why does iOS ask for VPN permission?
The connection switch is at the top of Home. Select a connection entry first, then turn on the switch. The first time you connect on iPhone / iPad, the system may ask you to allow a VPN configuration. This permission sets up the system network extension; it does not indicate whether your subscription is valid.
- On Home, tap the entry you want to use and check that it is selected.
- Turn on the connection switch at the top of Home, then follow the system prompt to authorize the VPN configuration.
- Return to Shadowrocket, check the connection status, then use a browser to make a new web request.
- To disconnect, turn off the same switch. If the connection starts again automatically, check Settings → On Demand.
A VPN status indicator only shows that the system tunnel is enabled. It does not confirm that remote authentication, DNS resolution, or the target website is working. Check the result of an actual request instead of relying on the status indicator alone.
5. Which Global Routing mode should I use: Config, Proxy, or Direct?
Global Routing determines how traffic is handled overall. Use Config for everyday routing by domain or IP. Switch to Proxy temporarily to troubleshoot the proxy path, or to Direct to test direct access over your local network. Scene lets you organize mode changes by scenario; it is not another proxy protocol.
- Config: Uses the rules in the current configuration to determine how requests are handled. To check the result, review the configuration file, rule order, and matched policy.
- Proxy: Routes all traffic through the proxy policy. Use it for comparison with Config, but do not assume that every request will succeed.
- Direct: Routes traffic directly without using the selected proxy server. It does not automatically choose the fastest connection.
- Scene: Switches between configured scenarios. If you have not set up scene conditions, use Config, Proxy, or Direct explicitly while troubleshooting.
For a comparison test, keep the same connection entry and target URL, and change only Global Routing. If the site works in Proxy but not Config, check the rules and policy references rather than immediately changing all connection details. Restore your preferred mode when the test is complete.
6. Where do rules go, and why might changes not take effect?
Rules go in the configuration file's [Rule] section and are evaluated in order when Config is selected. First check which file is selected in Config, then confirm that your rules are in that file. Editing a different, inactive file will not change how traffic is handled.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
This is a rule syntax example, not a complete configuration. DOMAIN-SUFFIX matches a domain suffix and its subdomains; IP-CIDR matches an IP address range; GEOIP classifies traffic using an IP geolocation database; and FINAL provides a fallback policy for requests that do not match earlier rules. Domain and IP requests use different matching conditions, so the text in the address bar alone does not tell you which rule matched.
Check the rules
- Global Routing
- Config
- File location
- Config → currently selected file
- Rule section
[Rule]- Match order
- Top to bottom; put FINAL last
After adding a rule, save the file and test the result with a new request.
Check the policy
- DIRECT
- Direct policy
- PROXY
- Proxy policy; check which connection is actually selected
- Custom policy name
- Must match a policy name defined in the configuration
- no-resolve
- For IP rules, avoid triggering an additional DNS lookup for the rule
Existing connections may continue to be reused. If needed, reconnect before testing again.
7. What does updating a subscription do? Do I need to update before every connection?
Updating a subscription requests its URL again and refreshes the connection entries with the returned content. It does not turn on the connection switch or automatically replace the rule file currently selected in Config. Unless your service has changed, you do not need to update every time before connecting.
- Update when: Your provider announces changes to entries or server addresses, or the subscription group does not match the provider's information.
- Check the URL first: If an update fails, verify that the full link is correct and still valid. A URL opening in a browser does not guarantee that the subscription endpoint returns data the app can parse.
- Note the result: Record whether the request timed out, failed authentication, failed to parse, or returned an empty list. Each points to a different troubleshooting path.
- Check the update route: If the subscription URL must be accessed through an existing proxy, check Update via Proxy under Settings → Subscribe. This requires a working connection.
If a subscription returns no content, repeatedly deleting and re-adding the same URL usually will not change the server's response. First check the service validity period, subscription access, and provider-side status. Remote rule configuration updates may also overwrite local changes, so keep a copy of your configuration before editing.
8. Does On Demand connect automatically? Why does it reconnect after I turn it off?
Settings → On Demand configures connections triggered by specific conditions. It serves a different purpose from Global Routing: On Demand determines when to establish or disconnect the tunnel, while Global Routing determines how traffic is handled when the tunnel is active. If the connection comes back after you turn it off manually, first check whether an On Demand condition is still being met.
- Go to Settings → On Demand and check whether the feature is enabled and whether any rules apply to your current network.
- Note the actions set for conditions such as Wi-Fi and cellular. A setting for one Wi-Fi network does not apply to every network.
- To troubleshoot a manual connection, temporarily turn off On Demand, then return to Home and use the connection switch.
- Once the manual connection works, restore your automatic rules and test them separately on the target Wi-Fi and cellular networks.
Automatic connection conditions cannot fix problems with a remote server, account, or rules. Do not add automatic connection settings until a manual connection works. Otherwise, system-triggered reconnections and remote failures may alternate, making the cause harder to identify.
9. Why can't I access websites when there are subscription entries and the switch is on?
Troubleshoot in this order: local network → selected connection → Global Routing → rules → DNS and target website. Change one thing at a time and record the result for the same URL before and after each change. A latency reading alone does not mean the target website's HTTPS request completed successfully.
Can't open websites even with the connection off?
Turn off the Home connection switch and temporarily disable Settings → On Demand, then try a website that normally works over a direct connection. If it still fails, complete any Wi-Fi sign-in or check your local network before changing proxy protocol settings.
Works in Proxy but not Config?
Keep the same connection entry and check the currently selected file in Config. Focus on the target domain's DOMAIN-SUFFIX rule, earlier rules, FINAL, and whether the policies referenced by the rules exist.
Update succeeded, but every entry times out?
A successful update only means the subscription request returned a result. Check that the service is valid, along with the server address, port, and authentication details, then compare with another existing entry. If the result is the same across multiple networks, send your provider a redacted error message to investigate.
If only one website has a problem, consider the site's own status and access restrictions. If domain access fails but an address-based connection test succeeds, check DNS settings. Do not treat changing DNS at random as a universal fix.
10. Do I need to enter protocol settings manually? Can I copy them to another device?
If you already have a subscription that imports correctly, use the connection details it provides. Before adding a connection manually, confirm its protocol type. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different fields; do not mix them up just because some fields are called “password” or “key.”
- Address and port: Follow your service's instructions. The port 443 used by an HTTPS subscription URL does not mean the proxy server also uses port 443.
- TLS and transport: TLS, Server Name, Host, and Path each serve a different purpose. Do not paste the entire subscription URL into any of these fields. Match the settings to the server configuration.
- Protocol credentials: A VMess / VLESS UUID, a Trojan password, and a WireGuard PrivateKey / PublicKey are different types of credentials and cannot be used interchangeably.
- Moving to another device: Import your own subscription on the new device, then check Global Routing, Config, and On Demand again. Using the same subscription does not automatically copy all local settings from the old device.
Before moving a configuration that contains device keys, such as WireGuard, check whether the service allows key reuse and whether a separate address must be assigned. If multiple devices cannot connect at once, the cause may be server-side device limits or key allocation, not the app. For a step-by-step first connection, see the setup guide; for protocol field details, see protocols.