Shadowrocket Official Manual

Shadowrocket Setup Guide

Add a server, choose Global Routing, connect, and verify access. Follow a repeatable sequence to complete your first setup.

This page covers the steps needed for first use. Screenshots show where items appear in the interface; their order on your device may vary with the system and app interface, so refer to what is currently displayed. For details about individual settings, see Settings explained.

01 / ADD SERVER · SUBSCRIBE

Add a server or import an existing subscription

Open Home in Shadowrocket and find Add Server in the SERVER group. Choose a method based on the details you have: use a server address, port, and authentication fields to add a server manually; use Subscribe with a complete link that returns a server list. You do not need to use both methods, and a subscription link should not be entered in the Host field for an individual server.

Enter details manually with Add Server

After opening Add Server, open Type and select the protocol that matches your server details, then fill in the fields required by that protocol. Type determines which fields appear, so do not fill in the form based on a screenshot and then change the protocol. Host, Port, Password, and Method in the image are examples of where fields appear; not every protocol uses the same set. If your details include other authentication or transport parameters, use the fields shown for the corresponding Type.

Enter the server address in Host without a webpage path, and enter the port from your server details in Port. Check Password, Method, and other fields carefully, especially for spaces, line breaks, or capitalization introduced when copying. If your details specify TLS, Server Name, or transport settings, expand the relevant options and check them too. Matching addresses and ports alone do not mean a configuration is complete. Do not guess the encryption method or omit authentication details.

Save using the control on the page, then return to Home and check the SERVER group. Seeing an entry only confirms that the details were saved; it does not mean the server can connect. First check that its name and address match what you expect, then select it so you have a specific server to test.

Import a link with Subscribe

If you have a subscription link, select Subscribe under Type in Add Server, enter the complete link as prompted, save, and wait for the list to load. Use your own subscription address, not the login page for a service account. After pasting, check both ends of the link to make sure you have not included explanatory text, quotation marks, or line breaks from a chat message. A subscription address may contain access credentials; do not post the full link in public discussions or screenshots.

Return to Home and check whether the expected server entries appear in the subscription group. If the group name appears without any entries, first make sure the refresh has finished, then check whether the link is valid and whether your current network can access it. Creating the same group again usually will not fix a retrieval failure. Subscribe updates server details; it does not mean that a rules file has also been imported.

If you have a QR code, use Scan QR Code and check the detected type and fields before saving. Import from Cloud JSON is for data in the corresponding format, not a general-purpose way to import any webpage link. After completing one of these methods, continue to the next step to choose how traffic is handled. There is no need to try every other import option.

Shadowrocket Add Server page showing Type, Host, Port, Password, Method, and the Scan QR Code and Import from Cloud JSON options
Add Server reference: choose Type first, then enter the corresponding fields. The combination shown does not apply to every protocol.
02 / GLOBAL ROUTING · CONFIG

Choose a Global Routing mode

Once the server appears in Home, open Global Routing and choose how to handle traffic for this session. The three modes are Config, Proxy, and Direct. Selecting a server and selecting a mode are separate actions: the first sets the proxy destination, while the second affects how requests are routed. Before troubleshooting, note the current selection; switching modes can change your test conditions.

Config: Follow the current rules

Use Config for everyday rule-based routing. Open Config, confirm which configuration file is active, and review its Rule section. Rules determine the matching conditions and how matching traffic is handled, such as whether a domain goes through PROXY or DIRECT. A server appearing in a subscription list does not prove that you have rules suited to your needs or that an imported file is the active configuration.

The official screenshot on the right shows the configuration editor: General, Rule, Hosts, URL Rewrite, and HTTPS Decryption organize different content, while Add Rule adds a rule. You do not need to edit every section when getting started, or enable every feature just to connect. First identify the configuration file and the location of Rule. If you plan to edit, save a copy of the original configuration so you do not overwrite working settings.

The line below is only an example of rule syntax, not a complete configuration to replace your existing file. It matches example.com and its subdomains by suffix and sends them through PROXY. Whether PROXY works still depends on the selected server and the corresponding configuration.

DOMAIN-SUFFIX,example.com,PROXY

Proxy and Direct: Make a clear comparison

Proxy routes traffic through the selected proxy path. It is useful for checking whether the selected server can handle an actual request during initial setup. It does not guarantee that every request will succeed or fix incorrect server details. If you use it temporarily for comparison, note the original mode and restore it after testing. Do not keep a setting you do not understand just to make one website load.

Direct handles requests using a direct route and can help you compare your device's local network with the proxy path. If a page loads through Direct, that only confirms the page is reachable on the current local network; it does not prove the proxy works. Likewise, a successful proxy test does not mean every rule is correct. For rule priority, fallback behavior, and DNS, see Settings explained. For this test, choose one mode and return to Home to connect.

Shadowrocket Config editor with General, Rule, Hosts, URL Rewrite, and HTTPS Decryption sections and Add Rule
The Config editor is where you review configuration contents. Choose a Global Routing mode from Home.
03 / HOME · CONNECTION

Return to Home and turn on the connection

Return to Home and check three things before connecting: the server you intend to test is selected in SERVER; Global Routing matches the mode you chose in the previous step; and your current Wi-Fi or cellular network works. If another VPN connection is running on the device, check its status in system settings first so you do not mistake a switch between connections for a Shadowrocket server issue.

Once confirmed, turn on the switch at the top of Home. The first time you connect, iPhone / iPad may show a system prompt to add a VPN configuration. Confirm that the request was triggered by your recent action in Shadowrocket, then follow the system prompt and authenticate on the device if required. This step adds the configuration needed for a network extension on your device; it is not a request for the server Password. Do not confuse the two types of credentials.

After authorization, return to the app and check that the top status changes from Not Connected and the connection switch stays on. The VPN status may appear in different places across systems, so check the status in Home and verify actual access in the next step rather than looking for an icon in a fixed location. If authorization completes but the connection has not started, check the switch and turn it on once if needed.

If the switch turns off immediately after you turn it on, stay on the current page and check for an error message, then verify system VPN authorization and the selected configuration. Toggling rapidly can add multiple connection attempts to the logs and make the original failure harder to identify. Do not rush to change DNS or re-add every server. First note the symptom—“turns off immediately”—then follow the relevant checks in the final step.

Even when the connection switch stays on, do not consider setup complete yet. It mainly indicates that the connection process is running on the device. You still need to verify server availability, domain resolution, and rule matching separately. Keep the server, network, and mode unchanged so that Connectivity Test and actual webpage access use the same conditions.

Shadowrocket Home page showing the Not Connected switch at the top, followed by Global Routing, Connectivity Test, the SERVER group, and Add Server
Check Home before connecting: review the server, Global Routing, and the top switch together.
04 / CONNECTIVITY TEST · DATA

Verify test results and actual requests separately

After connecting, run Connectivity Test from Home and wait for it to finish. Interpret the result in light of the test method: a response means the test target and route responded, but does not mean every website, protocol, and app is available. If the test times out, do not delete the server immediately; the target, how the network handles specific traffic, and the test method itself can all affect the result.

Next, open a browser and revisit a familiar page that you are allowed to access. Open a new page or reload it to avoid mistaking cached content for a new network request. If the page has images, text, and content that loads later, check that all of it appears as expected; seeing only a page title does not confirm that the whole request chain works. Do not refresh the subscription, switch servers, and change the configuration at the same time, or it will be difficult to tell which change affected the result.

To check routing, view Data or the connection records available in the current interface, and look at the destination and handling method for the request. An increase in the counter only shows that traffic passed through; it does not prove that it used the expected PROXY. If the records show the relevant rule and policy, consider the destination domain, match condition, and final handling together. If there is no relevant record, first confirm that the browser sent a new request.

Observed resultNext check
The switch stays on and the page loadsConfirm Global Routing matches your needs, then test the apps you use regularly.
Connectivity Test responds, but the page does not loadCheck domain resolution, rule routing, and the browser error. Do not re-import immediately.
Failure occurs only in ConfigCheck the current configuration file and Rule to see whether a rule sends the request elsewhere.
Results change when you switch local networksNote the difference between Wi-Fi and cellular, then check whether the required transport is reachable.

For comparison tests, change only one condition at a time. For example, keep the server fixed and compare Config with Proxy. If only Config fails, check the rules before re-entering the Password. Or keep the mode fixed and compare Wi-Fi with cellular; if only one network fails, note the difference first. After testing, restore the mode you intend to use and revisit the page to confirm. This avoids leaving a temporary troubleshooting setting in place.

05 / SETTINGS · DIAGNOSTICS

Check settings based on the symptoms

If verification fails, first classify the issue: details did not import, the server test timed out, webpages fail while the switch is on, or the connection drops after running for a while. Each symptom has a different starting point. Keeping the visible error and noting what you just did is more useful than resetting everything. Do not assume that every failure is caused by DNS.

Import did not work: Check the original details

If the expected entry does not appear after adding a server manually, return to Add Server and check that it was saved, that Type is correct, and that all required fields are complete. If Subscribe returns no servers, make sure you pasted the complete subscription address and that the current network can access it. Check whether your subscription is valid using your own service details or provider instructions. Do not post the link publicly to ask someone to test it; it may contain credentials that grant access to the service.

Test times out: Check parameters and time first

If the server keeps timing out, check Host, Port, Type, authentication fields, and transport parameters one by one. If you use TLS, also check that fields such as Server Name match the original details, and confirm that the device's system time is accurate. A time difference may affect certificate validation, but fixing the time does not guarantee that other issues will disappear. Some transports depend on UDP, and network differences can also affect test results. Do not mask parameter issues by casually disabling verification.

Test Method in Settings affects how the test is performed. Identify the current method before interpreting the result; do not keep switching it just to make a value appear in the list. If the server is reachable but the test target is not, the test result and webpage experience may differ. In that case, continue checking actual requests and error records.

Switch is on but webpages fail: Check DNS and rules separately

First return to Home and confirm Global Routing, then check the active file in Config. If Proxy works but Config does not, check rule routing first. If both modes fail but the test still responds, check DNS-related records and browser errors. Before changing DNS, note the original value and change only one item at a time. Retest before deciding whether to keep the change. Do not enter a group of addresses you found online into every DNS option.

Automatic connection or disconnection: Check On Demand and system status

If the connection comes back after you turn it off manually, or its status changes when you switch networks, open On Demand in Settings and check for connection behavior triggered by network conditions. Understand the current conditions first, then decide whether to disable them temporarily for comparison. You do not need to enable On Demand to complete your first connection. Also check the system VPN status to make sure no other connection-management setting is involved.

To investigate further, use Diagnostics in Settings to collect the necessary information around a single failed attempt. Before sharing a record, remove subscription addresses, server authentication fields, and other personal information; keep only the error type and reproducible steps. Settings such as Today Widget, Proxy, TCP, and UDP each have their own purpose. Do not change them all as a general fix. See Settings explained for details, or look for a specific issue in Troubleshooting.

Shadowrocket Settings page showing Language, Test Method, Today Widget, On Demand, Diagnostics, Proxy, TCP, and UDP options
Use Settings to check options based on the symptoms. You do not need to change every setting on first use, and should not change multiple network options at once.

After completing this page, you should be able to identify three things: which server is selected in Home, which Global Routing mode is active, and whether the page loads through the expected route. Keep this working setup as a reference when adding rules or changing settings later.