Shadowrocket Setup Guide

First identify what information you have, then choose how to add it. A complete URL used to update a server list should usually be imported with Subscribe. If you have the protocol, address, port, and authentication details listed separately, add a single server manually. Subscription URLs and config URLs serve different purposes, so don't choose between them based on how the URL looks. If you're unsure, check the instructions that came with the details.

Enter details manually with Add Server

Open Home in Shadowrocket, find Add Server in the SERVER section, and tap it. Choose Type first, then enter Host, Port, and the relevant authentication details. The fields shown depend on Type. For example, Password and Method in the screenshot apply to the selected type; they aren't required for every protocol. Match each field to your own server details, and don't fill in fields that don't apply.

Enter the server's domain name or address in Host and the supplied port in Port. Don't enter a webpage path, a full subscription URL, or extra spaces in Host. The password, encryption method, and other protocol parameters must match your existing details—don't guess. If any required information is missing, check with the provider before continuing.

Save the entry and return to Home. Check that it appears under SERVER and that its name matches your records, then select it. If you have a compatible QR code, use Scan QR Code in Add Server and check the parsed details before saving. Import from Cloud JSON is for the corresponding data format, not a general-purpose way to import any URL.

Import a full URL with Subscribe

If you have a subscription URL, open Add Server from Home, set Type to Subscribe, enter the full URL in the appropriate field, and add a recognizable name. Include all query parameters when copying the URL, especially anything after the question mark. A URL may contain access credentials. Check it on your device, and don't share the full URL in public screenshots or chat logs.

After saving, return to Home and wait for the subscription to load. Use its update action if needed. Check that the list contains server entries, not just a subscription name. If no entries appear, first confirm that the URL returns subscription content the app can parse—not a login page, notice page, or ordinary webpage. Saving a subscription only records the input; it doesn't mean the content was fetched and parsed successfully.

By the end of this step, you should have at least one server entry you can select. Keep the original details for reference, but don't create duplicates as a substitute for troubleshooting. Next, choose Global Routing. You need to know how requests will be handled before you can interpret the connection test.

Return to Home, tap Global Routing, and check the currently selected mode. The three modes are Config / Proxy / Direct. They determine how requests are handled; they are not server protocol names. Changing modes won't fill in server details or fix an expired subscription.

Check the current config before using Config

If you want requests routed according to rules, open Config and check which config is active and what it contains. The official screenshot shows the config editor sections General, Rule, Hosts, URL Rewrite, and HTTPS Decryption, with Add Rule under Rule. You don't need to edit every section to connect for the first time. Keep settings you've already confirmed, so server connection issues don't get mixed up with complex config changes.

A subscription is mainly used to retrieve or update a server list. Config organizes rules and related settings, so the two aren't interchangeable. Even after importing a subscription successfully, check that the active config meets your needs. Don't enable a config if you don't know where it came from or what it does just because it has many entries. Avoid changing HTTPS Decryption unless you have a specific reason.

This example shows how to read rules; it isn't a recommendation to replace your current config. The first line sends example.com and its subdomains through PROXY. The second sends the specified local network ranges through DIRECT. The final line handles requests that didn't match earlier rules. Rule order and the final action affect the result.

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

For your first test, note which mode you selected. To use existing rules, choose Config and check the config. To isolate a server connection issue, you can briefly switch to Proxy for comparison. Restore your usual mode after testing so temporary settings aren't left in place. For more on rule matching, see the system guide.

After adding your details and choosing a mode, return to Home. Select the server you want to use under SERVER, and check that the selection indicator is on the right entry. A subscription group and a server within that group are different items; seeing the group name doesn't mean you've selected a server. If several entries have similar names, distinguish them by their labels first.

Tap the connection switch at the top of Home. The first time you connect, iOS may ask to add a VPN configuration so the app can handle the relevant traffic through the system network extension. Confirm that the prompt was triggered by your action, then follow the system prompts to authorize or authenticate. Authorization allows the configuration to be created; it doesn't confirm that server authentication, DNS, or rules are correct.

After authorization, return to Shadowrocket and check whether Not Connected is still displayed at the top and whether the switch remains on. If the app still shows a disconnected state, first confirm that authorization is complete and a server is selected, then try connecting once more. Avoid repeatedly tapping the switch before checking the status, or it may be unclear whether the last tap started or stopped the connection.

Connection status isn't the same as availability

An enabled switch means the connection process is running, but a website may still fail because of the server, DNS resolution, or rule handling. The VPN status in iOS alone can't confirm that a request used the selected server. Next, make a real request and compare the result with the selected mode, test results, and logs.

If the connection turns off shortly after you enable it, or quickly returns to Not Connected, note the selected entry, mode, and error message, then check for issues. The layout may differ on iPad, but you can still check Home, SERVER, and Global Routing. Don't rely only on the exact button positions in a screenshot.

After connecting, keep the network conditions unchanged for now. Don't switch Wi‑Fi, change DNS, and select a different server at the same time. Keeping conditions stable makes the next test easier to interpret. If you change several things at once, you won't know which one fixed the issue—even if the page starts loading.

When something fails, keep the current settings and note what happened. Start with the input details closest to the source. Change one thing per attempt, then repeat the same test and browser request. If nothing improves, restore the original value before checking the next item. This prevents troubleshooting from creating new problems.

Subscription won't load: Check the URL and response

Review the existing subscription details. Check that the URL is complete, has no spaces at either end, and doesn't include copied instructions. Confirm that your network can access the subscription URL, and note whether the error is a timeout, authentication failure, or content parsing failure. These point to different issues—network path, access credentials, and content format—and can't all be explained by trying another update.

If the response isn't a server list, ask the original provider to confirm what the URL is for and whether it's still valid. Don't keep adding duplicate entries to retry, and don't post the full subscription URL in a public help forum. Once corrected, update only that subscription and return to Home to check that actual server entries appear.

Can't connect: Check the server and mode

For a manually added server, check Type and Host first, then Port, authentication, and any protocol-specific parameters. For entries created from a subscription, first check whether an update is needed; don't edit multiple entries if you're unsure what the fields mean. Then check the server selected on Home and whether Global Routing is still set to the mode you intend to test.

If the connection stays up but a particular website fails, use the Proxy and Config comparison from the previous section to narrow down the cause. If only one domain fails, check its DNS resolution and matching rules first. If most requests fail, check the server connection or current network. Record the original values before making changes so you have a baseline for comparison.

Check DNS, Test Method, and On Demand separately

If you suspect DNS, first check whether failures are limited to domain names, then review the DNS settings in the current config and any relevant diagnostics. Don't treat an arbitrary DNS address as a universal fix. DNS resolution, server connectivity, and rule handling are related but distinct; use the error details to check each one. For more configuration guidance, see the Shadowrocket system guide.

Open Settings and check Test Method to see which method Connectivity Test uses before interpreting the result. Settings also includes On Demand, which can connect automatically under specified conditions. If the app reconnects after you turn it off manually or changes state when you switch networks, review the existing conditions. For your first manual test, check the current On Demand status and avoid adding multiple conditions at once.

TCP and UDP may behave differently. A webpage loading doesn't necessarily mean an app request that relies on UDP will work. Check whether the server and protocol parameters support your actual use case, then review the relevant logs. Don't rule out issues with other transport paths just because a webpage loads.

Keep only the diagnostic details you need

To investigate further, use Diagnostics in Settings and record the error message, network type, selected mode, and steps to reproduce the issue. To compare Wi‑Fi with cellular, change only the network and repeat the same request. Treat any difference as a clue about network conditions, not a reason to reset all settings immediately.

Before sharing diagnostic information, remove passwords, access parameters from subscription URLs, and any personal request history that isn't needed. Explain where the problem occurs, which mode you used, what error appeared, and what you've already compared. There's no need to share full connection details. Once the issue is resolved, restore your usual settings, remove duplicate test entries, and confirm that a normal request works.