For readers with a WireGuard client configuration who are ready to add it manually to Shadowrocket. Start by using [Interface] and [Peer] to distinguish the local device from the peer, then check whether the intended traffic should go through the tunnel. If the connection fails, check the handshake, destination IP, DNS resolution, and packet size—in that order. There’s no need to change several settings at once.
Add WireGuard from Home
These steps use an iPhone or iPad as an example. Before you begin, ask the administrator of the service you already use to confirm that your configuration is for this device—not a server or another device. Both can contain [Interface] and [Peer], but the keys and addresses belong to different endpoints.
- In Home, tap the + in the top-right corner. Open Add Server, then select WireGuard under Type.
- Enter the local address, keys, and peer connection details from the original configuration. If the interface has separate host and port fields, split
Endpointinto two values. Don’t append the port to the host field as well. - After saving, return to Home, select the WireGuard entry you just added, and turn on the connection switch. If prompted to add a VPN configuration, follow the device instructions. Turning on the switch only enables the local connection; it doesn’t confirm that the peer has completed a handshake.
- Visit a destination the administrator has confirmed should use this entry. If you’re using Config under Global Routing, first make sure no rule routes that destination to
DIRECTor another outbound.
What PrivateKey, PublicKey, and Endpoint refer to
The field names below follow the conventions used in common WireGuard client configuration files. They explain what each parameter means; form labels may vary by platform. Example addresses are reserved for documentation and are not usable endpoints.
Local device: [Interface]
PrivateKey- The private key for this device. Use the complete value assigned to the local device. Don’t enter its public key here or remove the trailing
=. Address- The tunnel address assigned to this device, such as
192.0.2.10/32. Keep the original prefix length; don’t enter the server’s public IP address. DNS- Use the resolver specified in the original configuration. For example, if the resolver is on a remote private network, make sure requests to it can take the required route.
MTU- The tunnel interface’s maximum transmission unit, in bytes. Keep the value from the original configuration if one is specified. If not, leave the client’s default behavior unchanged.
The administrator needs the local device’s public key, not its private key.
Peer: [Peer]
PublicKey- The peer’s public key, which the client uses to identify the remote endpoint. Don’t derive a public key from the local private key and enter it here.
Endpoint- The peer’s reachable address and UDP port, such as
192.0.2.20:51820. For IPv6 in a single field, use the format[2001:db8::20]:51820. AllowedIPs- The address prefixes routed to this peer, such as
198.51.100.0/24. This is not the localAddressfield, and it doesn’t take a domain name. PresharedKey- An optional preshared key. If it’s set in the original configuration, it must match the peer’s configuration. Don’t substitute either public key for it.
PersistentKeepalive- The keepalive interval, in seconds. Use it only if the configuration requires it or you need to maintain a NAT mapping. For example,
25sends a keepalive every 25 seconds.
51820 is a common example port, not a fixed value. Use the UDP port the peer actually listens on.
If you change PrivateKey, ask the administrator to update the local device’s registered public key on the peer as well. Changing the client key without updating the peer prevents a handshake, even when the address and port are correct. When troubleshooting, don’t send configuration files or screenshots containing PrivateKey or PresharedKey.
How AllowedIPs and Global Routing work together
AllowedIPs determines which destination addresses WireGuard sends to the peer. It’s also used to check the source addresses of inner packets received from that peer. Global Routing determines whether Shadowrocket sends a connection through this outbound. Both layers must allow the traffic: adding a destination network to AllowedIPs doesn’t change Shadowrocket’s routing rules, and routing a connection through WireGuard doesn’t automatically add its destination to the peer’s address range.
/32/1280.0.0.0/0::/0Bottom line: check the destination IP before changing the prefix
For example, if the destination is outside 198.51.100.0/24, first confirm whether it should go through the peer. Don’t change the prefix to 0.0.0.0/0 just to make a test pass. If a domain returns both IPv4 and IPv6 addresses, check which address family is actually being used.
- Route only specified networks: Keep the approved network, such as
198.51.100.0/24. If the remote DNS resolver isn’t in that network, check whether the administrator requires its address prefix to be added separately. Don’t confuse the DNS address inside the tunnel with the path outside the tunnel used to resolveEndpoint. - Using a default route prefix:
0.0.0.0/0doesn’t include IPv6. Use::/0from the original configuration only if the peer is set up to forward IPv6 traffic and IPv6 coverage is needed. A default route prefix is also not the same as the app’s Proxy mode.
Troubleshoot handshake failures, DNS issues, and MTU
Use the same destination and network for each test, changing only one setting at a time. If Endpoint is a domain name, it must resolve before the tunnel comes up. A DNS resolver reachable only through the tunnel can’t resolve the endpoint for that initial connection.
| Issue | What to check |
|---|---|
| No handshake after sending a request to the destination | If the client doesn’t show handshake status, ask the administrator to check the peer’s latest handshake. Verify the Endpoint host and actual UDP port, the peer’s public key and preshared key, and that the peer has the local device’s public key registered. Being able to browse regular websites doesn’t mean the UDP port is reachable. |
| Handshake succeeds, but the destination IP is unreachable | Check which outbound the app selected, whether the destination is covered by the local AllowedIPs, and whether the peer has the correct prefix and return route for the local tunnel address. A successful handshake doesn’t mean forwarding is configured for the destination network. |
| Destination IP is reachable, but the domain fails | First check whether the domain resolves and whether the resolver is reachable. Then compare the returned addresses with the routing result. Don’t rely only on opening an HTTPS site by IP address in a browser: certificate validation or virtual hosting can also cause the request to fail. |
| Small requests work, but large responses repeatedly stall | Once you’ve ruled out an issue with the destination service, test the path MTU. Note the original value—for example, temporarily change 1420 to 1380—and retry the same request. This difference is for diagnosis, not a general recommendation. If it doesn’t help, restore the original value. |
Get Shadowrocket for every platform
Get Shadowrocket for iPhone and iPad from the App Store for a one-time payment of $2.99. The developer is Shadow Launch Technology Limited; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Download their installers from this site’s download page.