Official Manual · First Connection

Shadowrocket Quickstart Guide

Connect for the first time with an existing subscription or server details, then check routing, server responses, and actual browsing separately.

1. Add a server or import a subscription on Home

Open Shadowrocket, tap Home at the bottom, then tap the plus sign in the upper-right corner to open Add Server. First identify the type of details you have: a subscription link retrieves a set of entries, while individual server details correspond to one entry and usually list the address, port, and authentication information by protocol. For the first setup, choose one method; you do not need to import a subscription and manually enter the same server. You can leave the connection switch at the top off while adding details.

Existing subscription link: choose Subscribe

In Add Server, open the type selector and choose Subscribe. Paste the complete subscription link into the URL field. Check both ends, especially for spaces, line breaks, or nearby explanatory text accidentally included during copying. Do not remove parameters after the question mark or split the full link into a server address and port. After saving, return to Home and check whether the subscription and its server entries appear in the SERVER list. If you see only the subscription name and no selectable entries, first check whether it can be updated before proceeding.

Existing server details: enter them by protocol

In Add Server, select the protocol specified in your details, such as Shadowsocks or VLESS, then fill in the address, port, and required authentication fields. Enter only the specified hostname or IP address in the address field, and put the port in its separate field. Protocol-specific transport and security options should also match the details. If required fields are missing, ask the provider of those details rather than filling them with values from another entry. Save and return to the list to check that the new entry appears. If several entries have similar names, distinguish them with recognizable labels; do not put passwords in labels.

Whichever method you use, next select a specific server in SERVER and confirm that the selected entry is the one you intend to test. A successful subscription import means only that the list has loaded; it does not mean the server is reachable. Saving a manually entered entry likewise does not confirm that authentication has succeeded. Note the selected name, then keep that entry selected while choosing a routing mode to avoid changing two conditions at once.

2. Choose Config, Proxy, or Direct in Global Routing

On Home, tap Global Routing and choose Config, Proxy, or Direct for the task at hand. This setting controls how traffic is handled after the connection is established; it does not select a server. Changing the routing mode does not modify saved server addresses or subscription links. After choosing a mode, return to Home, confirm the displayed mode, then connect.

ModeHow it handles trafficWhen to use it
ConfigApplies the rules and policies in the active configuration file.Check whether everyday routing matches the configuration.
ProxyRoutes traffic handled by the client through a proxy.Temporarily rule out routing rules and check the proxy path.
DirectConnects traffic handled by the client directly, without a proxy server.Compare with the proxy path.

Confirm the active configuration before using Config

The Config tab at the bottom is where configuration files are viewed and managed; Config in Global Routing tells the connection to follow the active configuration. They share a name but serve different purposes. If you have a configuration ready to use, first go to Config below and confirm that the intended file is selected. Then return to Home and select Config in Global Routing. Do not treat an imported subscription as a routing configuration: a subscription provides selectable servers, while a configuration determines how requests are handled.

If you only want to check whether the server works, you can briefly test with Proxy, then switch back to the intended mode. If a page opens with Direct, that shows only that the request succeeded over the direct path; it does not prove that the proxy server works. Conversely, selecting Config does not mean every site uses the proxy; different domains may match different rules. For the first test, do not change any rules—just note your selection.

3. Turn on the Home switch and allow the VPN configuration

Return to Home and check the selected entry under SERVER and the current mode in Global Routing. Once both are correct, tap the connection switch beside Not Connected at the top of the page. When connecting for the first time, your iPhone or iPad may show a system prompt to add a VPN configuration. Confirm that the request is from Shadowrocket, allow it, and complete any device verification prompts. Return to the app and wait for the status to change; do not repeatedly tap the switch before handling the system prompt.

If you previously dismissed the system prompt, return to Home and try turning the connection on once more. If the prompt does not reappear and the switch will not stay on, first check the VPN configuration status in system settings. If the device is managed by an organization or school, also confirm that its management policy allows VPN configurations. If another VPN connection is active and you can manage it, disconnect it before testing. Do not delete configurations whose purpose is unclear or disable device management restrictions.

A connected status at the top means the client's VPN connection has started; it does not mean the subscription updated successfully or that the selected server has been verified by an actual request. Keep the current network unchanged for now. For example, if you connected over Wi-Fi, complete the next step on the same Wi-Fi network. Do not switch to cellular while testing the server. This makes it easier to tell whether a failure is related to the network, server, or routing mode.

4. Verify with Connectivity Test and actual browsing

On Home, tap Connectivity Test, wait for it to finish, then check the result for the currently selected server. A response from another server in the list does not prove that the server in use is responding. If the selected entry times out, note the network, server name, and test result; do not delete the entry based on one timeout. The result reflects only the response to the test target at that moment. It is not a summary of access to all websites, and response time does not indicate download speed.

Next, open a browser and visit a known working page suitable for comparison in a new tab. Wait for actual page content to load, then refresh once so you do not mistake a previously opened page for a new request. If you are using Config, test both a target expected to use the proxy and one expected to connect directly. Before testing, confirm that the target domain matches the configuration rules. A site's home page, login page, and resources may use different domains, so opening the home page alone is not enough to assess access to the entire site.

If the result differs from what you expect, keep the same server and network, change only the routing mode, and revisit the same target. For example, if access fails with Config but works with Proxy, first check the active configuration and the policy matched by that domain. If both Proxy and Direct fail, first check whether the target or current network is working. After comparing, switch back to the intended mode and visit the page again. Recording the connection status, test result, and actual browsing outcome is more useful for troubleshooting than noting a single latency value.

5. Troubleshoot based on where the failure occurs

Identify the first step that did not go as expected: no entries in the list, the switch will not turn on, a server test times out, or the test responds but the page will not load. Check in order, resolve the earlier step, then test the next one again. If pages load normally and only one target does not follow the expected routing, you do not need to reinstall the app or recreate the subscription first.

The subscription is saved, but no servers appear

Return to Add details and confirm that the type was set to Subscribe and that you entered the complete link exactly as provided. Check whether you have a newer link than the one currently saved, then try updating over a working network. If entries still do not appear, ask the provider of the details to confirm that the link is valid and its response is suitable for the client. When reporting the issue, you can include the error message and time, but do not post the full link, authentication fields, or screenshots containing them in public discussions.

The switch turns off immediately after being enabled

Return to the connection steps and confirm that you allowed the system's VPN configuration prompt and that no other VPN is active on the device. Resolve any permission or connection conflict, then try again on Home. If the device is managed, note the system prompt and ask the device administrator to check. This happens during connection startup, so changing the server port or routing rules is not the first thing to check.

The server times out, or responds but pages will not load

Disconnect Shadowrocket and confirm that the current network can access a page that normally works directly. If basic access fails too, first address network sign-in, Wi-Fi, or cellular connectivity. Once the basic network works, reconnect Shadowrocket and check the server address, port, and protocol. If your list includes another server known to work, compare them on the same network and in the same mode. If only one entry times out, first check its details and availability; if several entries fail, consider common network or settings issues.

If Connectivity Test responds but browsing fails, repeat the browsing comparison and check whether the problem occurs only with Config. If the browser reports a domain name resolution failure, note the domain and message, then use the troubleshooting guide to check DNS and rules. If only images or the login page on one site fail, note the specific page. Change only one setting at a time; if it does not help, restore the original value before checking another factor.