Official Manual · First Connection

Shadowrocket Setup Guide: Import a Subscription and Connect for the First Time

Start by importing your existing server details into Shadowrocket, then choose how traffic is routed, connect, and verify the result. These five steps help you establish a connection you can check and repeat; you do not need to adjust every setting on your first use.

Before you start: install the app and have your own connection details

Install Shadowrocket first. Get it for iPhone or iPad from the App Store; install the free desktop and Android versions from the download page. The iPhone / iPad version costs $2.99 as a one-time App Store purchase. The Mac / Windows / Android / Linux versions are free. Check the App Store page for iPhone / iPad system requirements.

This tutorial uses the iPhone / iPad interface. Before you begin, make sure you have your own subscription link or server details. Get subscriptions from your service provider; this site does not provide server nodes or subscriptions. A one-time app purchase does not include a service plan, and installing the app does not automatically provide a usable server.

Keep your current configuration and the original settings from your service provider for now; do not rush to delete existing entries. For the first test, use one clearly identified server or a subscription with a known purpose, and keep the current network unchanged. This makes it easier to tell whether an issue comes from importing details, connecting to the server, or choosing rules.

Add a server or import an existing subscription

First identify whether you have details for one server, a server subscription link, or a configuration file link. They may all look like text or a URL, but they appear in different places and serve different purposes after import: server details determine where to connect, while a configuration file mainly determines how requests are handled. Do not assume that a link belongs in Config just because it starts with HTTPS.

Individual server: open Add Server from Home

Open Home in Shadowrocket, tap the add button in the upper-right corner, and open Add Server. Choose the protocol specified by your service provider in Type, then enter the address, port, and authentication details exactly as supplied. Protocols such as Shadowsocks, VMess, VLESS, and Trojan use different fields. Do not enter a password or identifier for one protocol into another protocol's form.

Check each field against the original details, not just the address and port. If your service provider also specifies TLS, Server Name, a transport method, or a path, enter those values as directed; do not infer them from the server's display name. After saving, return to Home and confirm that the new entry appears in the SERVER section, then select the server you plan to use. The name is just a label for identification, not proof that the settings are correct.

Server subscription: choose Subscribe in Add Server

If you have a server subscription link, choose Subscribe in the Type field in Add Server, enter the complete link in URL, add a recognizable label, and save. Get subscription links from your service provider. When copying, do not include explanatory text, line breaks, or surrounding quotation marks, and do not remove parameters after the question mark.

After importing and fetching the contents, return to Home and check whether the SERVER list shows the relevant group and servers. Saving a subscription entry does not mean its server contents were successfully retrieved. If the list is still empty, check whether the subscription was fetched successfully before moving on to the connection steps. Updating an existing subscription does not require adding another copy. Find the update action for the existing subscription to avoid duplicate entries and selecting the wrong one.

Subscribe in Config: for configuration subscriptions

If you were given a configuration file link, open Config and use its Subscribe option to add or manage the configuration subscription. After importing, check that the file is available and identify which configuration is active. Do not use a server subscription in place of a configuration subscription, or vice versa: seeing a server on Home does not mean rules are selected in Config, and having a file in Config does not mean Home has a usable server.

If you have a QR code or an individual protocol link, you can use the app's QR scanning or clipboard import options, but only with information from a source you recognize and already have. Subscription URLs may contain access credentials; do not share the full link, QR code, or authentication fields publicly. For more on the import options, see Subscribe, Add Server, QR code, and clipboard import. Once the SERVER list contains an entry you can select, continue to the next step.

Choose Global Routing: Config / Proxy / Direct

Return to Home, tap Global Routing, and choose how this connection should handle traffic. This controls the direction of request handling; it does not change server settings or repair a failed subscription. On first use, check which server is selected separately from how requests are handled. Changing just one of these does not change all connection conditions.

Purpose and key checks for Config, Proxy, and Direct
Mode How it works What to check first
Config Uses the rules in the currently active configuration to choose a policy. Check the active configuration in Config and confirm that its rules match your expectations.
Proxy Routes requests through the proxy path to test the selected server's connection. Check which server is selected on Home. Do not assume that configuration rules are active.
Direct Routes requests directly. Useful for comparison, but not for checking whether a proxy server is available.

Choose Config when you have suitable rules and want to route traffic by domain or address, then check the active file in Config. Seeing a file listed on the page does not mean it is in use. If you are unsure whether the rules are correct, note the current mode and temporarily choose Proxy to test the server. Once the basic connection works, return to Config and compare results for the same destination.

Direct is mainly useful for comparing access over the current network. If a page opens in Direct mode, that does not mean the previously selected server has recovered, nor does it necessarily mean the connection switch is off. After comparing, return to the mode you need and check the Global Routing value shown on Home.

Change the mode only; do not change rules at the same time

Leave the configuration file as it is for now. If Proxy works but Config does not, check the active configuration and the matching result rather than immediately re-entering all server details. See Rules and configuration reference for rule keywords, policies, and matching order.

You do not need to create a new set of rules for this guide. Confirm the current mode, selected server, and active configuration first. Then connect so the verification results can be compared meaningfully.

Turn on the Home connection switch and allow the VPN configuration

In the SERVER section on Home, select the server you just checked, confirm the Global Routing mode, and then turn on the connection switch at the top of the screen. You may see Not Connected before the first connection. After switching it on, check whether the status changes rather than tapping repeatedly. Repeatedly toggling the switch interrupts the process and can make it difficult to distinguish a system authorization prompt from the app's status.

Responding to the first system authorization prompt

On first use, the system asks permission to let Shadowrocket add a VPN configuration. Check which app the prompt refers to, choose Allow, and confirm using your device passcode or biometric authentication as required. This creates a system configuration on the device to carry the connection; it does not add a server or change subscription details from your service provider. If you previously denied the request, start connecting again in the app and follow the system prompt.

After authorization, return to Shadowrocket and check the switch and connection status at the top. Seeing a VPN configuration in system settings only means that the configuration was created; it does not prove that the server is reachable, authentication succeeded, or web access works. Even if the system shows VPN as connected, you still need to test an actual request in the next step.

The switch turns off immediately or the status does not change

First confirm that a server is selected on Home, rather than just having added a subscription entry. Then check that system authorization is complete and whether another VPN connection or device management policy affects the current connection. Do not delete system configurations whose purpose is unclear. On managed devices, follow the device management requirements.

For initial troubleshooting, leave On Demand disabled. It triggers connections based on conditions and is not required for a manual connection. Mixing automatic triggers with the manual switch makes it harder to tell why a connection starts again after being turned off. If On Demand is already enabled, note the original setting, temporarily disable automatic connections, and run a manual test.

Once the switch stays on and the app status has updated, continue to the verification steps. Do not change servers or DNS yet; first check which requests work under the current conditions.

Verify the connection with Connectivity Test and real requests

Check connection success at three levels: whether the system connection is established, whether the selected server passes a test, and whether the destination request is handled as expected. Success at any one level does not confirm the other two. Run the full set of checks on the current Wi-Fi or cellular network before switching networks, so test conditions remain consistent.

Run Connectivity Test, then make an actual request

Use Connectivity Test on Home and observe the result for the selected server. Different test methods may check different stages, so a response only describes that test; it does not guarantee that every website or app will work. Do not switch servers repeatedly based only on one response time in the list. First confirm that the selected entry is the same one you tested.

Next, open a browser and visit a familiar HTTPS page that normally works, then reload it once. If the page is cached, seeing old content does not necessarily mean a new network request was made. You can also check another normal network action, such as opening a link on the page you have not visited before, but do not rely solely on an unfamiliar test site.

Check the actual policy when using Config

To verify rule-based routing, use Config to visit a destination whose expected policy you know. Then open Data or the connection log in the app, locate the relevant entry by domain and request time, and check which policy it used. A page loading does not prove that it went through a proxy; a DIRECT route may also load it successfully.

If the result is not what you expected, keep the destination, server, and network the same, temporarily switch to Proxy, and test again. If Proxy works but Config does not, check the rules and configuration first. If both fail, prioritize checking the server, authentication, or current network. Restore the mode you need after testing and do not leave temporary troubleshooting settings in place for everyday use.

  1. The connection status at the top of Home has changed, and the selected server is the one you intend to use.
  2. You have observed and noted the Connectivity Test result separately from the actual web access result.
  3. The current Global Routing mode is clear; if using Config, you have checked the active configuration.
  4. If verifying routing, you have checked the destination request log rather than relying only on the system VPN indicator.

Once these checks pass, you have a repeatable baseline for your first connection. When you later change rules, DNS, or On Demand, change one type of setting at a time and repeat these checks to identify what caused the difference.

Common issues: check the step where the problem occurs

When something goes wrong, start with the earliest failing step. Do not reinstall, change DNS, switch servers, and edit rules all at once. Note the current network, server, Global Routing mode, and the specific action that caused the issue. “The list is empty after saving the subscription” is more useful than a general “connection failed.”

The SERVER list is empty after import, or the subscription will not update

Return to the import steps and check whether you used the server subscription option or the configuration file option. Check for a truncated link, spaces, or missing parameters, then confirm that the current network can fetch the subscription. A failed fetch and a failed proxy connection are different issues. A working old server does not prove that the subscription update address is reachable.

If the address returns a login page, reports that it has expired, or does not show the expected content, ask your service provider to confirm the link status and format. Do not assemble authentication parameters yourself. If you need to keep troubleshooting evidence, record the error message. When sharing screenshots publicly, hide the full URL, QR code, password, and other authentication details.

The connection switch will not stay on, or the server test fails

First revisit the system authorization and connection steps, then check the server address, port, authentication, and transport settings. In particular, distinguish the label from the actual address and confirm that you selected the right protocol. If possible, repeat the same test on another working network. A different result after switching networks only shows that network conditions affect the result; it does not identify which side is at fault.

If several servers from the same subscription fail, also check whether the service is available and authentication is valid. If only one server fails, check its settings or availability first. Do not randomly change TLS, Server Name, or the path as a test; these parameters must match the server requirements.

The test responds, but web pages still do not load

First check whether the issue affects just one destination, then compare Proxy and Config. If only some domains fail, inspect the relevant request log, actual policy, and DNS resolution. DNS resolves domain names to addresses; changing DNS will not fix an incorrect server password, and not every access failure is a DNS issue.

Keep the system DNS setting as a comparison point and note the original setting before changing it. To compare system DNS, custom DNS, and DNS over HTTPS, read DNS settings and troubleshooting resolution. Change only one DNS setting during this test, then retry the same destination to make the result clear.

Proxy works, but Config does not behave as expected

Open Config and check the active configuration, then find which rule matched the destination request. Rules are usually matched in order. A broad rule placed before a more specific one may determine the result first; FINAL provides the last policy when no earlier rule matches. Also check whether the request matched REJECT rather than assuming every failure means the server disconnected.

This first-connection guide stays focused; you do not need to rewrite the entire file right away. For the structure of General, Rule, Host, and URL Rewrite, or the meanings of DOMAIN-SUFFIX, IP-CIDR, PROXY, DIRECT, and REJECT, see the Shadowrocket rules and configuration reference. To establish a new test baseline, return to the Global Routing steps in this guide and test again under consistent conditions.

Restore your everyday settings after troubleshooting

Restore your intended Global Routing mode, confirm the selected server and active configuration, then decide whether to re-enable On Demand. Keep an error description that can reproduce the issue, but do not keep temporary test settings. Do not delete an existing configuration that still works until you know the cause.