Shadowrocket Setup Guide:
Import, Connect & Verify
Follow five steps using the iPhone or iPad interface to add an existing subscription or server, then check that the connection and rules work as expected. Start by setting up one connection; adjust other settings after verification.
First identify the type of information you have: a subscription link retrieves a set of server details; an individual server link, QR code, or parameter sheet adds one server; a rule configuration determines how traffic is handled. These are different types of information and should not be entered in the same place just because each may be a link.
Add a server / import a subscription
Open Shadowrocket and go to Home. Before connecting for the first time, tap the plus button in the upper-right corner and choose Add Server. Select the method that matches the information you have. You do not need to import the same information more than once. Subscriptions, individual servers, and configuration files serve different purposes, so choosing the right option is more useful than repeatedly trying to save the same information.
Have a subscription link? Choose Subscribe
- In Add Server, open Type, choose Subscribe, and return to the entry screen.
- Paste the complete subscription link from your service provider into URL. You can enter a recognizable name in Remarks. Do not include passwords or private information from the link in the name.
- Check that the link has no extra spaces, line breaks, or chat text at either end, then tap Save in the upper-right corner. Return to Home and wait for the subscription to load. If no content appears, update the subscription.
- Expand the subscription group, confirm that server entries appear, and select one to use for this connection.
Subscription links often contain personal access credentials, so store them as sensitive information. Copy the complete link, not just text shortened for display on a page. Do not submit the link to an unknown parsing site. If import shows a group name but no servers, usable entries have not been retrieved yet. Turning on the connection switch will not fill in missing details; check the subscription content and update results first.
Have details for one server? Enter them in Add Server
If you have a server address, port, and authentication parameters, select the protocol specified in the details under Type, such as Shadowsocks, VMess, VLESS, or Trojan, then fill in each field. Enter the hostname or IP address in the address field and the port in the port field. Do not paste an entire sharing link into the address field. Authentication details, transport options, and TLS settings must match the original information; the same protocol name does not mean settings from another server will work.
If the details also include a transport path, hostname, or server name, enter each in its corresponding field. Whether an option should be enabled depends on the actual server configuration, not on whether this guide mentions it. After saving, return to Home and select the entry you just added. To correct a parameter, edit that entry rather than creating several entries with similar names and risking selecting the wrong one.
If you have a QR code, scan it with Scan QR Code, review the recognized protocol and parameters, and then save. Whichever method you use, this step is complete when a server entry appears in Home and you have selected the one you intend to use. If you are unsure about a protocol field, check the Quick Reference instead of trying options at random.
Choose a Global Routing mode
After adding a server, decide which connections should use it. Open Global Routing from Home to see the Config, Proxy, and Direct modes. This setting determines how traffic is handled; it does not select a server or fix an incorrect address or authentication detail from the previous step.
| Mode | Purpose and use |
|---|---|
| Config | Routes traffic according to the active configuration's rules, which may use a proxy, direct connections, or other policies. Suitable for everyday rule-based traffic handling. |
| Proxy | Sends eligible traffic through the selected proxy policy. Useful for a brief comparison test, but it does not confirm that every rule in Config is correct. |
| Direct | Connects directly without forwarding traffic through the selected proxy server. Useful for checking the original network connection, but not for verifying that a proxy server is working. |
For everyday rule-based use, select Config, then open the Config page at the bottom and confirm that the configuration you intend to use is active. The Config page and the Config option in Global Routing are related, but they are different controls: the former manages configuration files, while the latter determines whether traffic follows a configuration.
Do not assume that a successful subscription import means your rules are also configured. Subscriptions primarily update server details; configuration files define rules, policies, and related settings. Rules in the active configuration usually match in order. If a domain first matches a direct rule, its connection may bypass the proxy even when a server is selected. When verifying later, check the matching rule rather than expecting every page to behave identically.
For now, keep an existing configuration that you trust and understand. Avoid changing DNS, complex policy groups, and multiple rules during the first connection. For an overview of keywords such as DOMAIN-SUFFIX, GEOIP, and FINAL, read Proxy Mode Guide. First confirm that a server is selected and Global Routing is set, then continue to the connection step.
Turn on the Home connection switch
Return to Home. Confirm that the selected server has not changed and that Global Routing is set to the mode you chose. Then turn on the connection switch at the top. The first time you enable it, iPhone / iPad displays a system prompt to add a VPN configuration. Read the prompt, allow it, and complete verification with your device passcode or biometric authentication as required. This is device authorization, not a server password.
- Keep Shadowrocket in the foreground, turn on the connection switch, and wait for the system prompt.
- After authorizing, return to the app. Check whether the switch remains on and the app shows an established connection.
- If you previously canceled authorization, try connecting again and complete the prompt. If the device is managed or restricted from adding VPN configurations, check its management rules first.
- Once connected, keep the current server and mode unchanged, then test in the next step. Do not enable extra automatic connection settings yet.
A VPN status in the system means the device has enabled the relevant network configuration. It does not prove that the remote server is reachable or that all traffic is using the proxy. Server authentication can fail, the remote server may be unreachable, or rules may route traffic directly even while the switch is on. This step confirms authorization and local connection status; actual availability must be checked with both the next test and real access.
If the switch turns off immediately, note the message shown in the app, then check system authorization, whether the current configuration is usable, and whether another VPN connection is controlling the network. Do not toggle the switch repeatedly in quick succession; allow time for the status to update after each change. For a managed device, do not delete management configurations of unknown purpose; check the device requirements first.
On Demand triggers a connection under specified conditions; it is not required for the first connection. First confirm that a manual connection works, then decide whether on-demand connection is needed. Adding automatic reconnection conditions during initial verification can cause the connection to recover by itself, making it harder to tell whether a change came from a manual action or an automatic trigger.
Connectivity Test and connection verification
Return to Home and use Connectivity Test to test a server in the list. Check whether the selected server returns a result or shows a timeout or failure. The test helps assess responsiveness on the current network, but a response from one test does not confirm that authentication, rules, DNS, and every destination are working. A single timeout does not prove that the parameters are wrong.
Next, open the page you want to verify in a browser, wait for it to load fully, and try refreshing it. Do not rely only on a page that was already open: it may be cached, or an existing connection may continue to use the handling from before a change. To reduce interference, test only a few clear targets. Avoid changing Wi-Fi, the server, the mode, and browser settings at the same time, or it will be difficult to identify the cause of any difference.
To verify routing in Config, open Data and check the relevant connection record for the destination domain, matching rule, and resulting policy. If the record does not show the information you need, confirm that the relevant logging feature is enabled before testing, then make the request again. If a page opens but the record shows Direct, that only confirms this direct connection succeeded; it does not show that the selected proxy server handled the traffic.
For a comparison, note the Config result, briefly switch to Proxy, make a new request to the same destination, and compare the outcome. Restore the intended mode after checking. If Proxy works but Config does not, first check the matching rule and policy in the configuration rather than deleting and re-adding the server. If both modes fail, check the network and server parameters first.
After verification, keep a brief record of the server used, network, Global Routing mode, and which destinations succeeded or failed. If a problem occurs later, compare it with this known working state. That is usually easier than changing every setting from scratch.
Common issues and checks
When something goes wrong, first identify whether the failure is during import, testing, authorization, or actual access. If an earlier step is incomplete, resolve it before moving on. For example, there is no need to change Global Routing while the server list is still empty. Change only one condition at a time, repeat the same test, record the result, and then decide whether to keep the change.
Subscription will not import, or the list is empty after an update
First check that you copied the complete subscription link and that no query parameters are missing, the link has not been truncated by a messaging app, and no extra punctuation was added. Then confirm that the current network can retrieve the subscription and that your service is still active. An account management page that opens in a browser is not necessarily an importable subscription. If it returns a login page or error message, the app cannot use it as a server list. If you are unsure what the link is for, ask your service provider.
After an update fails, do not immediately delete the existing subscription. First check whether the old entries are still there, and keep any error message that may help explain the problem. Repeatedly adding the same subscription can create duplicate groups and will not fix a link that returns incorrect content. Once the subscription works again, update it and confirm that the new server entries have loaded.
Server appears, but Connectivity Test times out
First confirm that the local network works without the proxy, then check the server address, port, and protocol. For manually added entries, make sure the authentication details are complete and that TLS, transport, and related names match the original information. If your subscription includes another server you can use, test it while keeping the network and test method unchanged. This can help distinguish a single-server issue from a broader network issue.
A test timeout may be related to the remote server, network path, or test target, so do not draw a conclusion from a single result. Try again later or, if appropriate, switch local networks for comparison. Do not disable necessary security verification as a general fix.
Connection is on, but pages still do not load correctly
First check whether Direct was selected by mistake, then confirm that the active configuration in Config is the one you expect. If only some destinations have problems, check which rule matches each one and whether it is assigned to a different policy. If domain access fails while other connections work, check the DNS settings in the active configuration. Do not replace every DNS address at the start, as this may remove a setting that was working.
If the same destination works in Proxy but fails in Config, return to the rules and policies. If all destinations fail, check the server status and connection authorization. If the problem occurs in a particular browser or app, check whether it is limited to that app; login, cache, or permission issues should not all be attributed to the proxy connection.
Verify again after making a fix
After changing and saving parameters, disconnect and reconnect if needed so new requests use the current settings. Run Connectivity Test again, revisit the destination that previously failed, and check the policy in the connection record. Do not stop just because an error temporarily disappears; the change is effective only when the original failing scenario also works again.
If the cause is still unclear, note the device system, network, failing step, and any error text after removing sensitive information. Then consult Frequently Asked Questions. For interface terms and rule meanings, see the Quick Reference. For iPhone / iPad store region, purchase, and restore-purchase questions, see the App Store Guide. These issues involve different layers from server parameters and should be handled separately.