Shadowrocket Setup Guide

Identify the Type of Information You Have

Open Shadowrocket, go to Home, and find the SERVER section and Add Server. Check the information you have: if it is a link that updates a server list, use Subscribe. If it consists of separate details such as Host, Port, and Password, add an individual server. Don't paste an entire subscription link into Host or guess the protocol based on how the link looks. If you're unsure, check the instructions from your service before continuing.

Have a Subscription Link? Choose Subscribe

Open Add Server, tap Type, choose Subscribe, and enter your complete subscription link in the address field shown for that type. After pasting, check for extra spaces, line breaks, or quotation marks at either end. Keep any parameters after the question mark in the URL. Once you confirm the link is complete, save it and wait for the list to load. Return to Home and check for the corresponding group and server entries. Saving a subscription link doesn't mean the list loaded successfully. If the list is empty, troubleshoot the loading failure before turning on the connection.

A subscription update retrieves the content currently returned by that address. After the first successful import, update it from the actions menu for that subscription entry; you don't need to add the same address again. If an existing subscription still works, keep its entry while making changes so you can restore it if needed. Subscription links may contain access credentials. Cover the entire link and any identifying parameters in screenshots or when describing an issue to someone else.

Have Server Details? Fill In Add Server One Field at a Time

In Type, choose the protocol that matches your details, then check Host, Port, and the identity or encryption fields required by that protocol. The official screenshot shows a form with Password and Method; this doesn't mean every protocol uses the same fields. Fill in Shadowsocks, VMess, VLESS, Trojan, and other types using their respective details. If you see options for TLS, transport, or other settings, match them to your original information rather than copying fields from a screenshot of another type.

Host usually takes a server domain name or address, and Port takes the corresponding port. Don't append a web page path to Host. Copy Password and other identity fields exactly, preserving uppercase and lowercase letters. If you have a scannable server QR code, import it with Scan QR Code, then check Type and the key parameters. Import from Cloud JSON is a separate import option, not the same as Subscribe. After saving, return to Home and make sure you can select the entry before choosing a mode.

After adding a server, return to Home and open Global Routing. Distinguish between the three modes: Config, Proxy, and Direct. Changing modes doesn't correct server details or add a new server. Before your first test, note the current selection and change only one thing at a time so you can tell whether a result came from the server, mode, or rules.

Config: Handle Requests Using the Active Configuration

With Config selected, requests are handled according to the rules and policies in the active configuration. Open Config to check which file is in use, then open that configuration and review Rule. General, Rule, Hosts, URL Rewrite, and HTTPS Decryption in the screenshot are separate sections of the configuration editor; Add Rule adds a rule. You don't need to edit each section just to get connected for the first time, and you shouldn't enable settings unrelated to your current goal.

Rules are generally matched in order, and an earlier match may determine how a request is handled. DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches IP address ranges, and FINAL handles requests that don't match earlier rules. PROXY, DIRECT, and REJECT are different handling policies, not server names. When troubleshooting a page, consider its domain, rule order, and final policy—not just whether a particular rule exists.

Proxy: Compare the Server Connection

Proxy handles traffic using that mode and can be useful for a simple connection test after you verify the server details. If the same server works in Proxy but a page fails in Config, focus on the configuration, rules, and DNS resolution. This can narrow down what to check; it doesn't mean Proxy is right for every situation. Restore your preferred mode after testing.

Direct: Don't Mistake It for a Proxy Test

Direct accesses sites without using a proxy. If a page opens in Direct, that doesn't prove the server you just added works. Check Global Routing before connecting so you don't mistake a Direct result for a proxy result. An existing configuration file is also different from a Subscribe entry: Subscribe mainly retrieves a server list, while Config handles configuration and rules. Importing a subscription doesn't mean you've switched to a rules file. For more on how matching works, see Features and Settings; for specific issues, see Troubleshooting.

Return to Home and select the server you want from the SERVER list. Make sure the selected entry is the one you intend to use. If the list has multiple groups, check the name and source to avoid choosing an old entry by mistake. Then check Global Routing again: with Config, confirm the configuration is selected; with Proxy, confirm the server you selected is the one you're testing. Once both are correct, turn on the switch at the top of Home.

What to Do When the System Prompt First Appears

The first time you connect, the system may ask to allow adding a VPN configuration. This gives the app permission to create a network connection configuration; it is not another app purchase and doesn't import a server automatically. Confirm that Shadowrocket initiated the prompt, then follow the system instructions to allow it and authenticate on your device. If you dismissed the prompt, return to Home and try turning on the switch again to see if the permission flow reappears.

After granting permission, return to the app and check whether the status at the top changes from Not Connected to a connected state and stays there. The system VPN status can help confirm that a connection configuration is running, but it can't establish by itself that the server, DNS, or a particular web page is working. The switch shows the client's connection state. You'll still need to verify that requests work as expected.

Don't Change Other Settings Yet

Keep the current server, Global Routing mode, and configuration unchanged while you run Connectivity Test and try to access a real page. During initial troubleshooting, temporarily stop other configurations managing VPN connections, then reconnect. This helps prevent a system connection switch from making the current entry appear to fail. Don't switch servers, import a new configuration, and change DNS all at once. When several things change together, even if the connection starts working, it's hard to know why.

If the switch turns off immediately, keeps dropping, or the system prompt wasn't completed, address permission and connection status first rather than editing Rule. If you need to change important connection details, turn off the switch, save the change, then reconnect and test. The active connection may not use newly saved parameters until you reconnect, so starting a new connection makes the results easier to interpret. Then check whether your actual requests work.

Empty List: Check the Import and Update First

If no servers appear after saving a Subscribe entry, turn off the connection and confirm that your current network can access basic services. Then check that the link is complete, the subscription is still valid, and the update didn't return an error. Changing Global Routing usually won't restore entries missing from an empty list. Don't keep adding the same link and creating duplicate groups. Keep one entry to check, then ask your existing service's support team about the returned content and link status.

Entry Is There but Won't Connect: Check Details and Permission

Open the entry's edit screen and compare Type, Host, Port, identity fields, Method, and any required TLS or transport settings against your original information. Some fields appear only for certain Types; don't switch protocols just because a field shown in a screenshot is missing. Then confirm that system VPN permission was granted and that another connection configuration hasn't taken over. If only one server fails, check that entry first rather than replacing the entire Config.

Test Works but Pages Don't: Check Rules and DNS

First make sure the mode isn't Direct, then compare access in Proxy and Config using the same server. If only one domain fails, check whether it matches REJECT, whether an earlier rule takes precedence, and whether the final policy is what you expect. DNS failures can also cause pages to fail even when latency looks normal. Check the active configuration's DNS settings and any visible error; don't keep cycling through DNS options just because you see a timeout. See Troubleshooting for more detailed scenarios.

Connection Changes Automatically: Check On Demand

Open Settings and check whether On Demand is enabled and what conditions it uses. It controls when a connection is established and can affect testing. For an initial manual test, make sure its behavior fits your goal so automatic connections don't complicate the results. Test Method in Settings affects what the test result means; after changing it, don't compare the new and old values as if they were equivalent. You don't need to change TCP, UDP, and other sections all at once when a first test fails. Let the specific symptoms guide what to check.

Keep Diagnostic Information Instead of Clearing the Configuration

For further troubleshooting, open Diagnostics in Settings and review the available information. Record the error message, when it occurred, and the mode in use. Before sharing the record, check for server addresses, subscription links, or credentials and redact them. Keep the original configuration and note each change; if a test fails, revert the last change before trying another. For App Store access, restoring purchases, and purchase details, see the App Store Guide. These are separate from server connection troubleshooting.

You can finish troubleshooting once the same server repeatedly completes a real request in the same mode. If you later want to configure On Demand or refine Rule, save the working setup first and make one change at a time. That gives you a verified baseline to return to if a problem occurs, instead of starting over with several uncertain settings.