Shadowrocket Official Manual / Setup Guide
Shadowrocket
Import, Connect & Verify
Follow five steps using the iPhone or iPad interface. First check that the server connects, then verify how rules handle requests.
If a usable server entry is already available, continue from step two. If installation is not complete, first read Download and first-launch instructions. Do not confuse system installation prompts with in-app connection errors.
STEP 01 / IMPORT
Add a server or import a subscription
Identify the information you have before choosing where to enter it. A single server entry usually includes a protocol, server address, port, and password or identity fields. A subscription link retrieves a list of server entries. A config file may also contain rules, policies, and other settings. These serve different purposes, and the appearance of a link alone does not identify its type. Follow the instructions for your existing service details. Do not enter a config file URL in the server address field or use a webpage description URL as a subscription link.
Enter details manually with Add Server
Open Shadowrocket, go to Home, and tap the add control in the top-right corner to open Add Server. First choose the protocol that matches your existing server, then enter its address, port, and authentication details. The protocol determines which fields appear, so select it before entering the details. Do not choose a similarly named protocol just because a field is unfamiliar. Parameters are not interchangeable between protocols.
Check the server address for accidental spaces, make sure the port is complete, and preserve the original capitalization in password or identity fields. If your service details include a transport method, TLS, server name, or path, enter those according to the original instructions; do not enter only the address and password. Save, return to Home, and confirm the new entry appears in the SERVER list. Saving an entry does not confirm that the server can connect.
Import an existing subscription with Subscribe
If you have a subscription link, open the Config page and find the subscription action for Subscribe. Paste the complete link as prompted and confirm retrieval. Links often contain query parameters, so copy the entire string—not just the domain—and do not include explanatory text from a chat message. If the system asks to read the clipboard, allow access only after confirming it contains the information you intend to import.
When retrieval is complete, return to Home and check that the SERVER list contains entries for the subscription. If a config file appears in Config but there is still no selectable server in Home, check the imported content type. A downloaded file does not mean a server has been imported. The entry location may vary slightly between interface layouts; confirm whether the operation applies to a server subscription or a config file.
Check QR code imports
If you already have a server QR code, use Scan QR Code from the Home scanning entry. On first use, grant camera access when prompted by the system. After scanning, check the parsed protocol and address before confirming the addition. QR codes and subscription links may contain authentication details; do not post them in public forums or include their full contents in troubleshooting screenshots. After importing, select one specific entry and continue. Avoid repeatedly importing the same subscription, as duplicate entries make later checks harder.
At this stage, Home should contain the expected server and show its type and required parameters. If a subscription link cannot be recognized or an update leaves the list empty, troubleshoot the retrieval process in step five. For differences in entry points, see Four ways to import.
STEP 02 / ROUTING
Choose a Global Routing mode
Once a server entry is available, choose how requests are handled. Return to Home, open Global Routing, and check the current selection. The three modes are Config / Proxy / Direct. They control request handling; they are not connection quality levels and do not change the server's protocol or authentication details.
Config: use the active config
With Config selected, requests are evaluated against the rules in the active config. In Config, check which file is actually selected, rather than merely confirming that a file appears in the list. Downloading a file and setting it as the active config are separate actions. Editing an inactive file does not change the rules in use. For first use, choose an existing config whose purpose you understand and keep its original contents. Avoid changing many rules at once, or it may be difficult to identify the cause of an issue.
Rules are usually matched from top to bottom, and the matching rule determines the policy. PROXY sends requests to the corresponding proxy policy, DIRECT connects directly, and REJECT blocks the request. The final FINAL rule handles requests that did not match earlier entries. Check the active config to confirm where each policy points. Selecting Config does not mean that every request uses the current server.
Proxy: test the server path
Proxy is useful for a focused connection check: on the same network, select a server and test a specific target. If the target works with Proxy but not Config, focus on the config file, rules, and policy destination instead of immediately re-entering server details. When the test is complete, switch back to the mode you need for everyday use rather than leaving a temporary test setting in place.
Direct: check the local network path
With Direct selected, ordinary requests do not go through the selected proxy server. This can help compare the basic network path with the proxy path, but it does not show whether a remote server is working. If you expect a target request to use a proxy while Direct is selected, the result may still be direct even when the connection switch is on. Note the selected mode before continuing, and keep that condition clear during each check.
If you are unsure where to start, use Proxy to check whether the existing server can handle the target request, then use Config to verify the rules. You do not need to write a complete config here. See Global Routing settings for details about each option, and Protocol reference for protocol parameters.
STEP 03 / CONNECT
Select a server and turn on the connection
Return to Home and explicitly select the server you intend to use in the SERVER list. Do not assume that a newly imported entry is automatically selected; check the selection indicator in the list. If you have several servers, keep one entry selected during the test instead of switching between them. This makes it possible to relate the result to specific parameters.
Before connecting, use Connectivity Test to check the result. A time value means that a response was received under those test conditions; it does not guarantee that every website, app, or request will work. A timeout should also be assessed in light of the test method and actual access results. Use the test to narrow down the issue, not as a substitute for verifying page access in the next step. Do not compare displayed values without checking whether the server can complete a real request.
After checking the server and Global Routing, turn on the connection switch in Home. On the first connection, the system asks whether to allow a VPN configuration. Confirm that you are authorizing the intended app, select Allow, and complete any device passcode or other identity verification requested by the system. This permission creates a system network configuration; it is separate from the server password. Do not enter your device passcode in Add Server.
After granting permission, return to Home and check whether the switch remains on, then check the system connection status. If the switch immediately turns off, first look for a config error, permission prompt, or another active connection. Avoid rapidly toggling the switch. You can close other active VPN connections and then retry in Shadowrocket. Keep one clear test state at a time to avoid confusion from switching system connections.
A switch that stays on indicates that the client has entered a connection state. It does not confirm successful remote authentication or that target requests are being routed as expected. Do not change DNS, rules, or protocol parameters yet. Keep the current conditions and proceed to the next step to test an actual request. If you need to change servers, note the original entry and result, then repeat the same checks.
STEP 04 / VERIFY
Verify access and rule results
Check three things: whether the switch is on, whether the target is accessible, and whether the target uses the expected policy. The system VPN indicator only confirms that the system connection is active in some form. A page opening successfully may also mean that the target was reachable directly. Assess the result alongside the current Global Routing mode, selected server, and request records.
Repeat a specific request
In a browser, open a target page you are authorized to access and whose expected behavior you know. Reload it and wait for the result. Use a new request rather than relying on a page that has already loaded or cached app content. For the first check, keep the same network, server, and target. Note whether the page loads normally, waits for a long time, or shows a specific error. Each result suggests a different troubleshooting path.
Check where requests go in Data
Return to Shadowrocket and review the request records or connection details in Data that correspond to the visit. Locate them by request time and target domain. Check the policy used, any visible rule match, and the server destination rather than only looking for a change in data usage. Background device activity may also generate requests, so an increase in total traffic alone does not prove that the test target went through a proxy.
With Config selected, if the record shows DIRECT but you expected PROXY, check the active config rules. First confirm that the target domain matches the rule, then check for an earlier matching entry, and finally check the policy destination. A page may request several domains; the main document, images, and APIs may not match the same rule. Changing only the rule for the page address may not affect all its subrequests.
Narrow the cause by changing one variable
If access fails with Config, keep the same server and temporarily switch to Proxy, then repeat the request. If Proxy works but Config fails, check the rules and active config first. If both fail, investigate the server details, network connectivity, or the target itself. After the comparison, restore the intended mode and test access again. Do not change the network, server, and config at the same time; otherwise, even if access recovers, it will be unclear which change made the difference.
The check is complete when the target is accessible as expected and the policy in the request record also matches your expectation. If you need to describe the issue to someone else, share only the necessary symptoms, mode, and error text. Hide server authentication details and subscription links. For more about rule order, read Custom rules and the FINAL fallback.
STEP 05 / TROUBLESHOOT
Troubleshoot based on where the process fails
When something goes wrong, first identify the stage: subscription import, server test, switch staying on, or target access after the switch is on. Do not apply fixes for one stage to another. In particular, do not delete all configs or reinstall the app as soon as a timeout occurs. That removes useful comparison conditions and does not fix outdated server details.
Basic network and subscription retrieval
Temporarily turn off the connection and confirm that the device's Wi-Fi or cellular network works; complete any required network sign-in first. Once the basic network is working, check that the subscription link is complete and still valid, and see whether retrieval returned an error. If the imported list is empty, check whether the service details have changed or the returned content is still in a supported format. If a refresh fails, keep any existing working entries and avoid creating duplicates by repeatedly adding the same subscription.
Updating a subscription retrieves a new server list; Connectivity Test checks the reachability of an entry. These are different actions. If an update succeeds but a server still times out, continue checking that server. If an update fails but an older entry still connects, that does not mean all connections have failed. See Manual and automatic subscription updates for update locations and common causes of failure.
Server timeout or authentication failure
Return to the Add Server edit screen and compare the protocol, address, port, and authentication fields with your existing service details. Then check TLS, server name, transport method, and path. Do not omit fields that may look optional but are required by the server. If the system time is clearly incorrect, restore the correct time before testing; a time discrepancy can affect certificate or authentication checks. If needed, test the same server on another network you are authorized to use to identify local network differences.
If tests continue to fail, ask the provider of your existing service to confirm the server status and whether its details have changed. Share symptoms and error text only; do not disclose the full link or authentication details. Changes such as replacing a password or switching protocols should have a clear reason, not be random attempts to find a working combination. See the Server timeout and connection failure checklist for a full troubleshooting sequence.
Switch is on, but access is unexpected
First check whether Global Routing is set to Direct by mistake, then confirm which config is active in Config. If Proxy works but Config does not, follow the sequence “target request → first matching rule → policy destination.” If only one target has an issue, check its domain resolution and request records instead of immediately changing all DNS settings. Record the original value before making a change, change one item at a time, and repeat the same request.
If the page document loads but images or APIs fail, check the domains for the failed resources separately instead of treating the page as one connection. If system authorization is incomplete, resolve that first. If the switch stays on but the remote server does not respond, check the server and request path. Identifying the failing layer makes recovery easier and preserves results that can be reproduced.
Finish testing and keep a working setup
After the connection recovers, confirm that the selected server, Global Routing mode, and active config are the combination you intend to keep. Remove temporary changes made only to locate the issue. When you do not need a connection, return to Home and turn off the switch. Before using it again, confirm the server selection and turn it on. For common entry-point and permission questions, see the FAQ. For detailed protocol field descriptions, see the Protocol reference. There is no need to change every advanced setting during the first connection.