Official Manual · First Connection
Shadowrocket Quick Start
Import, Connect & Verify
This guide uses the iPhone / iPad interface. Start by importing the details you already have, choose Global Routing, then verify the result with an actual visit. Follow these five steps for your first setup; there is no need to change every setting at once.
- 01 Import details
- 02 Choose a mode
- 03 Authorize connection
- 04 Verify results
- 05 Find the issue
First, make sure you can copy the complete subscription link, or that your server details include the protocol type, address, port, and required authentication fields. Subscription links may contain personal access credentials; do not post them in public comments, screenshots, or chat groups. If you already have a configuration, save a copy before following these steps so you can restore the original state if something goes wrong. This is easier to troubleshoot than changing several unfamiliar settings in succession.
The screenshots below are official App Store screenshots to help locate Home, Add Server, Config, and Settings. The layout may change with app updates, so follow the English interface labels and fields shown on your device. For more on configuration management, see the subscription management manual. This page covers only the shortest path to your first connection.
STEP 01 / IMPORT
Add Server: Add a server or import a subscription
Open Shadowrocket and go to Home. When you first open the app, the SERVER group may not contain any entries yet; this means connection details have not been added. Open Add Server, identify whether you have a subscription link, a single-server share link, or fields to enter manually, and choose the matching method. Do not enter every kind of information as a Host address.
Existing subscription: choose Subscribe
In Add Server, select Subscribe under Type and paste the complete subscription link into the URL field. Check the beginning, end, and query parameters in the middle to make sure you have not included instructions, line breaks, or spaces. You can add a note to help identify it, such as “Personal subscription”; the note is for your own management and does not replace the link. Save, wait for the app to read the subscription, then return to Home and check the corresponding group and server entries.
Saving subscription details does not guarantee that the server list was retrieved successfully. If the group is empty or an error appears, first check that the link is complete, the current network can reach the address, and the link is still valid. Repeatedly adding the same subscription will not fix a retrieval problem and may create duplicate entries once the list loads. For full details on subscription updates and group organization, see the Subscribe management section.
Existing server details: check each field
To add a server manually, select Type first, then fill in the fields required for that type. Enter the server address in Host and the port in Port; match Password, Method, and other fields to the details you already have. Requirements vary by protocol, so the fields shown in a screenshot are not required for every protocol. Do not choose a different type just because its name looks similar, and do not paste a complete share link into Host. Details with paths, transport settings, or other parameters must also match field by field.
If you have a QR code, use Scan QR Code to read it, then check the parsed Type and server address. If the clipboard contains a supported share link, you can use the app's import prompt and review the result before saving. Import from Cloud JSON is a separate import option; do not treat an ordinary subscription link or arbitrary text as the corresponding file. If you are unsure what a field means, check the glossary instead of guessing authentication parameters.
After either import method, return to Home, find the server in the SERVER list, and confirm that its selection indicator is on the intended entry. At this point, you have prepared the connection details, but you have not chosen how traffic is handled or established a connection. Next, check Global Routing so the mode matches your needs before connecting.
STEP 02 / ROUTING
Global Routing: Choose how traffic is handled
Once the server appears in the list, return to Home and open Global Routing. This setting determines how traffic is handled; it is not a server protocol or system connection permission. The three modes are Config, Proxy, and Direct. Choose one based on what you need to do before connecting. Switching modes is not a general fix for every problem.
Config: Match rules in the active configuration
Use Config for rule-based routing in everyday use. The app handles requests according to the rules in the currently active configuration. A matching policy may be DIRECT, PROXY, or REJECT. So even with the connection on, not every request necessarily goes through the selected server. Open Config and confirm that the configuration you understand is selected; seeing a file in the list does not confirm that it is active.
The official screenshot shows the General, Rule, Hosts, URL Rewrite, and HTTPS Decryption sections in the Config editor. You do not need to change each section for a first connection or enable every feature just to import a subscription. A subscription is primarily used to retrieve and update the server list, while Config determines rules and other configuration content; these are separate settings. If your existing configuration meets your needs, keep it as is and verify access before making adjustments.
Proxy and Direct: use for a specific route
Proxy routes traffic through the selected proxy, which can help you compare the server path while troubleshooting. It cannot guarantee that the server is working correctly or compensate for incorrect protocol parameters. Direct connects without using the selected proxy server. If you want to test whether an existing proxy server works, browsing with Direct does not prove that the server is functioning.
Keep track of the mode you choose: use Config when you have a configuration you have confirmed; to distinguish a server problem from a rules problem, temporarily compare with Proxy and then restore the original mode. Avoid changing rules, switching servers, and changing modes at the same time, or it will be hard to identify the cause. Rule order and policy details are covered in the official subscription management manual and the rules glossary. Once you have confirmed the mode, return to Home to connect.
STEP 03 / CONNECT
Home: Turn on the switch and confirm system authorization
Return to Home and check two things: the selected server in SERVER is correct, and Global Routing is set to the mode you chose in the previous step. Then turn on the connection switch at the top of the screen. Not Connected in the official screenshot means the app is not connected yet. Having a server in the list or seeing a test result does not mean the connection has started.
The first time you connect, the system may ask you to confirm adding a VPN configuration. This authorization is needed for the app to establish a system network connection. Confirm that Shadowrocket initiated the request, read the prompt, and approve it as directed by the system. Your device may ask for your passcode or another form of authentication. Return to the app and check whether the connection status has changed. System authorization is separate from server account authentication; do not enter the server Password in a device passcode prompt.
If you previously declined authorization, the switch may not stay on. Try connecting again and respond to the system prompt instead of importing the subscription repeatedly. Another active VPN connection or a device management policy may also prevent the connection from starting. Check the current VPN status in system settings and stop any connection that does not need to run at the same time. For devices managed by a workplace or school, follow the device management requirements and do not remove management profiles without permission.
After turning on the switch, wait a moment and see whether it immediately returns to the disconnected state. If the connection stays on, continue to the next step. If it disconnects right away, note any error message or status and go to Troubleshooting; do not rapidly toggle the switch. A VPN status shown by the system indicates the relevant connection state, but does not mean every request will succeed or that all Config rules are behaving as expected.
While establishing the first connection, avoid changing networks, editing Type, or modifying rules at the same time. Keeping the conditions consistent makes it easier to identify the cause of any result. When you are done, return to Home, turn off the switch, and confirm that the connection has stopped. If On Demand is enabled, it may start a connection again based on its conditions. During initial troubleshooting, check that setting so an automatic reconnect is not mistaken for a faulty switch.
STEP 04 / VERIFY
Connectivity Test: Check the connection and actual access
Once the connection stays on, run Connectivity Test from Home. It checks connectivity to the selected test target, and the result depends on the test method, current network, and target response. A successful test is only one indication; it does not mean every website, app, or protocol is available. If a test fails, consider whether the target can respond before concluding from a single result that the subscription is invalid.
- Keep the current conditions.Note the selected server and Global Routing mode, run Connectivity Test once, and check whether it returns a result or times out. Do not update the subscription or switch servers during the test.
- Open a real page.Switch to a browser and visit a familiar page that is normally available. Open a new page or refresh it instead of relying on cached content. Seeing an old page does not necessarily mean the new connection worked.
- Compare with the expected route.In Config mode, some destinations may connect directly according to the rules. To check whether a destination is routed through a proxy, review the app's connection records and matching policy rather than relying only on whether the page opens.
If the test returns a result but the page will not load, first check whether the issue affects only one destination, then review its rules and DNS. If pages load normally but the test keeps failing, check the Test Method and test target before deleting the entire configuration. A latency value describes the response under the corresponding test conditions; it is not a file download speed and cannot, on its own, indicate the stability of a long-running connection.
For an initial check, consider the process complete when the switch stays on, actual requests succeed, and routing matches your expectations. There is no need to keep sorting or switching just to reach a particular number. Once verification succeeds, keep the working settings and adjust other features one at a time as needed. Before adding On Demand or more complex rules, read the subscription management manual, change one setting at a time, and repeat this check.
STEP 05 / DIAGNOSE
Settings: Troubleshoot each stage
When something goes wrong, identifying the step where it failed is more useful than saying only that it “won't connect.” Keep your current configuration and check the following in order. After each check, repeat only the steps related to it. Reinstalling, clearing the list, and changing networks all at once removes useful clues.
No entries after import: check the input and update
First confirm whether you imported a subscription link or a single-server share link, then check Type and the input field. If the subscription is empty, make sure the URL is complete, has no extra spaces, and did not return an update error. The server details come from the subscription you already have; the app cannot fill in missing fields. Do not share a subscription address containing credentials. To confirm whether the details are valid, use the information management channel you already have.
The switch will not stay on: check authorization and system status
Confirm that you completed the initial VPN authorization, then check the current VPN status and any device management restrictions in the system settings. If the switch turns off immediately, note the error shown in the app instead of changing Method or adding rules first. Testing the server network path is useful only after the app can start a connection. Restarting the app or device may help restore service, but it does not replace checking the specific error.
Connected but unable to access content: check the server, then the rules
For a manually entered server, check Type, Host, Port, and authentication fields. For an imported server, confirm that the selected entry is still valid. You can temporarily use Proxy on the same network for comparison, then restore the original mode. If Proxy works but Config does not, focus on the active configuration, the destination's matching policy, and DNS. If both fail, switch between Wi-Fi and cellular once if possible to identify a local network issue. Switching networks may incur data charges, so check your device settings first.
Only some situations fail: check the test method and records
Settings includes Test Method, On Demand, Diagnostics, Proxy, TCP, UDP, and other options. First check whether Test Method is appropriate for the current test. Do not change TCP- and UDP-related options at the same time because of one failed test. If only one app or destination has an issue, note the conditions, mode, and affected destinations. Check On Demand behavior separately so automatic connections are not confused with problems connecting manually.
If you need to investigate further, use Diagnostics to view or collect relevant records. Before sharing them, check for subscription URLs, server addresses, passwords, or other personal information; include only what is needed to reproduce the issue. For other issues, see Questions & Troubleshooting. For multiple subscription updates, duplicate entries, backups, and restores, continue with the subscription management manual. After troubleshooting, restore any temporary changes and repeat the connection and verification steps to confirm the result.
Other devices and app downloads
That completes the steps on this page. To use Shadowrocket on another device, choose the corresponding platform on the download page instead of assuming every screenshot location applies.
If you have completed the connection, continue with the subscription management manual to learn about updates, organization, and backups. To look up English interface labels, see the glossary; there is no need to import all your details again.