[Quickstart]Official Manual

Shadowrocket Quick Start

Start with an existing subscription or server details, then import, choose Global Routing, connect and test access. First confirm that one connection works before adjusting rules or other settings.

[Subscribe]

01 Add a server or import a subscription

After opening Shadowrocket, go to Home. This is where you view and select server entries. Config is for managing configuration files; the two serve different purposes. On first use, add your existing connection details to Home. You do not need to find a rules file just to make a server list appear. A subscription link is not an ordinary website address. It usually contains credentials for accessing a service configuration and should not be shared in public forums.

Existing subscription link: choose Subscribe

Tap the plus button in the upper-right corner of Home to open Add Server. Tap Type, choose Subscribe, then paste the complete subscription link you obtained from your service provider in the URL field. Check the link before and after pasting to make sure both ends are complete and that it contains no extra spaces, line breaks or explanatory text from a chat message. You can add a note to make the link easy to identify, then tap the button in the upper-right corner to save.

Return to Home and wait for the subscription content to download. Once retrieved, server entries should appear in the corresponding group. A group name is only a management label; it does not mean you are connected. You still need to select an entry. If you see a group name but no servers, first check for an error during subscription update. Repeatedly adding the same link will not fix the problem. A subscription may require an active account or a network that meets its access conditions; check the account details for the service you already use.

Some users receive individual server details rather than a subscription link. You cannot tell which it is just from the length of the address; first confirm its intended use with the provider. Pasting individual server details into Subscribe, or using a subscription URL as a server hostname, will cause an import error. If you are unsure, first read the glossary entry on subscriptions and Config files. Do not try entering an unfamiliar link into every field.

Existing server parameters: enter them manually in Add Server

If you have a set of server parameters, select the protocol in Type in Add Server that matches the original details, then enter the server address, port and authentication information. Shadowsocks, VMess, VLESS, Trojan and other protocols require different fields. Do not use a password or identity field for one protocol as if it belonged to another. Check TLS, SNI, transport method and path against the original details, rather than guessing from the server name.

After saving, return to Home, confirm the entry appears in the list and select the server you want to use. Do not connect just yet: the next step is to choose Global Routing so the test results correspond to a specific traffic-handling mode. If the subscription has several entries, select just one for the first test. Changing the server and routing mode at the same time makes it harder to identify the cause of a failure.

[Rule]

02 Choose Global Routing

Tap Global Routing on Home to check the selected mode. The three options are Config, Proxy and Direct. They determine how requests are handled by policies; they do not fill in server parameters or fix expired authentication details. Note the current option before switching so you can restore it after testing.

Config matches traffic against the rules in the currently enabled Config file. Open Config and check which file is actually selected, not just whether a file exists. Rules in a file are usually matched in order. A request is handled by the policy specified in the first matching rule. If a domain can be accessed directly, that does not prove the proxy server is working; the request may not have used the proxy at all.

Proxy can help isolate rule-related factors by sending applicable traffic through the proxy mode. For an initial test, select Proxy, then return to Home and confirm that a server is selected. This creates an easy-to-observe test condition; it is not a recommendation to use this mode permanently. System traffic scope, app behavior and network conditions can still affect the result.

Direct accesses destinations directly and is not suitable for testing whether a proxy server works. If access behaves the same with the connection on as it does with it off, first check whether the mode is still Direct instead of immediately re-entering the password. Direct can also serve as a comparison to help determine whether a website that normally works without a proxy encounters problems in other modes.

After confirming that real-world access works in Proxy, open Config, select a Config file you already have and understand the source of, then return to Global Routing and switch to Config. Do not replace your current configuration with unfamiliar rules from the internet, or change DNS settings at random just to make every test pass. See Settings reference for details on rule order, DNS and On Demand. This page covers only the basic connection workflow.

[Connect]

03 Connect and authorize the system prompt

Return to Home, check that the selection indicator is on the server you want to test, and confirm that Global Routing is set as in the previous step. Then turn on the connection switch at the top. The first time you connect, iPhone / iPad may show a system prompt to add a VPN configuration. Confirm that the request was just initiated by Shadowrocket, then follow the system prompt to allow it and complete any authentication required by the device.

System authorization allows the app to establish the corresponding network connection; it does not purchase a service or create a server account. If you tap Cancel, return to Home and check the switch status. Try again when you are ready to connect. If the device is managed by an organization, its management policy may restrict the configuration. Ask the device administrator to check permissions instead of repeatedly deleting system settings.

After authorization, return to Home and check whether the switch stays on and the app shows a connected status. The system status bar or Control Center may also show a VPN status indicator, though its location varies by device. Do not rely on one small icon alone: consider the connection status, actual access and request records together. An established VPN tunnel only confirms that the system connection step is complete; it does not guarantee that the remote service is available.

If the switch turns off as soon as you turn it on, or the system immediately displays an error, keep the error text and check whether another VPN connection is active, system permissions are granted, and the current configuration has any obvious errors. During initial troubleshooting, leave automatic connection conditions such as On Demand disabled. Otherwise, the connection may reconnect automatically after you turn it off, making the current state harder to assess. Change one item at a time and reconnect; do not toggle the switch repeatedly in quick succession.

When you change servers, networks or key parameters later, you can turn off the connection, make the changes, turn it back on and repeat the next verification step. Leaving the app for the Home Screen does not disconnect it. When you no longer need the connection, turn it off from Home and confirm that the status has changed. This also prevents you from mistaking the results of a previous connection for a test of the current parameters.

[Test]

04 Verify that the connection works

Use Connectivity Test on Home for initial feedback. It can help identify obvious connectivity problems with the selected server, but its target and method may differ from those used by apps in everyday use. A test result does not mean every website is accessible. If the test fails, consider the specific error and real-world access before drawing conclusions; do not delete the entire configuration based on one result.

Next, open a browser and visit a website you are authorized to access and can clearly confirm has loaded. Refresh the page during the test so you do not mistake previously cached content for a new result. If you need to sign in, submit a form or use a real-time feature, test those actions separately. A successfully loaded main page does not mean every domain it references uses the correct policy.

When using Config, also verify that traffic is routed as expected. For example, if a test domain should use PROXY, first find the corresponding rule in the Config file, then check the actual handling using available connection or log information. If the request matched DIRECT, check whether an earlier rule matched first rather than blaming the server. See the glossary for rule keywords and the Settings reference for specific settings.

If access works in Proxy but fails in Config, first check the active Config file's rules, policy references and DNS settings. If both modes fail, check the server parameters, service status and current network first. If only one app fails, also check its sign-in status, cache or service availability. Change one condition at a time so you can compare the results before and after.

Finally, test again on both the Wi-Fi and cellular networks you actually need. After switching networks, wait for the system to stabilize, then confirm the connection status and selected server. Do not mistake a brief interruption during the switch for a persistent failure. Once this step is complete, keep the verified server and mode as a baseline. The quick-start process is done; use these working conditions as a fallback when you add automatic connection, change rules or replace the Config file later.

[Troubleshoot]

05 Troubleshoot based on where the failure occurs

Start with the last step that worked, not with reinstalling the app. Note the current network, import method, protocol, selected server, Global Routing mode and error text. Then identify whether the failure happens while downloading a subscription, connecting or accessing a website. This reduces repeated steps and helps you describe the issue clearly when asking your own service provider for help.

No servers appear, or the subscription update fails

First check that the URL is complete, the subscription is still valid, and the current network can access the subscription address. Existing server entries do not guarantee that the next subscription update will succeed; downloading a subscription and connecting to a server are separate steps. Keep the existing group, check the link and service status, then try updating again. Do not repeatedly delete and recreate it. If you only have a webpage description rather than recognizable configuration content, ask the original provider what the link is for.

Connectivity Test fails

Confirm that you selected the server you intend to test, rather than just opening a group. For manually entered details, check the protocol, address, port and authentication parameters. For connections using TLS, also check requirements such as SNI against the original details. Do not hide parameter problems by enabling Allow Insecure at random, and do not switch to an unfamiliar test target just to make the test show success. If another entry in your existing subscription is available, test it on the same network and in the same mode.

The switch will not stay on, or access fails while connected

If the switch will not stay on, first check system authorization, other VPN connections and any explicit error message. If the switch stays on but access fails, confirm that the mode is not Direct, then run a comparison test in Proxy. If Proxy also fails, check the server status and parameters. If Proxy works but Config fails, troubleshoot the active Config file. Do not change DNS, the protocol, rules and test website all at once, or you will not know which change caused the result.

Only some websites fail, or a failure occurs after switching networks

Problems with specific websites usually require checking the rules matching the domain, DNS results and the destination service status. First confirm whether other websites work, then narrow down the cause. If a problem occurs after switching between Wi-Fi and cellular, wait for the network to stabilize, reconnect and test the same destination again. For more detailed troubleshooting categories, read Frequently asked questions. Do not replace multiple advanced settings during the initial setup.

After troubleshooting, test again in this order: select a server → confirm Global Routing → connect → test real-world access. Once access is restored, add the original settings back one at a time. For configuration backups or ongoing maintenance, continue to the Settings reference. You do not need to configure every feature during your first connection.