Official Manual Getting Started / iPhone and iPad Interface

Shadowrocket Setup GuideImport Subscriptions, Rules, and Test Connections

Follow this sequence: add a server, choose a mode, connect, verify, and troubleshoot. First confirm that an existing server connects, then adjust rules. Change one setting at a time to make results easier to assess.

STEP 01 / ADD SERVER

Add a server or import an existing subscription

Open Home in Shadowrocket and find the SERVER list and Add Server. A subscription link and the details for a single server are different types of input: a subscription link retrieves and updates a group of servers, while manual setup requires you to enter the details for one server field by field. Identify which type of information you have and follow the corresponding path. There is no need to do both.

Existing subscription: use Subscribe

Open Add Server, tap Type, select Subscribe, and paste your existing subscription URL into URL. Check the beginning and end of the pasted text and look for line breaks. Make sure you have not included explanatory text from a message, quotation marks, or trailing punctuation. A subscription URL may contain access credentials; do not include the full URL in a public screenshot or share it with unrelated people.

Save and return to Home. Wait for the subscription to load, then check whether the corresponding group and server entries appear under SERVER. A subscription name appearing does not mean its contents were retrieved successfully. Expand the group and confirm that it contains selectable servers. If it is empty, check the update status before turning on the connection switch. Import failures and server connection failures happen at different stages and need to be addressed separately.

To update a subscription later, use the update action on the existing subscription entry instead of repeatedly adding the same URL. Repeated imports can leave duplicate groups with the same name, making it unclear whether the selected server belongs to the subscription you are checking. Note the selected server before updating, then confirm the entry is still present afterward. Entry names and parameters may change with the subscription contents.

Single server details: enter the fields for its Type

If you have a Host, Port, and authentication details, select the appropriate Type in Add Server. Protocols such as Shadowsocks, VMess, VLESS, and Trojan use different fields; entering only an address and port is not enough. Follow the original server details. Password and Method in the example screenshot apply only to the type shown and do not mean that every protocol uses the same form.

Check that Host has no extra spaces, Port is complete, and Password, encryption method, and other authentication fields match the original details. If the information includes TLS, a transport method, or a server name, enter those in the corresponding options as well. Ask the provider of the original details if you are unsure; do not guess by changing the protocol type.

If you have a QR code, use Scan QR Code. Use Import from Cloud JSON only when your source is explicitly in the corresponding format. Check the scanned result, especially Type, Host, and Port. After saving and returning to Home, confirm that the entry appears under SERVER, then proceed to Global Routing. For other import formats, see Questions and Answers. For subscription update errors, see Subscription Failure Diagnosis.

Shadowrocket Add Server page showing Type, Host, Port, Password, Method, and the QR code and cloud JSON import options
Add Server: choose Type first, then fill in the fields it requires. The fields shown in the screenshot do not apply to every protocol.

STEP 02 / GLOBAL ROUTING

Choose Global Routing and the active configuration

After adding a server, return to Home and tap Global Routing. This controls how connections are routed; it is not where you change a subscription URL. First, understand the three modes: Config, Proxy, and Direct. Choose Config to handle different requests according to existing rules. If you temporarily change modes to diagnose an issue, restore the original selection after testing.

Config: follow the active rules

Config uses the rules in the active configuration to choose DIRECT, PROXY, or another defined policy for each request. Open the Config tab at the bottom to confirm which configuration is active, then review its Rule section. A subscription usually provides a server list, while a configuration file provides rules and other settings. Importing a subscription does not necessarily select a corresponding rule configuration automatically.

In the official screenshot, General, Rule, Hosts, URL Rewrite, and HTTPS Decryption are sections for editing a configuration. When getting started, check the active configuration and Rule; you do not need to edit every section or enable HTTPS Decryption to connect. If you already have a working configuration, save a copy before editing so you can restore it if troubleshooting goes wrong.

Proxy and Direct: compare routing paths

Proxy sends connections through the current proxy policy, but it cannot fix an unavailable server. Direct connects without using the selected proxy server. If a page opens after switching to Direct, that only shows that the page's direct route works; it does not prove that the proxy is configured correctly. These modes are useful for comparison, not as universal fixes.

Rules are usually matched in order. This example is only to illustrate the syntax: the first line matches a domain suffix, the second matches an IP by geographic location, and the last line is the fallback. It is not a complete configuration to import as-is, and the policy names must be valid in your configuration. Do not overwrite your existing Rule just to copy the example, and do not replace your server address with the example domain.

DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

After checking the configuration and policies, return to Home and confirm the Global Routing selection again. Keep the rules unchanged for the connection test. If Proxy works but Config does not, check which rule matched the actual request. For more on rule syntax and policies, see Questions and Answers and Troubleshooting.

Shadowrocket Config editor showing General, Rule, Hosts, URL Rewrite, HTTPS Decryption, and Add Rule
Config: review the rule sections in the active file. Global Routing modes are selected from Home, not from this configuration editor.

STEP 03 / HOME

Select a server and turn on the connection

Return to Home and find the server you just imported or added manually under SERVER. Select the entry you intend to use. A group heading and the servers within it are at different levels; expand the group and confirm which server is actually selected. If the configuration uses a policy group, also check that the policy handling the request does not point to a different server. Selecting a server in the list does not mean every request will use it.

Turn on the switch beside Not Connected at the top. On the first connection, the system asks to add a VPN configuration. Read the prompt and allow it, complete device authentication as required by the system, then return to Shadowrocket. VPN configuration permission is used to establish a system network connection. Granting it does not replace server import or verify the server address and password.

After returning, check whether the connection status at the top has changed and whether the switch remains on. If the system says setup is incomplete, finish the prompt instead of repeatedly tapping the switch while it is open. If you previously denied permission, try connecting again and follow the prompt. If the configuration still cannot be added, check for device management restrictions or another VPN connection in progress.

A switch that stays on only indicates that the local connection has reached a certain stage; it does not mean every destination is accessible. Do not change DNS, rules, and server settings at the same time. Keep the current settings for the next verification step. To disconnect, turn off the switch at the top of Home. If it reconnects automatically, note what happened and check On Demand in Settings later.

Shadowrocket Home page with the Not Connected switch, Global Routing, and Connectivity Test at the top, and SERVER and Add Server below
Home: check the selected server, Global Routing, and the switch at the top in order. Connectivity Test is for the next step and does not replace verification with a real destination.

STEP 04 / CONNECTIVITY TEST

Verify the connection, not just the switch

First, use Connectivity Test on Home to check a candidate server. Results depend on Test Method, the test destination, and the current network, so compare results under the same test conditions. A response is a reason to continue verification, but it does not prove that every website, protocol, or app works. A single timeout also needs to be assessed alongside actual access.

Next, open a browser, visit a destination you actually need, and reload the page. Do not rely only on a tab that has been open for a long time; cached content can hide whether a new request succeeds. Also visit a destination you know can be reached directly to check whether the basic network is working. If the basic network is unavailable, restore Wi-Fi or cellular data before continuing to troubleshoot the app.

If you are using Config, check which rule matched the request and which policy was ultimately used. Review the destination domain and handling result in the request records available in your current version. Under Config, some connections may use DIRECT as a normal result of rule-based routing. That alone does not mean the connection has failed. Conversely, even with the connection switch on, an incorrect DIRECT match can prevent a destination that requires a proxy from loading.

If the test responds but the actual destination does not open, note the destination, network, current mode, and server. Then change only one setting at a time for comparison. For example, temporarily switch from Config to Proxy and revisit the same destination. If the result changes, check the rules or policy first. If it does not, check server parameters, DNS, or the destination's status. Restore the original settings after comparing results so you do not leave the app in a test mode.

If real-world access works as expected, the initial connection is complete. Adjust rules and On Demand one at a time afterward, repeating the same destination test after each change. If problems persist, follow the symptom-specific checks below. Do not clear all configurations without first recording the current setup.

STEP 05 / SETTINGS

Settings and common failure points

Start troubleshooting by identifying where the failure occurs: the subscription did not import, a server test timed out, the connection switch will not stay on, or only some requests fail after connecting. Each symptom calls for different checks. Keep the current configuration and error message, then narrow down the cause in the order below. Avoid changing the server, rules, and DNS at once, or it will be difficult to tell what affected the result.

Subscription update failed: check retrieval first

Make sure the subscription URL is complete and has no extra spaces, line breaks, or punctuation. Confirm with the provider of the original details that the URL is still valid. An empty subscription list, an authentication failure, and a network timeout are different issues. If existing entries still work, keep them for comparison; do not delete all servers just because an update failed. See Shadowrocket Subscription Failure Troubleshooting for details.

Server timeout: check parameters, then compare networks

Recheck Type, Host, Port, and authentication fields, and make sure no TLS or transport parameters are missing. Keep the server parameters unchanged and test over available Wi-Fi and cellular networks. If the results differ by network, check the network environment first. If only one server fails on the same network, check that entry's status rather than resetting all system network settings.

Cannot access destinations after connecting: distinguish rules from DNS

First confirm that the basic network can directly reach a working destination, then compare the same destination under Config and Proxy. If it fails only under Config, check the matched rule and policy. If the issue looks like a domain name resolution failure, review the DNS settings in the active configuration. Do not enter multiple unknown DNS addresses at once, and do not treat changing DNS as a fix for server authentication failures.

Frequent reconnects or battery drain: check On Demand

Open Settings and find On Demand. Check whether automatic connection conditions are configured. To troubleshoot automatic reconnection, temporarily disable the relevant conditions and connect manually to see whether the behavior changes. Restore them afterward if needed. Assess battery use against system battery statistics and usage times; the VPN indicator in the status bar alone does not prove abnormal battery drain.

Test Method in Settings affects how Connectivity Test results should be interpreted. Diagnostics can help collect further clues. Recording the steps and error details is more useful than repeatedly toggling the switch. Do not change every advanced Proxy, TCP, and UDP option just for one connectivity test. Adjust an option only when you know it is relevant to the current symptom, and note its previous value.

On iPad, use the same Home, Config, and Settings interface terms to find controls. The layout and columns may look different in landscape orientation, so do not rely on screenshot coordinates. If the issue persists after the basic steps, follow the symptom-based checks in Troubleshooting. For questions about protocols and settings, see Protocol Questions and Answers.

Shadowrocket Settings page showing Language, Test Method, Today Widget, On Demand, Diagnostics, Proxy, TCP, and UDP
Settings: focus on Test Method, On Demand, and Diagnostics when troubleshooting. Change only the options relevant to the issue.