If you tapped Don’t Allow
Go to Settings → General → VPN & Device Management (older systems may say VPN only). Delete the Shadowrocket row, return to the app, and flip the switch so the system asks again.
01
Line up three things before you start
Shadowrocket is a client, not a carrier. Missing any one of them, no amount of UI fluency will get you through. Download, switching regions, and spotting fakes: download page. Meanings: glossary. This handbook assumes the icon is already on the Home Screen.
| Required | Where it comes from | If you don’t have it |
|---|---|---|
| Official app | App Store, app ID 932747118 |
Enterprise signing, IPAs, and Android wrappers are out of this handbook’s scope |
| A working line | Your own provider: a subscription URL, a QR code, or a parameter sheet | The switch flips; the tunnel is empty |
| System VPN permission | The configuration request iOS shows on first connect | The app can’t take over traffic and will keep failing |
| A working network | Wi-Fi or cellular itself is up | Switch to Direct to check; if the phone can’t get online, don’t blame the client first |
Don’t paste a mystery subscription from a forum or group chat. Whoever controls that URL can change your exit.
02
First open: get VPN permission right
The home list is usually empty after you open it. Don’t hunt for nodes yet—finish system authorization. Permission and “do you have a line” are two different things.
- Open Shadowrocket. Notifications and Local Network can follow your habit; the one that actually blocks you is VPN.
- Find the connect switch (often at the bottom or top of Home). You can tap it once even if the list is empty.
- The system shows “Shadowrocket Would Like to Add VPN Configurations.” Tap Allow, then confirm with Face ID, Touch ID, or a passcode.
- Return to the app. The tunnel is only “allowed to be built,” not already connected to a line.
The system prompt looks like this
“Shadowrocket” Would Like to Add VPN Configurations. This will allow the app to filter your network traffic and monitor your internet use. [Don’t Allow] [Allow]—on an official store install, this is the same door iOS gives every VPN-class app. Tap Allow. It is not malware.
If it suddenly can’t connect later
After an iOS update the configuration sometimes dies. Same fix: delete the old configuration → re-authorize. Don’t reinstall first, and don’t start by changing node ciphers.
This section is done when Shadowrocket is visible in the system VPN list and the app is no longer refused the moment you flip the switch. The list can still be empty.
03
Import: four doors, pick the matching one
The + at the top right of Home is the load door. What you got from the provider usually belongs to only one of the rows below. Don’t try all three and end up with a pile of duplicate, expired entries.
| What you have | Door | How you update later |
|---|---|---|
| A long https subscription URL | + → type Subscribe |
Update this one row; don’t hand-build dozens of nodes again |
| A QR code | Scan, or recognize from the photo library | Scan again when the code changes; a single node will not refresh itself |
ss:// vmess:// trojan:// text |
Copy first, then see if “Add from Clipboard” appears | Same as a single node; re-import after it changes |
| A sheet of address, port, password, protocol | Fill in by protocol type | Edit the field that changed |
Subscription (most common)
- Tap
+, set type to Subscribe. - Paste the full URL. Check
https://or the scheme your provider wrote; no leading/trailing spaces, no line breaks. - Put the provider’s name in the remark so multiple subscriptions are easy to tell apart.
- Save and return to the list. Pull to refresh, or open that subscription and tap Update.
- Nodes should appear in a batch. Count is 0: stop. Check the URL and the plan. Don’t hammer Update.
A subscription is a remote list. When the provider changes lines, you only update this one row. A port you edit on a single node may be overwritten on the next update—keep lasting changes on the provider’s side.
Scan
- In
+, choose Scan and point at a computer or another phone. - Code in the photo library: use library recognition. Don’t send it through a social app and scan from there; compression often breaks recognition.
- Success usually adds one row. That’s a single node, not a subscription.
Clipboard
Copy the shared text in full and return to Shadowrocket. If you see “configuration detected on the clipboard,” confirm add. No prompt: switch to manual, or ask the provider for a subscription URL.
Manual entry
In +, pick the protocol that matches the provider. The name can be yours; what actually decides whether it connects are the fields after:
| Field | What to fill | Common mistakes |
|---|---|---|
| Address / Host | Domain or IP, exactly as written | Putting the port in the address, or dropping a subdomain |
| Port | A number on its own | Left empty, or written as 443443 |
| Password / UUID | Paste as-is | An extra line break or space after an email forward |
| Cipher / transport / TLS | Match the method, path, and hostname the provider wrote | Picking whatever “looks more secure” from memory |
| Remark | Only affects how the list displays | Editing a remark will not resurrect a dead node |
This section is done when the list has at least one config with a clear source. Not time to flip the switch yet.
04
Update first, test second, tap to select last
A successful import does not mean the currently selected row works. Flip the switch with nothing selected and you may connect an old node—or nothing.
- Open that subscription and tap Update, or pull down on Home. Count suddenly 0: check the provider dashboard for expiry and device limit first.
- Connectivity-test a few rows (swipe left, long-press, or open details—depends on version). Look at latency and handshake, not the peak speeds in ads.
- Skip timeouts and failures. Tap a row with acceptable latency that can handshake, and confirm it’s selected.
What a speed test is for
A successful handshake plus latency you can live with. Third-party “speed test” apps measure the whole device’s exit, which may not be the row you selected, so they can’t convict a single node.
How often in a day
Once when you change networks is enough. Hammering test like a refresh button will not resurrect an expired plan.
This section is done when you have a node you just tested, in the selected state.
05
Three modes, then flip the switch
Order: select a node → pick a mode → flip the switch. “Switch on but pages won’t open” is usually the wrong mode or node, not a broken app.
Config
Split by rules: tunnel what should tunnel, Direct the rest. Daily default. Saves power and is less likely to break local apps and the LAN.
Proxy
Send as much traffic as possible into the tunnel. Good for troubleshooting, or a short spell when rules clearly missed a domain. Don’t make it the all-day default.
Direct
Same as power-off. Use it to compare “is this the client, or can the phone itself not get online.” You can stay here when you’re done.
- Confirm a node is selected. Put the mode on Config first. Don’t start on Proxy as a beginner.
- Flip the connect switch. VPN in the status bar means the system tunnel is up.
- Open a site you know should go through the tunnel and confirm it loads.
- Then open a local bank, intranet, or a site that should stay in your country and confirm it wasn’t dragged far away. If it was, it’s usually rules—or you’re actually sitting on Proxy.
Success means all three: switch on, latency acceptable, and you can say whether this app should tunnel or go Direct. Missing one: compare on Direct, then change nodes. Don’t start by changing ciphers.
06
Split routing, DNS, and switches to leave alone for now
Touch settings only after you can get online stably. If the subscription already brings rules, watch for a few days. Two maps stacked is a common reason things get “slower the more you tweak.”
How to add a rule
A site that shouldn’t be Direct but is: switch to Proxy to verify. If it opens, go back to Config, add a rule, and write down what you changed so you can roll back. Don’t live in global for one site.
How to fill DNS
Prefer the value your provider wrote in their notes. Empty or following the system is usually safer than a random public DNS. A bad fill makes split decisions wrong: switch on, this site still won’t come out.
| Option | What it does | Advice |
|---|---|---|
| MITM / HTTPS decryption | Install a certificate and split open encrypted traffic | Leave it off if you don’t understand certificate chains |
| IPv6 | One more address family | Keep the default when the node and the local network aren’t ready |
| UDP | Some calls and games use it | Turn it on per the provider’s notes; don’t treat it as an accelerator |
| DoH / DoT | Encrypt DNS queries | Turn it on with documentation; don’t run several at once |
Changing ciphers, randomly swapping ports, or turning on MITM at the same time will almost never save a dead node or an expired subscription. Those two only go to the provider.
07
How to turn it on and off day to day
- Daily use stays on Config, not all-day Proxy. Global shoves video, system updates, and local printing down one node—slow and power-hungry.
- You can switch back to Direct when you’re done. It doesn’t have to stay on.
- Feels slower: update the subscription and switch to a node you just tested, then consider settings.
- The same subscription on multiple devices follows the provider’s device limit. Over the limit looks like a blank update or everyone timing out.
- A Home Screen widget can only flip the switch quickly; it cannot replace “pick a node, then a mode.”
- If it suddenly fails after you change Wi-Fi / cellular, test a few nodes first, then check permission.
08
Can’t connect: check by layer, change one thing at a time
Decide the layer first: permission, subscription and nodes, or mode and rules. Don’t flip five switches at once.
| Symptom | Layer | What to do |
|---|---|---|
| Fails the moment you flip the switch | Permission | Delete the old VPN in Settings, return to the app, and allow again |
| The list is empty | Subscription | Check whether the URL is complete, expired, or over the device limit |
| Nodes are there but all time out | Node / local network | Switch to Direct to confirm the phone can get online, then try another row. If they all fail, ask the provider |
| Switch on, pages spin | Mode / rules / DNS | Try Proxy once; if it opens, a rule was missed—go back to Config and add it |
| Only some apps fail | Split routing | Verify with Proxy the same way. Edit rules after you’re sure. Don’t reinstall first |
| Especially power-hungry or hot | Habit / node | Switch back to Config, use Direct when idle, and avoid nodes that clearly drop packets |
| Broken after an iOS update | System configuration | Delete the configuration and re-authorize; if that fails, reinstall the official app, then update the subscription |
| UI or signature doesn’t look official | Source | Delete it and reinstall only from the App Store. Don’t fix a crack |
- Switch to Direct: can the phone itself get online? If not, fix Wi-Fi / cellular first.
- If it can: return to the app and confirm VPN permission is still there.
- Update the subscription, switch to a node you just tested, put the mode on Config, then flip the switch.
- Still failing: try Proxy once. If that works, it’s rules or DNS; if not, give the node name and approximate time to the provider.
09
Delete, new phone, backup
Deleting the app may wipe the local list. The subscription URL is still in your email or the provider’s dashboard—walk section 03 again after reinstalling.
- New iPhone: restore Shadowrocket in the App Store with the original purchase account, then import the subscription. An iCloud backup alone may not bring back the VPN configuration in full.
- After restore you still have to allow VPN once more.
- Whether Family Sharing can pass the app to family members follows Apple’s current rules and whether this app supports it. Whether the line travels too depends on the provider, not the store.
- Don’t restore a third-party “config backup” from a mystery site. That’s handing your exit to someone else.
The official app can be installed again; the line lives on your own subscription. Keep the two apart and a new phone isn’t scary.