Official Manual / First Connection
Shadowrocket Setup Guide
Follow the steps in order: import, choose a routing mode, connect, and verify. This guide uses iPhone and iPad as examples. First establish a connection you can test, then move on to rules and everyday use.
Keep the app’s default settings for now, and don’t add On Demand or complex rules yet. If the menus differ from the steps here, look for the English setting names shown in the app rather than relying only on button positions.
Step 01 / Prepare the SERVER List
Add a Server or Import a Subscribe Link
Open Shadowrocket and go to Home. The SERVER section may be empty the first time you use the app. That means no connection details have been added yet; it does not indicate an installation problem. First, identify what you have: a subscription link that returns a list of servers, or details for one server, including its protocol, address, port, and authentication. Choose one method; there’s no need to add the same information twice.
Have a Subscription Link? Use Subscribe
In Home, tap the plus sign in the upper-right corner to open Add Server. Open Type and choose Subscribe. Paste the full subscription link from your service provider into the URL field. If the app shows a Remark field, enter a name that will help you recognize it. Before saving, check the beginning and end of the link and its query parameters. Watch for spaces, line breaks, or chat text copied along with it. Don’t use the address of an account management page as a subscription URL.
Tap Done to save, wait for the subscription to load, then return to Home and check the result. A successful import should show a subscription group and its server entries—not just a name. If the group appears but contains no servers, check whether your network can reach the subscription URL, whether the link is still valid, and whether the response uses a format supported by the app. Tapping the connection switch repeatedly won’t fill in missing subscription data; resolve the import issue first.
A subscription link may contain access credentials, so protect it like account information. Don’t share the full link or paste it into an unfamiliar website for conversion. To refresh it later, update the existing subscription. Adding the same link again can create duplicate groups, making it harder to tell which server is selected and which group you’re maintaining.
Have Details for One Server? Enter the Parameters by Type
If you have details for a single server, tap the plus sign to open Add Server, choose the correct Type, then fill in the corresponding fields. Shadowsocks, VMess, VLESS, Trojan, and other protocols use different authentication and transport parameters. Entering only Address and Port is not enough. Match the address, port, password or UUID, and any TLS, Server Name, or transport settings to the server details you have. Don’t guess at options your provider hasn’t specified.
After saving, return to Home and confirm that the server appears in the SERVER list. If you have a compatible QR code, use Scan QR Code to import it. After scanning, check that Type, address, and key parameters match your server details; don’t rely on the name alone. At this point, you’ve entered the information but haven’t connected yet. Next, choose Global Routing so you don’t mistake a routing issue for an unavailable server.
Step 02 / Choose How Requests Are Routed
Choose One of the Three Global Routing Modes
Return to Home, tap Global Routing, and check the selected mode. This setting determines how requests are routed; it doesn’t provide a server or replace server authentication. This guide usesConfig, Proxy, and Direct as the mode names. Use the labels shown in the app: Config, Proxy, and Direct. After choosing a mode, return to Home and check Global Routing again to confirm the change took effect.
| Mode | How Requests Are Handled | What to Check First |
|---|---|---|
| Config | Selects a policy based on the rules in the active configuration. | Make sure an active configuration is selected and that the policies referenced by its rules point to available servers. |
| Proxy | Generally routes connections through the current proxy policy. | Confirm the correct server is selected; use this mode to test the server connection first. |
| Direct | Connects directly to the destination without routing through the current proxy server. | Useful for checking your basic network, but it does not verify that a proxy server works. |
Use Proxy for the First Test
If you haven’t set up rules yet, you can temporarily choose Proxy to narrow down the issue: can the current server connect? This is a troubleshooting step, not a recommendation to keep this mode for everyday use. Even in Proxy mode, check the results of real requests; don’t assume that all system traffic always follows the same route under every condition.
If you already have a working configuration and want to route traffic by domain or address, choose Config. Note that two similarly named options serve different purposes: Config in Global Routing is a routing mode, while the Config page in the app manages configuration files. Importing a Subscribe link gives you a server list; it doesn’t necessarily provide a rules configuration suited to your needs. Check them separately.
When Using Config, Confirm the Active Configuration
Open the Config page and make sure the configuration you want to use is set as current, then return to Home and choose Config. Rules are matched in order. The matching rule and its assigned policy both affect the route. Don’t paste in a batch of unfamiliar rules just to connect for the first time. For details on rule order, policy references, and DNS, see the complete manual. For now, focus on a repeatable connection test.
Direct can help you check your basic network. If a website that should be directly accessible still won’t open in Direct mode, check your device’s network before changing server parameters. Once you’ve chosen a mode, select a server and turn on the connection.
Step 03 / Select and Authorize
Select a Server in SERVER, Then Connect
In the SERVER list on Home, find the server you want to test and tap the dot beside it. Confirm that the selection indicator is next to the intended entry. A server name is just a label; it doesn’t confirm that the parameters are correct, that the server is available, or that requests are following the intended route. For your first test, stick to one entry with complete, known details. Switching between servers without keeping track makes it difficult to link each result to the settings used.
Select the Entry Before Connecting
Check Global Routing and the selected server, then turn on the connection switch at the top of Home. When disconnected, you may see a status such as Not Connected. After switching on, wait for the status to update and check whether the connection stays active. Opening server details to edit parameters and tapping the dot to select a server are different actions. If you only opened the details page without selecting the entry, the connection may still use the previously selected server.
When using Config, remember that rules may reference a specific policy or policy group; not every request necessarily uses the server you selected on Home. To test one server by itself, temporarily use Proxy for comparison, then switch back to Config and check the routing. Don’t change server parameters, configuration files, and DNS at the same time, or you won’t know which change caused the result.
About the System Prompt to Add a VPN Configuration
The first time you connect, iOS may ask whether Shadowrocket can add a VPN configuration. This connection permission lets the app handle traffic through the system’s networking mechanism and is separate from your existing subscription details. Once you’ve confirmed that the prompt was triggered by your action and names Shadowrocket, tap Allow and complete device authentication as requested. Return to the app and check that the switch and connection status remain stable.
If you dismissed the system prompt earlier, importing the subscription again won’t help. Server details and system permissions are separate steps. Try turning on the connection again and follow the system prompts to check VPN configuration and permissions. If your device is subject to management policies, check those requirements first. Avoid having another VPN connection compete for the system network tunnel; keep only the connection you’re testing active.
A VPN status indicator in iOS or an enabled switch in the app only shows that the connection tunnel has started. It doesn’t by itself confirm that a website is reachable, authentication is correct, or rules are routing traffic as expected. After granting permission, don’t add more rules yet. Go straight to the verification steps and check with a real request.
Step 04 / Check the Results
Run Connectivity Test and Verify Routing
Once the connection is stable, tap Connectivity Test in Home, wait for it to finish, and review the result. The test reflects a particular target under current network conditions. It can help identify an obvious connection failure, but it doesn’t confirm that every website, protocol, or app is working. After a successful test, try a real request. If the test fails, consider how broadly the issue occurs before deciding what to check.
Compare Before and After Using the Same Target
Open a browser and visit a website you actually need to use, with an address you know is correct. Check that the main page and essential resources load. If you can still see an old page, it may be cached and doesn’t prove that a new connection worked. Reload the page or open another page on the same service to make sure a real request is sent. For services that require sign-in, distinguish network failures from account permission messages.
For a useful comparison, keep the network, server, and test target the same and change just one setting. For example, compare Proxy and Config with the same server, or keep Proxy unchanged and test another server you already have. Don’t switch Wi-Fi, change servers, edit TLS, and update the configuration all at once, then try to identify the cause from a single result.
For Config, Check the Rules and Policies
If you plan to use Config for everyday routing, first confirm the basic connection works. Switch to Config and repeat the same test. Open the app’s request log or diagnostic view and check the destination domain, matched rule, and final policy. A website opening doesn’t necessarily mean it went through a proxy; the rules may have sent it DIRECT. Conversely, a rule using PROXY only works as intended if that policy points to an available server.
The upload and download figures on the Data page can provide useful context, but rising numbers don’t prove that a particular request was routed as intended. Background activity can also generate traffic. A better approach is to match the time of your action and the test target to the corresponding log entry, then check how that request was handled. For a closer look at rules, see the complete manual. You don’t need to adjust all the statistics and diagnostics settings when you’re just getting started.
If Connectivity Test, a real request, and the expected routing all check out, keep the current settings. Before making changes later, note the working conditions: network, server label, Global Routing mode, and active configuration. If something still fails, troubleshoot in the order below instead of deleting everything and starting over.
Step 05 / Change One Variable at a Time
Troubleshoot Common Issues by Failure Point
First identify where the problem occurs: the subscription won’t import, the connection switch won’t stay on, the test fails, or only some websites are affected. Each points to different checks. Keep any information that still works, change only one thing at a time, and repeat the same test. Even if that doesn’t solve the problem, you’ll know whether the change made a difference.
No Servers After Import? Check the Subscription Content
If the SERVER list is empty, revisit the subscription settings and check that the URL is complete and isn’t an account management page address. Confirm that your device’s basic network is working, then update the existing subscription. The URL may be valid but return an error page, or your service provider may need to confirm access or the expected format. Your app purchase, VPN permissions, and subscription response are separate; changing Global Routing won’t fix an empty list.
The Switch Won’t Stay On? Check Permissions and Parameters
If the connection stops immediately after you turn it on, check the app’s message first. Then confirm that you’ve granted permission for the system VPN configuration, that device management policies aren’t blocking it, and that no other VPN connection is active. Next, verify the selected server’s Type, Address, Port, and authentication details. Fill in TLS, Server Name, and transport path settings only when your server details specify them; leaving a field blank and entering an incorrect value are not equivalent. An incorrect device date or time can also affect certificate validation, so correct it first.
Connected but the Test Fails? Check the Network and Server Separately
Disconnect and make sure your device’s basic network can reach a website known to be accessible. If Wi-Fi requires web authentication, complete it first. Once the basic network is working, reconnect, keep Proxy and the same test target, and check the result. If you have another server, compare it while keeping all other conditions unchanged. One failed test doesn’t mean you need to rebuild all your server details.
If the log shows an authentication error, connection timeout, or certificate issue, check the related parameters. Don’t disable certificate validation or weaken security settings just to clear a warning. For server-side requirements you can’t confirm, ask your service provider for accurate details, then update the relevant fields.
Proxy Works but Config Doesn’t? Check Routing First
If Proxy works but Config doesn’t with the same network, server, and destination, check the active configuration, rule order, policy references, and DNS before considering another app purchase. Make sure the expected file is selected on the Config page, then check which rule matched the failed request and whether it sent traffic to DIRECT, REJECT, or an unavailable policy. Start with the rule that actually matched; don’t delete unfamiliar rules in bulk.
If only one service is affected, check whether it uses multiple domains or a separate sign-in endpoint, and whether your account status could be involved. Different DNS settings can also cause domain resolution and connection results to differ, but avoid adding multiple DNS setups during initial troubleshooting. For more issue-specific guidance, see the FAQ. To learn about configuration files and ongoing maintenance, continue to the complete manual.
Your first-time setup is complete when the SERVER list contains a valid entry, Global Routing matches your goal, system authorization is granted, the connection stays active, and a real request succeeds. If an issue comes up later, check these in the same order. That usually makes it easier to find what changed than repeatedly deleting and reimporting everything.