OFFICIAL MANUAL / FIRST CONNECTION

Import a Subscription and Make Your First Shadowrocket Connection

Follow the steps in order: import, choose a mode, authorize the connection, and test access. First establish a repeatable connection, then adjust rules and automatic connection settings. This guide focuses on iPhone and iPad; interface labels remain in English.

Import an Existing Configuration
Global Routing
Authorize the VPN Configuration
Test Actual Access

STEP 01 / IMPORT

Add a Server or Import an Existing Subscription

First identify what you have: a subscription URL, individual server details, or a QR code. Use one import method at a time to avoid duplicate entries and selecting the wrong one.

Have a Subscription? Check the Subscribe Entry

Open Shadowrocket and go to the Config page. Look for the Subscribe entry, paste your complete subscription URL into the corresponding address field, then confirm to import or update it. If Subscribe is available as a type under Add Server in your version of the interface, you can enter the same details there. Layouts may vary; follow the Subscribe label and the fields shown. Don’t enter a subscription URL as a single server’s Host.

Copy the full URL, including everything after the question mark. Line breaks, extra spaces, or truncated characters in a chat app can make a valid URL unrecognizable. Treat the URL as private configuration data: don’t post it publicly or share it with strangers to troubleshoot. After importing, return to Home and check the SERVER group for an entry. Verify the name and number of entries before continuing.

Have Individual Server Details? Use Add Server

In the SERVER group on Home, tap Add Server. Select Type, then fill in Host, Port, and the relevant authentication fields. The official screenshot shows one example with Password and Method; fields may differ for other types, so don’t assume every protocol uses the same form. Enter the server address in Host and the corresponding port in Port, then carefully check the authentication method and encryption settings against your own details.

If your details include TLS, SNI, or other transport settings, check the corresponding options; entering only the address and port may not be enough. Don’t guess a different Method or change certificate verification settings just to make a test pass. Save the entry, return to Home, and open it again to confirm that no key fields are missing or recognized as a different type.

QR Codes and Clipboard Imports: Check the Entry After Importing

If you have a QR code, use Scan QR Code and grant the requested permissions. The code must contain recognizable configuration data. For a single configuration link, copy it and follow the app’s clipboard detection prompt to import it. Import from Cloud JSON is for compatible JSON configuration data, not a general-purpose substitute for a subscription URL. If you’re unsure of the format, check the source’s instructions rather than trying the same content through multiple import methods.

At this stage, success means the entry is saved and its details can be checked—not that the network is already working. A subscription may contain multiple servers, or a server list without routing rules. Next, choose how Global Routing should handle requests, then select a server from the list. If a subscription update fails but the old entry remains, keep it for reference rather than deleting it.

Official Shadowrocket Add Server page showing Type, Host, Port, Password, Method, and options such as Scan QR Code — Add Server fields vary by Type. The fields shown are for reference and do not mean every protocol uses the same parameters.

STEP 02 / GLOBAL ROUTING

Choose How Global Routing Handles Traffic

The server determines which connection is used for proxied requests; Global Routing determines how requests are handled. These are separate settings.

Return to Home and tap Global Routing to check the current selection. The three options are Config, Proxy, and Direct. Don’t rely on the connection switch alone to confirm routing: even with the switch on, Direct or a DIRECT rule may send relevant requests directly. Note the current mode before testing so you can compare results afterward.

Config: Use the Rules in the Active Configuration

If you choose Config, open the Config page to confirm which configuration file is active, then check its Rule section. In the official screenshot, General, Rule, Hosts, URL Rewrite, and HTTPS Decryption are configuration editor sections; they are not settings you must enable one by one to make your first connection. For initial setup, check the Rule content and active configuration. Don’t change unrelated settings or enable HTTPS Decryption just to test a connection.

Rules are generally matched from top to bottom, and the corresponding policy applies when a rule matches. For example, DOMAIN-SUFFIX matches a domain suffix; DIRECT means direct access, PROXY sends the request to a proxy policy, and REJECT blocks it. FINAL is the fallback when no earlier rule matches. The example below illustrates syntax only; it is not a complete configuration for your network. Read it for reference—you don’t need to copy it over your current file.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

Proxy and Direct: Compare Them Deliberately

Selecting Proxy routes requests handled by the current mode through the proxy path. This can help you briefly check whether the server connection works, but it doesn’t guarantee that every website will be accessible. Direct provides a direct-access comparison; it cannot verify whether a server is working. When comparing modes, change only this setting and test the same website again to distinguish a rules issue from a proxy connection issue.

If a website works in Proxy but fails in Config, check the matching rule and policy in the active configuration rather than immediately reimporting the subscription. If both modes fail, investigate the connection and server details. Restore your usual mode after testing. For more on rule order, policies, and DNS, see the Glossary and the Troubleshooting Manual. This guide does not cover advanced configuration.

Official Shadowrocket Config editor page showing General, Rule, Hosts, URL Rewrite, HTTPS Decryption, and Add Rule — Use the Config editor to check configuration sections; choose Global Routing from Home.

STEP 03 / CONNECT

Select a Server and Turn On the Connection

Select the entry you want to use before operating the switch at the top. The first connection requires authorization for the system VPN configuration.

In the SERVER group on Home, select the server you plan to use and make sure the selection indicator is on the correct entry. If the subscription contains several similarly named servers, open the details to verify the address and type instead of guessing from the name. Check Global Routing again to make sure it matches your test plan, then turn on the connection switch at the top of Home.

While disconnected, you may see a status such as Not Connected. The first time you turn on the connection, the system may ask to let Shadowrocket add a VPN configuration. This creates a system network configuration for the app on your device; it does not import a subscription or fill in server details. Confirm that the prompt came from your action, allow it, and complete device authentication as requested. Then return to the app to check the status.

If you previously canceled authorization, return to Home and try turning on the switch again. If the prompt appears again, follow it. If the switch immediately turns off or the status does not change, check the VPN section in system settings for the relevant configuration. Settings menus vary by system version; use the system settings search for VPN if needed. Don’t delete existing configurations in bulk without first recording their current state.

The system authorization process is the same on iPhone and iPad, though lists and details may be arranged differently on larger screens. Check the selected server, current Global Routing mode, and connection status—not the button’s position on screen. If the device is managed by an organization, network permissions may be restricted by its policies. Check the device management requirements instead of repeatedly changing server details to resolve a system permission issue.

A change in the status at the top means the app and system connection process has progressed; it doesn’t by itself prove that a website will load. Don’t repeatedly tap the switch right after turning it on, as connection and disconnection actions may overlap. Wait for the status to settle, keep the server and mode unchanged, then use Connectivity Test and an actual website visit to check the connection.

Official Shadowrocket Home page showing Not Connected, Global Routing, Connectivity Test, the SERVER group, and Add Server — Home shows the connection status, Global Routing, and server selection. Check your selections before turning on the switch at the top.

STEP 04 / VALIDATE

Verify the Result with a Test and Actual Access

Record “switch on,” “test returned a result,” and “website accessible” separately. One result alone doesn’t tell the whole story.

Run Connectivity Test First

Keep the server and mode you selected, tap Connectivity Test on Home, and check whether it returns a result. A timeout is a troubleshooting clue, but doesn’t necessarily mean all requests will fail. A response doesn’t prove that authentication, DNS, rules, and the destination website are all working. The method and target used by the test affect its result, so record what happens rather than deleting all your entries at once.

Next, open a browser and visit a familiar website you currently need to use. Check whether it loads, then see whether ordinary links on the page open as well. A cached homepage alone isn’t enough to verify a new request; reload it or open another page on the same site. Don’t use a screen showing only cached in-app content to conclude that network access has been restored.

If websites load but a particular in-app feature fails, keep the current configuration for now and note the app, action, and network conditions involved. A single service may also be affected by its sign-in status or the destination service itself. Don’t immediately attribute every issue to the server connection. Repeat the same action on the same network to see whether the issue is consistent before troubleshooting further.

Check Whether the Result Matches the Current Mode

A website loading in Config may have matched a DIRECT rule, so access alone doesn’t prove that the proxy path is working. To test the proxy path, temporarily switch to Proxy as described above and visit the same destination using the same server and network. Restore the original mode afterward and note whether the results differed.

If you’re familiar with Shadowrocket’s connection logs, use the request domain and corresponding policy as additional evidence. Record only the lines relevant to the issue. A PROXY rule in the configuration doesn’t mean every request matches it; an earlier rule may already have matched. If a test succeeds but one domain fails, first distinguish a rule match issue from DNS, then check the destination itself instead of repeatedly toggling the connection.

You’re done when you can state which server and Global Routing mode you used, and what happened when you tried to access the site. To compare Wi-Fi with cellular, first record one complete set of results, then switch networks and repeat the same steps. Changing the server, network, and mode at the same time makes results difficult to compare.

STEP 05 / SETTINGS & DIAGNOSTICS

Check Settings at Each Point of Failure

First identify where the failure occurs, then adjust one relevant setting. Settings is where you check options, not a list of items that all need changing.

Import Fails: Check the Source and Import Method

If no entry is created, first check that the source format matches the import method. Then verify that the link is complete and valid, and check your regular network. Being able to open a subscription URL doesn’t guarantee that it returns recognizable configuration data; a login page, error message, or empty response may prevent import. Don’t include private subscription details in public screenshots. If you need to confirm whether the source is valid, contact the provider of your existing service.

The Switch Won’t Stay On: Check System Authorization

Return to the connection steps, confirm that authorization for the system VPN configuration is complete, and check whether another active VPN connection is affecting the current attempt. If the system VPN configuration was deleted, the app may need to request authorization again. First record the existing configuration and exact prompt, then follow the system process. Don’t make reinstalling your first troubleshooting step; before reinstalling, make sure you can restore your existing configuration.

Test Times Out or a Website Fails: Check the Test and Connection Separately

Open Settings and check Test Method, then repeat the test under the same conditions. If a test method returns no result, use actual website access as additional evidence; don’t treat one test value as the only measure. If repeated attempts to access websites also fail, return to Add Server and check Type, Host, Port, authentication, and TLS-related details against your source. Don’t randomly change ports or passwords.

If Proxy works but Config fails, check Rule and DNS in the active configuration first. If the issue began after switching networks, note the difference between Wi-Fi and cellular, then check network reachability. Settings such as Proxy, TCP, and UDP serve different purposes; avoid changing them all during initial troubleshooting. Keeping the default or existing configuration usually makes it easier to identify the setting that actually changed the result.

Automatic Connection and Diagnostics: Record First, Then Troubleshoot

If the connection comes back after you manually disconnect, check the On Demand status and existing conditions in Settings. On Demand triggers connections based on conditions. During initial testing, record its current value; if needed, temporarily turn it off to compare with a manual connection, then restore it to suit your needs. Don’t mistake an automatic trigger for a faulty switch, and don’t add complex conditions before confirming that a manual connection works.

For more clues, open Diagnostics and review information related to your current attempt. Record the failed step, network type, mode, exact error message, and steps needed to reproduce the issue. Before sharing screenshots or logs, hide subscription URLs, passwords, authentication details, and personal network information. Logs can help narrow down the cause, but there’s usually no need to share your complete configuration publicly.

If the cause is still unclear, continue with the Connection Troubleshooting Manual for symptom-based guidance. For purchase, authorization, and common usage questions, see the FAQ. If a field is unclear, check the Glossary. Keep a record of the server, mode, and test results so you won’t have to repeat every step when troubleshooting further.