Shadowrocket Setup Guide

01Add Server / Subscribe: Import existing details

First identify what information you have, then choose the right option. A subscription link retrieves and updates a group of servers; a single-server share link imports one entry; an address, port, and credentials must be entered manually. Don’t assume a link is a subscription just because it starts with https://. An account page, help page, and subscription URL are different things. If you’re unsure what a link is for, check the service information you already have.

Have a subscription link? Use Subscribe

Open Shadowrocket, go to Home, tap the add button in the top-right corner, and open Add Server. Under Type, choose Subscribe. Back on the form, paste the complete subscription link into URL. If you have multiple subscriptions, enter a name you’ll recognize in Remarks, then save. Subscription URLs often contain personal access credentials. Don’t share them in public forums or post the full link to demonstrate the steps.

Wait for the subscription request to finish, then return to Home and check for the expected group and server entries. If you see the subscription name but no servers, don’t continue to the connection steps yet. Check whether the request succeeded, the link is still valid, and the response contains subscription data the app supports. Seeing a subscription name does not mean all server details were retrieved successfully.

Understand the difference between Subscribe and Config. Subscribe imports and updates server details; Config manages configuration files that affect rules and other behavior. You don’t need to import an unfamiliar configuration to get started, and having a subscription doesn’t mean you have a rules configuration that suits your needs. Once your servers appear, verify the connection using this guide, then organize your configuration as needed.

Have server details? Enter them with Add Server

If you have details for a single server, choose its actual protocol under Type in Add Server, such as Shadowsocks, VMess, VLESS, or Trojan, and fill in the matching fields. Check Address and Port; authentication fields vary by protocol and may include Password or UUID. Don’t use fields from one protocol for another, and don’t guess the protocol from the port number.

If your server details include TLS, a transport, Host, Path, or other options, enter each one as specified. The server address and the name used for TLS may serve different purposes; don’t change one just to make them look the same. If any details are missing, verify the original information before proceeding. That’s easier to troubleshoot than a server entry based on guesswork.

Have a share link or QR code? Verify the imported details

If you have a QR code, use Scan QR Code and grant camera access if prompted. If you have a share link, copy its complete contents and use the app’s clipboard import option. A successful scan or parse only means the details could be read; it doesn’t mean the server is currently reachable. After saving, check the protocol and address to avoid using outdated information or selecting the wrong entry.

Step complete: A clearly identified server entry appears in Home, and you’ve selected the one you want to use. Don’t import more entries yet; next, confirm Global Routing. For details on updating subscriptions, managing multiple groups, and backups, see the Subscribe section of the Server Management Manual.

02Global Routing: Choose how traffic is routed

The server determines where you connect; Global Routing determines how connections are routed. Return to Home, tap Global Routing, check the current selection, and choose a mode for your needs. Start with these three: Config, Proxy, and Direct. They are routing modes, not different servers, and they don’t change whether an existing subscription is valid.

Config: Apply the active configuration’s rules

Use Config when you need rule-based routing. The app uses rules in the currently enabled configuration to apply policies such as PROXY, DIRECT, or REJECT, so not all connections necessarily go through the selected server. In Config, distinguish between a file that appears in the list and the file that is currently enabled. Importing a file without enabling it does not mean its rules are active.

If some websites work and others don’t in Config, note the difference before assuming your subscription is invalid. Rules are generally evaluated from top to bottom, and the matching rule determines the policy; FINAL handles traffic that hasn’t matched an earlier rule. Check the active rules to see whether a domain uses DIRECT or PROXY rather than relying only on the connection switch.

Proxy: Check the proxy route

Proxy can be a straightforward way to test the selected server for the first time. It checks proxy traffic that the app normally handles, reducing interference from standard rule-based routing. If you plan to use Config day to day, first verify the basic connection in Proxy, then switch to Config and test the same website. Proxy cannot fix incorrect server details, and it doesn’t guarantee that every network action in every app will be handled the same way.

Direct: Compare with a direct connection

Direct connects without using the proxy server, so it isn’t a way to test whether that server works. If a website opens in Direct but not Proxy, the two routes behave differently; check the selected server and related settings. Conversely, a failure in Direct doesn’t mean the device has lost all network access. Always compare using the same test destination.

Step complete: You can identify the selected mode and explain why you chose it. For an initial server check, start with Proxy; use Config when you have specific rules to apply. After choosing a mode, return to Home and approve the connection. For more about rules and settings, see Feature Guide.

03Home: Connect and approve the VPN configuration

In Home, check once more that the selected entry is the server you just imported and Global Routing is set to the mode you chose. Then turn on the connection switch at the top of the screen. The first time you connect, iOS may ask whether Shadowrocket can add a VPN configuration. This authorizes the system to manage the network configuration; it isn’t a subscription payment prompt or a check that the server is working.

Check the app name in the system prompt and confirm the request came from Shadowrocket, which you just opened. Tap Allow and complete any device verification required by the system. Finish verification in the device’s system interface; you don’t need to share your device passcode with anyone to follow this guide or import a subscription. Once approved, return to Shadowrocket and check whether the switch stays on and the app shows a connection status.

If you previously denied the configuration request or the switch turns off immediately, first check whether there’s a pending system prompt. If needed, check the VPN configuration status in system Settings, then return to the app and try again. Settings paths vary between system versions, so follow the menus shown on your device. Don’t remove an unfamiliar managed configuration just to test the connection.

If another VPN connection is active on your device, check which one is currently in use before testing Shadowrocket. For your first connection, leave On Demand unchanged. Automatic connection triggers add another variable; configure them only after you’ve verified that manual connection and disconnection both work.

Step complete: System approval is complete and the app’s connection switch stays on. This confirms that the local connection process has started; a VPN icon or an enabled switch does not prove that remote access is working. Verify it with a real request in the next step.

04Connectivity Test: Verify with real-world access

In Home, use Connectivity Test to check the server, then switch to Safari and open a website you normally use and are permitted to access. The test result and page load reflect different parts of the process: the test helps assess whether its target is reachable, while the page load shows the result of your actual visit. One successful test does not mean every website, protocol, and rule is working correctly.

Check that the page loads fully and that its links work; don’t rely only on a title or image that may be cached. Reload the page or open a page on the site you haven’t visited before. An old page that still displays can be misleading because of browser caching.

Then return to the app and check Global Routing. If Config is selected, use the connection logs to check which policy applies to the test domain: DIRECT, PROXY, or REJECT. A page loading successfully doesn’t necessarily mean it went through the proxy; a rule may have sent it direct. A failed page could also mean the domain matched REJECT rather than the server disconnecting.

To compare modes, keep the same server and test website, change only one variable by switching between Config and Proxy, then make the request again. If Proxy works but Config doesn’t, first check the active configuration’s rules and DNS settings. If both modes fail, return to the server and basic connection steps instead of rewriting the entire configuration.

Changes in Data can help indicate that the app has handled traffic, but traffic records alone don’t prove that the target website returned successfully. For a more reliable check, compare the switch status, actual page load, selected mode, and relevant connection logs. The details should make sense together.

Step complete: The website loads as expected, and you can explain which route it takes in the selected mode. After testing, restore the mode you plan to use day to day. If an issue appears after changing networks or servers, repeat this step; there’s no need to start over with purchase and installation.

05Common problems: Check where the failure occurs

Change one thing at a time while troubleshooting, and note the results before and after each change. Record the selected server, Global Routing mode, test website, whether a system prompt appeared, and where the failure occurred. Don’t record or share full authentication details. This makes it easier to retrace your steps and prevents confusion after multiple setting changes.

No server entry after import

First, return to Step 1 and confirm the link type. If you used an account page as a subscription URL, the app may be able to open it but won’t retrieve the correct server data. Check that you copied the entire link, including its beginning, end, and query parameters, and that there are no extra spaces. Confirm the subscription is still valid. For manually entered details, make sure you saved the entry instead of simply leaving the edit screen. Don’t keep adding the same link to work around an error message.

The connection switch won’t stay on

First check system approval and the local configuration status. Confirm that you completed the VPN configuration prompt, and check whether another connection is affecting the current state. The local connection process isn’t complete yet, so changing DNS or rules is unlikely to help. If the device is managed, follow its management requirements and don’t remove configurations arbitrarily.

The switch is on, but all tests fail

Check that the correct server is selected, then verify that its address, port, protocol, and authentication fields match your existing details. A subscription updating successfully doesn’t mean every server in it is usable. Review Connectivity Test results alongside an actual request. If your own subscription includes another server you know works, keep the same mode and test website and change only the server for comparison. Confirm entry validity using your own service information.

Connectivity Test passes, but websites won’t open

First, remember that the test target and the website are different. Then check whether the issue occurs only in Config. DNS resolution, rule matches, remote responses, and differences in test methods can all contribute. Before changing settings, note the current values and check whether DNS is customized or the configuration handles the domain specially. Don’t change DNS, the server, and the entire configuration at once before identifying the issue; otherwise, you won’t know which change mattered.

Some websites or features don’t work

Keep a working page as a comparison, then check the domains used by the failing page and the policies they match. A website may request content from multiple domains, so if the main page loads but images or sign-in fail, check the related requests rather than only the domain in the address bar. Comparing Proxy and Config can help narrow down the cause, but confirm it against the connection logs and configuration.

The connection starts again after disconnecting

Check whether On Demand is enabled and whether its triggers match your current network. If automatic connection is enabled from the start, a reconnect after manual disconnection can look like a faulty switch. First return to a state where you can observe the connection manually, then confirm that connecting, browsing, and disconnecting work as expected before setting up On Demand.

This page covers your first setup and helps pinpoint common issues. Use the links above to return to the relevant step; there’s no need to reinstall the app repeatedly or change every setting before identifying where the failure occurs.