OFFICIAL MANUAL / FIRST CONNECTION

Shadowrocket Setup Guide: Import a Subscription and Connect for the First Time

Follow the steps in order: import, routing, connection, testing, and troubleshooting. First establish a connection you can verify, then adjust rules and automatic connection settings.

iPhone / iPad
An Existing Subscription or Server Details
Five Steps

STEP 01 / IMPORT

Add Server: Add a Server or Import a Subscription

Open Shadowrocket and go to Home. First identify what you have: a subscription URL that updates a server list, or details for a single server, such as its address, port, and credentials. These use different forms, so don’t identify a link by its length alone. If you’re unsure, check your provider’s description of what it’s for. For your first setup, leave the connection switch off until you’ve saved the details.

Have a Subscription URL? Choose Subscribe

On Home, tap the add button in the upper-right corner to open Add Server. Open the Type list and choose Subscribe, then paste the full subscription URL into the URL field. You can add a name you’ll recognize in the remarks field. Check that the URL is complete, especially at the beginning and end, and make sure you haven’t copied spaces, line breaks, or chat text. Don’t edit or remove parameters from the URL.

Confirm, then use the save option on the page to return to Home and wait for the subscription to load. A successful import means selectable servers appear under the subscription—not just a subscription name. If you see a group but no servers, check for an error message, then update the subscription once. Don’t add the same URL repeatedly instead of updating it; doing so makes it harder to tell which server list you’re testing.

Subscription URLs often contain access credentials, so treat them like account information. Don’t post a full URL in a public forum or submit it to an unfamiliar website for testing. Updating a subscription in the app fetches the current server list from that URL; it is separate from updating Shadowrocket through the App Store. When the list changes, update the existing subscription and confirm that your selected server is still there.

Have Details for One Server? Fill In Its Protocol Fields

If you have the details for one server, choose the protocol specified by your provider in Add Server, then fill in the server address, port, and required authentication fields. For example, Shadowsocks and VLESS use different authentication fields; don’t switch the Type just because the address is the same. Enter TLS, transport, and server name fields as provided. Don’t enable or disable them based on guesswork.

If you have a QR code for importing a single server, use Scan QR Code to read it. Before saving, check the detected Type and server address. A QR code only carries information; it doesn’t guarantee the settings are valid. If scanning fails, check the original details rather than guessing the port or credentials. See the Glossary for protocol field definitions.

After saving, return to Home, tap the server you want to use, and confirm it’s selected. This only confirms that the details are in the client; it doesn’t prove the server can connect. Next, choose how requests should be routed, then turn on the connection. This helps you avoid judging the import before you know which mode is active.

Input: An existing subscription URL or complete server details.
Result: A selectable server appears on Home, and one entry is selected.
Next: Open Global Routing and confirm the mode you’ll use for this test.

STEP 02 / GLOBAL ROUTING

Global Routing: Choose Config, Proxy, or Direct

Return to Home and tap Global Routing to check the current mode. This controls how requests are handled; it doesn’t select a server region or update a subscription. Note the current selection so you can tell whether later differences come from the server or the routing settings. The three modes are Config, Proxy, and Direct.

Config: Config: Handles requests according to rules and policies in the current configuration file. Requests may use PROXY, DIRECT, or REJECT.
Proxy: Proxy: Routes requests handled by the client through the proxy. It’s useful as a baseline test for your first connection.
Direct: Direct: Connects directly. A successful request in this mode does not verify that the proxy path works.

To test an existing server for the first time, you can start with Proxy. This temporarily removes rule matching as a variable; then turn on the connection in the next step. Proxy applies to requests handled by the client, not as an absolute guarantee for all traffic on the device. After selecting a mode, return to Home and confirm it has changed and the intended server is still selected.

If you plan to use Config, open the Config page and check which configuration file is active. The Config page is for managing configurations; Config in Global Routing is a routing mode. The names are the same, but the actions are different. A server subscription is not a complete rule configuration, and importing a server list doesn’t confirm that a rule file is active.

If you’re unsure what rules are in the current configuration, leave it unchanged before your first connection. First use Proxy to confirm the server path works, then switch back to Config for comparison. Some requests may connect directly under Config by design; that doesn’t mean the connection switch has failed. See Rule Keywords Explained for DOMAIN-SUFFIX, FINAL, and policy definitions.

STEP 03 / CONNECT

Home: Connect and Approve the System Prompt

On Home, check the selected server and Global Routing mode again, then turn on the connection switch at the top. The first time you connect, the system may ask permission for Shadowrocket to add a VPN configuration. This means the app wants to create a system connection configuration for handling network traffic; it doesn’t mean the system has verified the remote server details you entered. Review the prompt, make sure you initiated the action, then approve it and complete any required authentication.

After approval, return to Shadowrocket and check that the switch and connection status remain on. The connection indicator may appear in a different place depending on the device, so don’t rely only on whether a particular status bar icon is visible. Authentication can still fail, the connection can time out, or the server may be unreachable. Establishing the system connection and confirming that the remote proxy path works are two separate checks.

If you previously denied permission, return to Home and try connecting again; check whether the system prompts you again. If the switch immediately turns off, read the app’s message, then check the relevant VPN configuration in system Settings and whether the device has restrictions. On a managed device, follow its management requirements; don’t delete existing management configurations just to complete this guide.

Once the connection stays on, don’t switch between multiple servers or change Global Routing at the same time. Get a test result in the next step first. To stop testing, return to Home, turn off the switch manually, and confirm the app shows that you’re disconnected. If the connection starts again automatically, check for On Demand or other automatic connection settings.

STEP 04 / VERIFY

Connectivity Test: Check the Connection and Routing Rules

With the connection on, run Connectivity Test on Home to test the selected server. Wait for the test to finish and check whether it returned a result for that server. The test value reflects one test method under current network conditions; it is not a measure of webpage loading speed or a guarantee of ongoing availability. A timeout is worth investigating, but one timeout doesn’t prove that all requests will fail.

Test Page Access, Then Check Rule Matches

Open a browser and visit a lightweight page that normally works. Wait for a new request to complete. Don’t rely only on an already open page, since cached content may still display after disconnecting. Then test a separate page and note whether everything fails, only some pages fail, or pages just load slowly. A problem with one website doesn’t necessarily point to Shadowrocket.

Return to the app and check connection records or relevant information available in Data. Find the request you just made and check the policy and route used. If the record shows a matched rule, confirm it’s what you expected—for example, a destination expected to connect directly matches DIRECT, while a destination expected to use the proxy follows the selected server or the corresponding policy in your configuration. An increase in traffic counters alone doesn’t prove that a specific request used the proxy.

If Proxy worked and pages loaded, switch to Config and revisit the same pages. Keep the server and local network unchanged for a fair comparison. If only Config behaves differently, first check the active configuration, rule order, and policy selection; don’t immediately reimport the subscription. Rules may route a request to a policy other than the server currently selected on Home, so check the actual connection records.

Evaluate the Results in Three Stages

Stage one is “the client is connected,” confirmed by the switch and app status. Stage two is “the server path works,” confirmed by Connectivity Test and actual page access. Stage three is “the rules behave as expected,” confirmed by the match record for the same destination. These stages are not interchangeable. A connected client alone doesn’t prove a subscription works; even after confirming the server path, check that Config routes requests as expected.

To compare with your regular network, note the current routing mode, disconnect manually, request the same page again, then reconnect and repeat. Change one condition at a time so the results are meaningful. When you’re done, keep the mode that suits your everyday use; there’s no need to keep switching servers to chase a lower test value.

Connection: The switch stays on and the app shows a stable connection.
Request: A new request to a real webpage completes successfully.
Routing: The rules, policies, and routes shown in the request record match your expectations.

STEP 05 / TROUBLESHOOT

Common Issues: Start with the First Step That Fails

Troubleshoot by asking, “Which step first failed to produce the expected result?” If there’s no selectable entry on Home, start with the import. If authorization isn’t complete, resolve the system connection prompt first. If the connection works but some pages don’t load, check page access and rules. Don’t reset configurations, reimport the subscription, and change networks all at once. That removes useful comparison points and may overwrite information that was already correct.

The Subscription Is Empty or Import Fails

Check that the full URL is correct and that it’s intended for subscriptions. Make sure you didn’t enter a service information webpage address or omit parameters when copying. The current network must be able to reach the URL to load the subscription; the fact that the client opens doesn’t mean the subscription URL is reachable. If you see an authentication or format error, keep the error text and ask your service provider to check the URL status and supported format. Don’t share the full URL or change its authentication parameters without knowing the cause.

If importing a single server fails, check Type first, then compare the address, port, authentication, TLS, and transport settings one by one. A missing field is not the same as an incorrect value, and saving successfully doesn’t prove the values are right. Check the details read from a QR code, too. If required information is missing, refer to the original instructions rather than trying common defaults.

The Switch Turns On, but Requests Fail

First confirm that the selected server is still in the updated list, then test it with both Connectivity Test and a real webpage. If you have multiple existing servers, switch only the server for one comparison and leave the routing mode unchanged. If possible, repeat the same tests over Wi-Fi and cellular. This helps identify whether the issue follows a particular server or only occurs on one local network.

If all tests fail, check whether the server address resolves and whether the port and authentication details match. Note the error type shown in the app: a connection timeout and an authentication failure call for different checks. For a timeout, focus on network reachability; for an authentication failure, verify the credentials and protocol first. Don’t treat every symptom as simply “connection failed,” and don’t rely on repeatedly toggling the switch as a fix.

Proxy Works, but Some Requests Fail in Config

In Config, first confirm which configuration file is active, then check the match record for a failed destination. See whether it matched the expected rule, whether the policy points to an available server, and whether it was assigned DIRECT or REJECT. For domain resolution issues, distinguish between a domain that didn’t resolve and a connection that failed after resolution. Don’t change several DNS settings at once during initial troubleshooting. Keep the current settings and note the evidence first. See the Glossary for related terms.

If only certain destinations fail while others work, check those destinations, their matching rules, and the route used before deleting configurations. If the issue is slow loading, compare a lightweight page with the affected request and test at similar times. A single latency result can’t account for differences in bandwidth, server load, destination response times, or local network quality.

Record Reproducible Details Before Continuing

Note the device type, local network, Global Routing mode, protocol in use, step where the failure occurred, and the exact error shown in the app. Before sharing records, redact subscription URLs, server credentials, and other personal data. Keep only the details needed to diagnose the issue. A clear report such as “the same server works in Proxy, but one destination fails in Config” is usually more helpful than reinstalling repeatedly.

The first-use process is complete when you can import the details, select a server, connect, load a real page, and understand how the rules handled the request. For specific errors, see Frequently Asked Questions. For App Store storefronts, purchases, and restoring on a new device, see the App Store Guide. This guide covers the basic manual connection workflow. When adjusting On Demand or more complex configurations later, continue changing one condition at a time and testing the result.