Shadowrocket Quick Start

01 · Add Server / Subscribe Import your details

Open Shadowrocket and go to Home. Use Home to view and select servers; Config is for managing configuration files. After importing a subscription, look for its server entries on Home—not just a filename in Config. Choose one of the methods below based on the details you have. There's no need to import the same details twice.

Have a subscription URL? Choose Subscribe

On Home, tap the add button in the top-right corner to open Add Server. Tap Type, choose Subscribe, and enter your complete subscription URL in the URL field. You can use the name or notes field to identify the source; don't enter authentication details there. Save, wait for the contents to load, then return to Home and check that the subscription and its servers appear.

Before pasting, make sure you have a subscription URL—not an account page, help page, or individual server share link. It's easy to miss parameters at the end of a URL or accidentally include a line break, space, or punctuation from a message. Preserve the URL's capitalization and parameters; don't delete the query string based on guesswork. A successful subscription import means the app read its contents, not that every server in it can connect.

A subscription is an updatable list of servers. To refresh it later, find the subscription on Home and use its edit or action menu to update the existing entry. Don't add another subscription with the same name each time. After updating, check that your selected server is still listed. If the update fails, keep the existing entry while checking the URL and network; don't immediately clear all your details.

Have details for one server? Check the Type and fields

From Home, open Add Server and choose the Type that matches the protocol in your server details. Enter the address, port, and required authentication information in the corresponding fields. Fields vary by protocol: a password, UUID, TLS settings, and transport options aren't interchangeable. Enter only the server address in the address field; don't include the port, path, or entire share link.

If you have a complete share link supported by Shadowrocket, use the import option in the app. If you have a QR code, use Scan QR Code and allow camera access if prompted. After importing, open the entry and check its Type, address, port, and authentication fields. Automatic parsing saves manual entry, but it can't tell you whether server details have expired or confirm that the transport settings match the server.

Return to Home after saving and confirm that the server appears in the list. Its name is just a label; the settings inside the entry determine how it connects. At this point, you've added the details to the app, but haven't chosen how requests are routed. Next, choose Global Routing and turn on the connection. For the difference between subscriptions, share links, and configuration files, see the glossary.

02 · Global Routing Choose a mode

On Home, open Global Routing and choose the mode you need. The three options are Config, Proxy, and Direct. They change how requests are routed, not which server you're using. Switching modes won't fix a server address or authentication field, or restore an expired subscription.

Config: Apply policies from the active configuration

Config routes requests according to the active configuration. Open Config and confirm that the configuration you need is selected—not just listed among your files. Return to Home and confirm that Global Routing is set to Config. If you're new to the app and don't have rules ready, don't import and switch between multiple configurations from unknown sources. First check what the active configuration is for, then decide whether to use it.

Common rules include PROXY, DIRECT, and REJECT: they route requests through a proxy, connect directly, or reject requests, respectively. Whether a request uses a server depends on the matching rule and its policy, so some requests connecting directly in Config mode is normal. A webpage loading doesn't mean every request used a proxy, and one direct connection doesn't mean the configuration is broken.

Proxy: Test the selected server first

Proxy can help with an initial test: select your server on Home, then set Global Routing to Proxy to reduce the impact of rule-based routing. This is a troubleshooting step, not a recommendation to use Proxy for every situation. Necessary app or system exceptions may still affect some requests, so Proxy doesn't mean every type of traffic on the device follows exactly the same route.

If access works in Proxy but fails in Config, check the active configuration, matching rules, and DNS next—not the server password. When testing is done, restore your preferred mode and note which configuration you used. This helps separate server availability from whether the rules are working as expected.

Direct: Compare against your regular network

Direct routes requests without using a proxy, which is useful for checking whether your current network can reach a destination. The server may still appear in the Home list when Direct is selected, but its presence doesn't mean requests are using it. For a useful comparison, keep the network and destination the same and test at roughly the same time. Switching networks can affect the result too.

After choosing a mode, there's no need to adjust advanced fields yet. Return to Home, confirm the mode, and continue to the next step. For details on General, Rule, Host, URL Rewrite, and rule order, see the configuration reference. This guide covers only the checks needed for a first connection.

03 · Home Connect

Return to Home, tap the server you want to use, confirm it's selected, and turn on the connection. If your subscription includes several servers, test one first rather than switching repeatedly during the same test. To edit an entry, stop the connection first, make and save your changes, then select the entry again to connect.

First connection: VPN configuration prompt

The first time you turn on the connection, the system may ask to let Shadowrocket add a VPN configuration. Check the app name in the prompt, allow it, and complete device authentication as requested. Then return to Shadowrocket and check the status. This permission lets the app create a system connection for network handling; it isn't a purchase confirmation and won't import a subscription or fill in server details.

If you previously denied permission, the connection may not complete. Turn it on again and follow any system prompts. If no prompt appears, check for the Shadowrocket entry in the system's VPN settings. Settings paths and layouts can change between system versions; don't delete other configurations just to find a specific menu name.

The steps are the same on iPad: select a server, turn on the connection, and respond to the system permission prompt. Landscape orientation and device layout can move controls. Use labels such as Home, Global Routing, and Config to find features rather than relying on their position on screen.

A connection switch isn't proof of access

An enabled switch and a VPN indicator show that the connection configuration is in the corresponding state. They don't prove that server authentication succeeded, DNS is working, or every website is reachable. Some issues appear only when a request is made, so verify access in the next step. If the switch turns off immediately, troubleshoot authorization or connection setup first—not Rule.

Leave On Demand off during the first connection test. It triggers connections based on conditions and isn't required for a successful manual connection. If you've already set conditions, they may trigger a connection again after a network change or manual disconnect. Check those conditions while troubleshooting, then test the manual connection. Once that works reliably, set up and test automatic connection separately.

04 · Connectivity Test Verify the connection

After connecting, check the selected server and then test a real webpage. Open Connectivity Test in the app, confirm it's testing the selected entry, and review the result. A result shown for a server doesn't mean it's the one currently selected. After updating a subscription or switching servers, check again on Home.

Review the test result, then make a real request

Connectivity Test can show whether a test request received a response, but results depend on the test method, destination, and network. A timeout is worth investigating, but a successful test doesn't replace checking in a browser. Don't treat the reported time as the speed every app will get, or delete a server based on one result.

In Safari, visit a familiar webpage that you can access and use to check whether the page and its necessary resources load. If possible, try two different sites so that maintenance or access restrictions on one site aren't mistaken for an app issue. Keep the network unchanged and reload the page rather than relying on an old tab; cached content can make it look as if a new request succeeded.

If the page loads, check that the result matches your Global Routing mode. Proxy tests the server route, Direct tests your regular network, and Config requires checking the rules. Config may connect some destinations directly, so a page loading and a page going through a proxy are two different things. To verify routing, check the policy used by the corresponding request and compare it with the configuration's expected behavior.

Compare results under the same conditions

If the result is unclear, note the current server, Global Routing mode, selected configuration, and test destination. Stop the connection and check the same destination on your regular network, then reconnect and compare. Change one condition per test to identify whether the server, mode, or network is relevant. Don't switch servers and networks and change DNS all at once, then record only that it works.

A successful check means more than seeing an indicator: the selected server matches your expectations, the mode suits your needs, real requests work, and policies in Config behave as intended. Once these conditions are met, you can keep using the current settings. For more routing setup, see the Rule configuration reference. If the problem persists, use the next section to narrow it down; there's no need to start over with installation.

05 · Common issues Troubleshoot step by step

First identify where the problem occurs: the subscription hasn't loaded, the connection switch won't stay on, or the switch is on but webpages fail. Each calls for different checks. Keep entries and configurations that work, and note their original settings before making changes. After each fix, repeat the test from the previous section. Don't overwrite everything at once.

Subscribe fails to load or the list is empty

Return to Home, open the edit options for the subscription, and check that the URL is complete, especially its ending parameters, spaces, and line breaks. Confirm the link is still valid and returns a server subscription the app can read—not an account sign-in or help page. Opening a URL in a browser doesn't mean its contents are in subscription format. Never test a link containing authentication details with a public tool.

If the subscription loads on your regular network, update it while using that network. If updating requires a particular connection, first use a server you already have that works, then try again with the app's current settings. You can't use a server that hasn't been imported yet to retrieve the same subscription. For questions about link validity, account status, or server details, contact the provider of your existing service. This site doesn't provide replacement subscriptions.

The switch turns off immediately or the connection won't establish

First check system permission for the VPN configuration, then confirm that a usable server entry is selected on Home. Open the entry and check that its Type, address, port, and authentication fields match the original details. For protocols with TLS or transport settings, verify the server name, path, and other specified parameters. Don't bypass an unknown error by disabling certificate validation, or copy settings from a different protocol.

If another VPN connection is active on the system, stop it and test Shadowrocket on its own. Otherwise, a connection handoff or status change could look like a server failure. Check that the device date and time are correct; a significantly incorrect clock can affect secure connections. Reconnect after correcting any issues and check whether the status stays on. If not, keep investigating the connection rather than the routing rules.

The switch is on, but no destinations are reachable

Check your regular network by selecting Direct or stopping the connection. If the network itself can't connect, address Wi-Fi, cellular service, or any required network sign-in first. If it works, select one of your own servers, compare using Proxy, and run Connectivity Test. If both checks fail, focus on server availability, authentication details, and transport settings.

If the test returns a result but Safari still fails, check DNS settings and the destination. An outdated custom DNS setting may affect name resolution. Note the current value before comparing it with a known-working setting. Don't assume DNS is the cause just because a page won't load, and don't add multiple custom addresses at random. For DNS and related General settings, see the configuration reference.

Proxy works, but Config fails or only some destinations fail

Open Config to confirm which configuration is selected, then check the relevant Rule entries. Rules are usually evaluated in order, so a broad rule earlier in the list may match before a more specific one. Use FINAL as the fallback at the end. Also check whether the matching policy is PROXY, DIRECT, or REJECT; don't just look for the destination domain in the rule list.

If only some sites fail, consider the destination's status, other domains the webpage relies on, and current network conditions. Don't route all requests the same way just to fix one page. Compare Proxy and Config for the same destination and check the actual request records to narrow down the issue. See the glossary for DOMAIN-SUFFIX, IP-CIDR, and FINAL, and the Rule configuration reference for syntax and order.

Record the steps to reproduce the issue

Note the device type, current network, Global Routing mode, steps that trigger the issue, and whether all or only some destinations fail. Before sharing error details, remove subscription URLs, passwords, UUIDs, and other authentication information. Keep the protocol type, error message, and checks you've completed. Configurations may also contain private addresses; review each item rather than masking only the server name.

Restore any temporary mode and settings changes made during troubleshooting, then select your usual server and Config and verify access to a real webpage again. If the problem persists, continue investigating the layer you've identified. A first connection involves getting the details, routing, authorization, and request results working together. Add rule refinements, On Demand, and other configuration options one at a time after this basic flow is reliable.