STEP 01 / INPUT
Add Server: Add a Server or Import a Subscription
Open Shadowrocket and go to Home. This screen lets you view server entries, select the server to use, and control the connection. For first-time setup, enter your connection details before turning on the switch. Identify what you have: a subscription link that can refresh a group of entries, or the address, port, and authentication details for a single server. The two use similar entry points, but their fields mean different things.
Have a subscription link? Choose Subscribe
In Home, tap the plus button in the top-right corner to open Add Server. Open Type and choose Subscribe. Paste your complete subscription link into the URL field, add a recognizable note, and save. When copying the link, watch for leading or trailing spaces, line breaks, or punctuation from a chat app. Keep the full URL, including any query parameters; do not stop copying before the first question mark.
After saving, return to Home and wait for the subscription to load. When it loads successfully, you should see a subscription group and its server entries. Expand the group, then tap the server you plan to use and confirm it is selected. Saving a subscription record does not mean the server list was retrieved successfully. If you see only the group name and no entries, check the load result before continuing.
Refreshing a subscription retrieves entries from an existing link; it does not fix the servers themselves. If the first attempt fails, check that the address returns subscription content the app can recognize, rather than an account-management webpage. Ask the original provider to check the link status, but never post a complete link containing credentials in a public discussion. If a list is already present, confirm that the selected entry still belongs to a valid group.
Have details for one server? Fill in the fields for its Type
For a single server, start in Add Server and choose the protocol specified in your details under Type, such as Shadowsocks, VMess, VLESS, or Trojan. Then fill in the server address, port, and corresponding authentication fields. Choose the protocol based on the details provided, not on a similar-sounding name. Passwords, UUIDs, encryption methods, and transport settings are not interchangeable; use your original connection details.
Enter the server domain or IP address in the address field and the specified number in the port field. If your details include TLS, a server name, or a transport path, check those too; a complete address and port do not necessarily mean the setup is complete. If you have a server share link or QR code, import it in its supported format. After using Scan QR Code, check the imported details—especially Type and authentication fields—to make sure the QR code was intended for this purpose.
After saving and returning to Home, add a recognizable note to the entry and select the server. Check just two things: the entry appears in the list, and the selected entry is the one you intend to use. To understand protocol fields, see the protocol technical reference; you do not need to adjust every advanced setting before your first connection. Once the details are entered, choose how requests should be routed through these entries.
STEP 02 / ROUTING
Global Routing: Choose Config, Proxy, or Direct
Tap Global Routing in Home to check the current mode. This choice determines how requests are handled after the connection is established; it does not select the server protocol. The three modes are Config, Proxy, and Direct. Importing a server does not tell you whether the current configuration suits your needs, so check the mode before turning on the connection.
| Mode | How it handles traffic | First-time setup check |
|---|---|---|
| Config | Uses rules in the current configuration to select a policy. | Check the configuration in Config and its final policy. |
| Proxy | Routes traffic in Proxy mode to check forwarding through the selected server. | Confirm the intended server is selected in Home. |
| Direct | Uses Direct mode; it does not show that server forwarding is working. | Useful for comparing access with the device's regular network connection. |
For everyday rule-based routing, check Config first
To use rule-based routing, open the Config screen and confirm which configuration is active. Open it and check its contents, paying particular attention to the rules in [Rule] and the final policy. A server subscription provides server entries; a configuration describes how traffic is handled. They are not the same thing. After importing a subscription, check that the active configuration suits your needs.
Rules are usually checked in order, and the policy for the first matching rule is applied. PROXY, DIRECT, and REJECT specify different actions. FINAL is the fallback when no earlier rule matches. You do not need to write rules when getting started, but understand that a site opening directly may be intentional under the configuration—not a sign that the connection has failed. Do not clear the entire configuration just to restore access to one site.
Test the server first: Keep the comparison conditions clear
To check whether the server you just added works, temporarily choose Proxy and test the same destination. When you're done, switch back to Config for your normal use. Direct provides a comparison with your local network: if Direct works but Proxy fails, focus on the server or its settings. If both modes fail, also check the device's network connection and the destination site.
After changing modes, return to Home and check the current Global Routing value. Change only one thing at a time—either the mode or the server. If you change the server, configuration, and DNS all at once, you won't know which change made a difference. Once you've confirmed the mode, keep it as is and continue to the connection steps.
STEP 03 / CONNECT
Home: Turn on the connection and authorize it in iOS
Return to Home, confirm the selected server is the one you checked, and make sure Global Routing shows the intended mode. Keep these three states distinct: details saved, server selected, and connection switch on. Seeing a server in the list does not mean traffic is being handled in the selected mode. Once the first two checks are complete, turn on the connection switch at the top of Home.
The first VPN configuration prompt
When you connect for the first time, iOS or iPadOS may prompt you to add a VPN configuration. Read the app name in the prompt and make sure it comes from Shadowrocket, which you just opened. Follow the system instructions to allow the configuration and complete any required device authentication. This system authorization allows the app to handle network traffic; it is not a server account login, and you should not enter your subscription password here.
If you dismissed the prompt earlier, the connection may not continue. Return to the app and start the connection again, then follow the system prompt to authorize it. The wording may vary based on the device language and system state. You do not need to look for a specific button label; confirm the prompt's purpose and which app requested it. Check the App Store page for the device's system requirements.
Check the app after authorization
After authenticating, return to Home and check whether the connection switch stays on. The device may show a VPN status indicator, but its position varies with the system layout, so do not rely only on whether an icon appears in the status bar. A switch that stays on means the connection process has started; it does not prove that the remote server, domain resolution, and every rule have been verified.
If the switch turns off immediately, first check that system authorization is complete and that no other VPN configuration is handling the connection. For first-time setup, also check On Demand so automatic connection conditions do not conflict with manual actions and make it seem like the connection keeps turning back on. Do not rapidly toggle the switch. Wait for the current state to settle before deciding whether to try again.
If the system shows a specific error, note its wording and when it appears—for example, “stops immediately after authorization” or “the switch stays on, but webpages fail.” These details are more useful than simply saying it does not work. If you save a record, hide server addresses, authentication fields, and credentials in subscription links. Once the switch stays on, test with actual requests rather than treating the status indicator as the end of setup.
STEP 04 / VERIFY
Connectivity Test: Check access and rules
After turning on the connection, run Connectivity Test from Home to check the server's test results. This can help identify unreachable entries and compare responses under the same network conditions, but results depend on the test method and target. A response only shows that this probe received a response; it does not prove that all webpages or protocol traffic are working.
Make a new webpage request
Open Safari and visit a familiar site you need to use, then refresh the page or open a new one. Do not rely only on a page that was already open; cached content may still appear after the connection changes. Check whether the page loads fully. If you see only a title or some images, count that as a partial request failure rather than calling the entire connection successful.
If you are using Config, compare one destination you expect to go through the proxy with one you expect to connect directly. This checks whether rules are behaving as intended; it does not prove that all traffic follows the same route. A region shown by an app or website may be affected by your account, cache, or location permissions, so do not use it as your only connection check.
Find the request in Data
Return to Shadowrocket and check Data for the connection record corresponding to your recent request. If the details you need are not being recorded, enable the relevant recording option in the interface and make the request again. Start by locating the request by time and destination domain, then check the policy used and any visible match details. The information available varies by screen; rely on what the current interface shows.
For example, if a domain expected to use the proxy instead shows DIRECT, check the rule order in Config rather than immediately re-entering the server password. If a request uses PROXY but keeps failing, check the selected server, authentication fields, and DNS resolution. If you see REJECT, first confirm whether the active configuration is intentionally blocking that request. Use records to understand the result; do not change policies at random just to make the records look consistent.
After a successful verification, note the selected server, Global Routing mode, and configuration name. If a problem occurs later, compare it with these verified settings. When testing is complete, manage the recording feature as needed. Before sharing records, remove private destination details and all credentials. That completes the first-connection workflow; troubleshoot later issues based on where they occur.
STEP 05 / CHECK
Common failure points: Check each step in order
Start troubleshooting at the earliest step where something went wrong. If no server list appears, stay on the import step. If the switch will not stay on, focus on the connection and authorization. If only one site fails, check the destination request, DNS resolution, and rules. Change one thing per attempt and repeat the same test request so you can compare results.
Import failed: Check the link and content type
Return to the subscription entry in Add Server and check that Type is Subscribe, the URL is complete, and it has no extra spaces or punctuation. If the response is actually a login page, error message, or empty content, the app cannot use it to create a server list. Do not enter a subscription URL as a server address, or mistake a single-server share link for a refreshable subscription. If you are unsure about the format, ask the original provider what the details are for.
Server unavailable: Check the original details first
If Connectivity Test keeps failing, first confirm that the device can access the internet with the connection turned off. Then check the selected entry's address, port, protocol, and authentication details. For a manually added entry, compare each field with the original details. For a subscription entry, check that the subscription refreshed successfully and that the selected entry is still valid. Changing the protocol repeatedly rarely fixes an authentication mismatch and can obscure the original issue.
Switch is on but you cannot access sites: Check the mode and DNS
First check whether Global Routing is still set to the mode you expected during testing. In Direct mode, results do not show that server forwarding is working. In Config mode, check whether the destination actually matches PROXY. Keep the server unchanged and temporarily test in Proxy mode to help distinguish a rules issue from a server issue. Restore your usual mode after testing.
If the probe gets a response but a webpage says the domain cannot be found, check the DNS settings in the active configuration. First confirm which Config is in use, then check whether its resolution settings work on the current network. Do not replace several addresses at once just because you see a DNS error. Keep the original values, change one setting, and retry the same domain. DNS resolution and server forwarding are separate steps and should be checked separately.
Some sites fail: Check the match before changing rules
If only some destinations fail, find their requests in Data and compare them with the rule order and FINAL policy in Config. A webpage may request several domains, so a homepage might load while its images fail because the requests match different rules. Identify the failed request's domain and policy before deciding whether to change a rule. Do not replace the entire ruleset with one policy instead of diagnosing the issue.
For more troubleshooting, browse the FAQ by symptom. For help understanding protocols and settings, see the technical reference. To restore a purchase after reinstalling on a new device, see the restore purchases guide. Reinstalling the app does not restore your configuration or connection details, so make sure you have saved them before proceeding.