Shadowrocket Setup Guide

Add a server and import a subscription

First identify what kind of information you have, then choose the right option. Details for a single server usually include its protocol, address, port, and authentication parameters. A single-server URI encodes these details in an importable string; a server subscription link retrieves a list of entries. A remote configuration file may also include DNS, rules, and policy settings. A link beginning with https:// alone doesn’t tell you which type it is. If you’re unsure, check the original instructions instead of repeatedly importing the same link through different options.

Enter details manually: Home → Add Server

Open Home in Shadowrocket and tap the add button in the upper-right corner to open Add Server. Under Type, choose the protocol that matches your existing details, such as Shadowsocks, VMess, VLESS, or Trojan. Then enter the server address, port, and authentication details in the corresponding fields. Fields differ by protocol, so don’t enter one protocol’s parameters into another. The address field usually takes only a hostname or address, not a webpage path; enter the port exactly as provided.

If your details specify TLS, a transport method, Host, or SNI, enter each value as provided. Don’t guess based on the label or use a display name as a connection parameter. After saving, return to Home and make sure the entry appears in the list. Give it a recognizable label if helpful, but refer to your original service details when making changes. Seeing the entry in the list doesn’t confirm that its parameters are correct; test it in a later step.

Server subscription: Add Server → Subscribe

If you have an existing server subscription link, choose Subscribe under Type in Add Server, enter the full link in URL, and save it with a recognizable label. Preserve the link’s path, query parameters, and capitalization. When copying it, check for trailing spaces, line breaks, or punctuation from a chat message. Return to Home and wait for the subscription to load, then check for the expected group and server entries. If the list is still empty, check the import result before turning on the connection.

Saving a subscription and loading its contents are separate steps. If loading fails, check that your current network can reach the link, that it’s still valid, and that it returns a server subscription format supported by the app. A link may contain access credentials, so protect it like a password. Don’t share the full URL in public screenshots, comments, or support requests. This guide explains how to use details you already have; it doesn’t obtain or verify private links.

Subscribe on Config and other import options

Subscribe on the Config tab is for remote configuration files, not server subscription groups on Home. Use it only when you’ve confirmed the link points to a complete configuration file. Follow the prompts to save it, inspect its contents, and check which configuration is currently active. A configuration file may change DNS and rules, so understand its source and behavior before using it.

Scan an existing QR code with Scan QR Code. To import a single-server URI, use the clipboard import prompt provided by the app. Grant camera or clipboard access only when the relevant action requires it. After importing, check the protocol, server address, and label. Don’t import the same details repeatedly using manual entry, QR scanning, and the clipboard. Once Home shows at least one selectable server, continue to Global Routing.

Choose Global Routing

A server entry determines the parameters used for the proxy connection. Global Routing determines how requests are handled. Return to Home, tap Global Routing, and choose Config, Proxy, or Direct. For your first test, avoid changing the mode, DNS, and rules all at once. Decide what you’re testing and choose the corresponding mode so you’ll know which layer to check if it fails.

For everyday rule-based routing, choose Config and confirm the active configuration file on the Config tab. Rules are usually matched from top to bottom, and the first matching rule determines the policy. Requests that don’t match an earlier rule are handled by FINAL. PROXY, DIRECT, and REJECT specify different actions, while custom policy groups require checking which option is selected within the group. Choosing Config doesn’t automatically create rules suited to every use case.

To test a newly added server, you can temporarily choose Proxy, then return to Home and select the server. After a successful test in Proxy mode, switch back to Config to verify the rules. Direct can help you check your basic network connection, but a website loading in Direct doesn’t prove that the server works—the request didn’t use it. Keep track of the current mode so you don’t mistake direct access for a successful proxy connection.

If you’re new to rules, read the overview of rules and configurations before making changes. There’s no need to add automatic triggers such as On Demand at this stage. Manual control makes it easier to tell when a connection starts and stops. Once you’ve chosen a mode and server, continue with system authorization.

Turn on the connection and authorize it in iOS

Return to Home, tap the server you want to use, and make sure the selection indicator is on the intended entry before turning on the connection switch at the top. If your configuration includes a policy group, check its selection too, as it determines the actual outbound route. A server name is only a label; don’t assume the right entry is selected based on a similar name.

When you connect for the first time, iOS may ask permission to add a VPN configuration. This system permission lets Shadowrocket handle the relevant network traffic on your device and authorizes the VPN configuration on this device. Review the prompt, confirm the app name, and allow access. Complete verification with your device passcode or biometric authentication if requested. If you cancel, the switch may turn off when you return to Home. Start the connection again and respond to the system prompt rather than adding the server again.

After authorization, return to the app and check whether the connection switch stays on and whether any connection error appears. The system VPN indicator can help you check the connection, but its location varies by device and system version. Don’t rely on its presence in the status bar as your only check. If the switch turns off immediately, note the message and check system authorization, the active configuration, and the server parameters.

During testing, check whether another VPN configuration is also active or whether device management restrictions apply. Confirm which configuration is actually in use to avoid confusing results from repeatedly switching settings. Leaving the app in the background is not the same as manually disconnecting. To end a test, return to Home and turn off the connection. If needed, check On Demand conditions in Settings to avoid mistaking an automatic reconnection for a faulty switch.

The iPad layout may be wider than the iPhone layout, but the steps are the same: select an entry on Home, then control the connection switch. Don’t reimport everything just because the layout differs. Once the connection stays on, move on to testing access and policies. A “connected” status alone doesn’t prove that the network is working.

Verify access and rule behavior

Verify the connection in three stages: check whether the server is reachable, whether the destination actually opens, and whether the request follows the expected policy. On Home, run Connectivity Test for the selected server. The result shows reachability under specific test conditions; it doesn’t mean every website or protocol will work. The reported time isn’t a download speed or a complete measure of service quality.

Next, open a browser and visit a familiar website you’re authorized to access. Refresh the page and check that its content and necessary resources load. Keep the destination the same during testing; if needed, add a second destination for comparison. Don’t change the server, website, and network all at once. The browser may show cached content, so make a new request rather than relying on a page that was already open.

In Proxy mode, check whether the selected server path can load the destination. In Config, also check the matched rule and the policy actually used. In Data, find the connection record for the request by its time and destination domain, and review any rule and policy details shown. Different record types may display different fields, so check the information available in the record. An increase in total traffic alone doesn’t prove that the request used PROXY.

In Config, a request matching DIRECT isn’t necessarily an error; what matters is whether it matches your expectation. A website may use several domains. If the text loads but images don’t, check the requests for the failed resources, not just the main domain. If a rule assigns REJECT, the destination being unavailable may be expected. Compare your intended route with what the connection record shows before deciding whether to change the configuration.

For comparison, test the same destination in Proxy and Config and note the results. If Proxy works but Config doesn’t, check the rules, policy group, and DNS settings first. If both modes fail, check the server and basic network connection. After comparing, restore your usual mode and don’t leave temporary troubleshooting settings in place.

Common issues: what to check first

When something goes wrong, first identify what happened: did the subscription fail to load, did the switch turn off immediately, did Connectivity Test return no result, or does only one website fail to open? Each symptom calls for a different check. Change one condition at a time, retest the same destination, and note the result. Replacing the entire configuration may change the symptoms, but it makes the cause harder to identify.

Check your network and server details first

Turn off the connection and check that your device’s network works on its own. If the Wi-Fi network requires a login, complete that step first. Updating a subscription or re-entering server details won’t usually help if the underlying network isn’t connected. If needed, test on another network you can use to see whether the problem is limited to the current one.

Once the basic network is working, check the server address, port, protocol, authentication fields, and TLS parameters. If a subscription loaded before but no longer works, use the app’s update option to reload it. Check whether the update completed and whether the entries changed. If the update fails, keep the existing details for reference rather than deleting the whole group. Check link validity, account status, or server status through your own service provider.

Then check the mode, DNS, and rules

Make sure Global Routing isn’t set to Direct if you expect traffic to use a proxy, and that requests meant to connect directly aren’t being routed through a proxy by mistake. In Config, check the active file, policy group selection, and FINAL. If Proxy works but Config doesn’t, check the rule matched by the request instead of reinstalling the app. Rule order matters too: an earlier broad rule can prevent a more specific rule later in the list from being applied.

DNS issues can let a server test return a result while a destination domain fails to resolve or only some page resources load. Check whether the active configuration uses custom DNS and whether the specified addresses are reachable on your current network. Don’t enable multiple DNS options you don’t understand, or assume an address is more suitable based on its format alone. Note the original settings before changing them, and restore them if the test doesn’t help.

Finally, check individual destinations and automatic connections

If only one destination fails, distinguish between a connection timeout, a DNS resolution failure, an error returned by the service, and an access-permission message. Receiving an error from the destination service is different from failing to establish a connection. Account sign-in issues or the destination service’s own status aren’t necessarily caused by the proxy. Check the Data records from the same time and focus on the failed request; one page’s result doesn’t describe every connection.

If the connection starts again after you manually turn it off, check On Demand and its triggers in Settings. During troubleshooting, you can temporarily disable automatic triggers and confirm that manual connections work, then restore your settings. For questions about system authorization or getting the app from the store, see the App Store purchase and account guide. It covers purchasing, checking device compatibility, and restoring a previous purchase, so there’s no need to revisit those steps while troubleshooting the network.

When you’ve finished troubleshooting, return to the Global Routing selection step and restore your intended mode, then retest using the connection verification steps. To investigate “connected but no internet” in more detail, read the troubleshooting guide to servers, modes, DNS, and rules. When asking for help, share only the error message and steps you’ve tried. Hide subscription links, passwords, authentication parameters, and other private information.