Official Guide / First-Time Setup
Follow the steps in order: add a server, choose a mode, connect, and verify. Get a connection you can retest working first; adjust rules and automatic connection settings afterward.
Step 01 / Add a Server Entry
Choose one of these methods. If you have a subscription link, import it first. Enter server details manually only when you have individual server parameters.
Open Shadowrocket, go to Home, and tap the add button to open Add Server. Under Type, choose Subscribe, then enter the full subscription link in the URL field. Subscription links often contain account-identifying parameters. Copy the entire link from start to finish, without chat quotes, explanations, or line breaks. Do not use your provider’s account management page URL as the subscription link.
Use the app’s Save or Done action to return to Home, then wait for the subscription to load. Check that server entries appear under SERVER. A successful import means servers are available to select—not just that the link was accepted in the input field. If you see a subscription name but no servers, check the update result and make sure the link is complete. Avoid adding the same link repeatedly and creating duplicate groups.
Updating a subscription fetches the list provided by your service provider; it does not restore an app purchase or guarantee that a server can connect. If entries are already listed, confirm the imported group and the server you want before continuing. If the link cannot be parsed or the list is empty, go to Step 5 to troubleshoot. Leave the rules unchanged for now.
If you have a server address, port, and authentication details, select the correct Type in Add Server, then fill in the fields shown. Fields vary by protocol; two entries having a password does not mean they use the same type. The screenshot shows fields for Host, Port, Password, and Method. Other types may show different fields.
Enter the server domain name or IP address in Host, without adding a webpage path. Enter the port number provided to you in Port. Check Password and Method exactly, including any leading or trailing spaces introduced when copying. For UUID, TLS, SNI, or transport settings, use the server details you already have rather than guessing. Save, return to Home, and make sure the new entry appears. Add a note that makes it easy to identify.
If you have a QR code, use Scan QR Code in the app and allow camera access when prompted. If you use the in-app clipboard import option, first make sure the clipboard contains a complete share link, not a screenshot description or webpage text. After scanning or importing, return to the list and check the entry type, address, and group. Don’t treat a successful scan as a substitute for checking the details.
Import from Cloud JSON, shown in the screenshot, is a separate import option—not a general-purpose field for subscription links. For initial setup, use the method that matches the information you have. See the Glossary for the difference between subscriptions, individual share links, and Config files. For bulk organization and update strategies, see Managing Subscriptions and Servers.
Step complete when: The target server appears in Home under SERVER, and you can verify where it came from and check its details. Next, choose when those servers should be used.
Step 02 / Choose How Traffic Is Handled
Choose a mode before connecting. Selecting a server in the list does not mean all traffic will use it.
On Home, tap Global Routing to check the current selection. This guide covers three modes: Config, Proxy, and Direct, shown in English in the app. After making a selection, return to Home and check the value beside Global Routing again to confirm it changed.
Choose Config if you have a configuration file that you know works. Then open Config and confirm the selected file is the one you intend to use. Its rules determine whether requests use a proxy, go direct, or follow another policy. If the file references policy groups, check which servers those groups actually use. A subscription list alone does not mean you have routing rules suited to your needs.
The official screenshot on the right shows the Config editor, with General, Rule, Hosts, URL Rewrite, and HTTPS Decryption. You don’t need to edit each section for your first connection or add HTTPS Decryption settings just to test. Keep the configuration as it is until you understand what the current rules do. Add Rule opens the rule editor; it is not for adding a server.
If you’re not sure your configuration is set up correctly, temporarily choose Proxy to test the route through the selected server, reducing the variables introduced by rule matching. This mode does not guarantee server quality. Incorrect server details, failed authentication, or a network issue can still prevent access. After testing, switch back to Config and retest if you normally route traffic by rules.
Direct handles traffic without using a proxy. So even when the connection switch is on, requests may not be using a proxy server from the list. Use this mode to compare basic network behavior, not to test whether a proxy server works. Note the original mode before switching and restore it after testing so you don’t mistake direct-connection results for rule behavior later.
For now, focus on understanding the differences between the modes. Read the specific configuration to understand rule order, policy names, and matching scope. For details, see the Global Routing section. Don’t replace an entire configuration by copying a few keywords if you’re not sure what the rules are meant to do.
Step complete when: You know whether Config, Proxy, or Direct is selected. If Config is selected, you know which configuration is active. Next, turn on the connection.
Step 03 / Connect
Your first connection may require system authorization. After approving it, check the app’s status and try accessing a page.
Return to Home, select the entry you want under SERVER, and check the selection indicator. If you have multiple subscription groups, make sure similarly named entries aren’t from different groups. If Config is selected and the configuration uses policy groups, check the actual target for each group. Tapping an entry on Home may not override policies specified in the configuration.
After checking Global Routing, turn on the connection switch at the top of the screen. The official screenshot shows Not Connected before connecting; it helps identify the control and does not show your live status. After tapping, check the status on your device rather than expecting it to match the screenshot exactly.
The first time you connect, your iPhone or iPad may show a system prompt to add a VPN configuration. This authorization allows the app to establish a system-level connection; it is not a field for your server password. Confirm that Shadowrocket initiated the request, review the prompt, and approve it as instructed. Complete device passcode or other device authentication if requested. Do not enter your server password on the device authentication screen.
If you cancel authorization, the app cannot establish a complete connection just because a server entry exists. Return to Home and try connecting again, then follow the system prompts. If the switch turns off immediately after authorization, note any message and work through Step 5. You don’t need to delete the app or rebuild all your subscriptions right away.
Keep the same network while testing; don’t switch between Wi-Fi and cellular, change servers, and change modes at the same time. If another feature is managing the device’s VPN connection, first check which connection configuration is active to avoid mistaking a configuration switch for a server failure. On managed devices, system policies may also affect authorization; follow your device’s management requirements.
When the connection status changes, don’t immediately enable On Demand or change more settings. A successful manual connection completes this step, but you still need to verify that it handles the requests you need. When you’re done, return to Home and turn off the switch. If you later need connections to start under specific conditions, learn about On Demand separately.
Step complete when: System authorization is handled, the connection stays on, and the selected server and mode haven’t changed unexpectedly. Next, verify using both test results and actual pages.
Step 04 / Check the Results
Test results, system connection status, and whether a webpage works are three different things. Check each one separately.
Check the Test First
On Home, tap Connectivity Test and wait for it to finish. The test method depends on settings such as Test Method in Settings. A failure with one test method does not prove that every real request will fail.
Then Check Access
Use Safari to open a familiar page, then open the page you actually need. Check that it loads and that you can continue using it—not just that cached content or a single test value appears.
After the test finishes, first check whether the target server returned a result. The value reflects performance under the current test conditions; it is not a speed guarantee and does not mean every website uses the same route. Results may vary by test method, network, and target. To compare servers, keep the test conditions as consistent as possible instead of ranking results from different times and methods together.
Next, use Safari to open a page that normally works and confirm basic browsing, then test the page you need. Reload if necessary so cached content isn’t mistaken for a successful new request. Once the page opens, try a real action, such as opening another section. Seeing only a title or a few cached images does not confirm that the entire connection is working.
With Config selected, different pages may match different rules, so one successful page does not validate the entire configuration. To check how a request is handled, compare the connection records visible in the app with the active rules, and look for whether it uses DIRECT or a proxy policy. The system VPN indicator cannot distinguish between these two routes, so don’t use it to conclude that every request went through a proxy.
If the test returns a result but a page won’t open, keep the current server and mode and move to the next step to check the target and configuration. If the test fails but the page works, check Test Method first; don’t delete a working entry right away. The goal is to find where the results diverge, not to stop as soon as one indicator looks normal.
Step complete when: The page you need works, and its traffic handling matches the selected mode and rules. Once the test passes, you can fine-tune your everyday setup. If it doesn’t, follow the steps below to narrow down the issue.
Step 05 / Change One Thing at a Time
Separate basic network, import, server connection, and routing issues. Don’t start by resetting all settings.
Turn off the connection on Home and open a page that normally works. If it still won’t load, check Wi-Fi, cellular service, or any network sign-in requirement first. Reconnect once your basic network is working. This comparison helps you avoid blaming every access issue on your subscription. Keep network conditions stable while testing.
If SERVER has no usable entries, check whether the subscription link is complete, whether it contains extra spaces, and what result appeared during the update. Subscription links may contain account credentials; don’t post the full link in a public discussion. Check service status, validity period, and account limits with your service provider. Repeatedly tapping update won’t fix an account-side issue.
For manually added servers, recheck each field starting with Type, then verify Host, Port, authentication, and transport settings. Don’t change only the password while overlooking the protocol type. If the original information is missing required fields, ask your service provider for complete details instead of combining parameters from another entry.
If the connection switch stays on but access doesn’t behave as expected, note the current configuration and mode, then briefly switch to Proxy and retest the same target. If it works in Proxy but fails in Config, focus on the active configuration, matching rules, and policy group targets. If both modes fail, check the server and network. Direct is only for comparing direct access; it cannot confirm that the proxy route works.
Open Settings and check Test Method to see which method produced the result. Don’t randomly change multiple options under Proxy, TCP, or UDP just to make a value appear. Adjust these settings only when you understand the issue and what each parameter does. After one change, return to Home and retest the same target to confirm that the change made a difference.
If the connection comes back after you turn it off, check whether On Demand has automatic connection rules that match your current network conditions. During troubleshooting, turn off On Demand to run a controlled manual test, then restore the conditions you need afterward. On Demand controls when a connection starts; it cannot fix incorrect server details.
If you still can’t identify the issue, review the diagnostic information available in Diagnostics. Record the network, mode, selected entry, and error message at the time the problem occurs. Before sharing anything, redact subscription URLs, passwords, UUIDs, account details, and identifiable access records. Share only the relevant details; they’re usually more useful than a screenshot of every setting.
For your next test, use the same server, mode, and target. Revert the last change if it didn’t help, then check the next item. This makes it easier to undo changes and identify the cause. For more common issues, see Troubleshooting. For subscription updates, organizing groups, deleting entries, and backups, see Managing Servers. Once these basic steps are complete, you can fine-tune rules and automatic connection settings for your needs.
Step complete when: You can identify which part of the setup is causing the issue and repeat the same test. After fixing it, return to Step 4 and verify access again.
