A WireGuard setup starts with identifying the local keys, peer keys, tunnel address, and public endpoint, then checking the route scope and MTU. This guide assumes you already have configuration details from your own provider or server. The steps use Shadowrocket on iPhone and iPad as an example; Mac, Windows, Android, and Linux users can match the field descriptions to their platform’s editor rather than following mobile button locations. Use the guide to verify each value’s source and distinguish handshake, routing, DNS, and packet-size issues.
1. Identify the local and remote sides before entering settings
WireGuard uses UDP and keys to identify both ends of a connection. It does not use a username and password: your device holds its own PrivateKey, and the server registers the matching local PublicKey. In the client’s Peer settings, enter the server’s PublicKey. Do not swap the two PublicKeys just because they have the same field name.
Where each setting belongs: local Interface or remote Peer
Local Interface
- PrivateKey: The device’s private key. Keep it only on trusted devices that need to use it.
- Address: The device’s internal tunnel address, not the server’s public address.
- MTU: The maximum packet size for the tunnel interface. Set it based on the configuration and actual network path.
- Local PublicKey: Derived from the local PrivateKey and provided to the server administrator for registration.
Remote Peer
- PublicKey: The server’s public key, supplied by the server administrator.
- Endpoint: The server’s reachable domain name or IP address and UDP port.
- AllowedIPs: The IP prefix ranges associated with this Peer.
- PresharedKey: An optional additional key shared by both sides. Don’t invent a value.
When checking a setting, always ask which side it belongs to. Never use the PrivateKey from a server configuration file as the client’s private key.
If your provider supplies a complete client configuration, use its matching keys and Address. If you generate a new key pair on your device, the server must also be updated with the new client PublicKey; changing only the phone’s PrivateKey breaks the existing pairing. Don’t post screenshots of a complete configuration or paste private keys into public forums.
2. Compare the PrivateKey, PublicKey, and address fields
The standard WireGuard field names below explain what each value means. Shadowrocket’s editor may not show every field in exactly the same way on every platform. For example, Endpoint may be split into an address and port, or local IPv4 and IPv6 addresses may have separate fields. Match settings by meaning rather than copying them based on field order.
| Field | Source and meaning | Common mistake |
|---|---|---|
PrivateKey | The matching private key generated on this device and registered with the server, or the client private key assigned by your provider. | Entering the server’s private key, missing trailing characters, or copying extra spaces or line breaks. |
PublicKey | Enter the server’s public key in Peer; the server separately registers the client’s public key. | Entering the client’s own public key as the remote Peer key. |
PresharedKey | An optional preshared key. If enabled, it must match exactly on both sides. | Entering a key when the server hasn’t enabled it, or using the PrivateKey by mistake. |
Address | The tunnel address and prefix assigned to this device, such as the example address 192.0.2.2/32. | Using the server’s public IP or reusing another device’s internal address. |
Endpoint | The server’s public address and actual UDP port, such as example.com:51820. | Adding a web protocol prefix or assuming every server uses port 51820. |
DNS | If present, this is a DNS setting specified by the associated tool; it is not part of the WireGuard handshake itself. | Using a DNS address as the Address, or assuming that changing this field alone applies all DNS settings. |
WireGuard PrivateKey, PublicKey, and PresharedKey values are typically Base64-encoded 32-byte data, commonly shown as 44 characters. Correct length does not mean the key is valid or that both sides are paired. Check every character against the original details instead of adding characters to make the length fit.
3. Add WireGuard from Home and verify the connection
Before opening the editor, have the local PrivateKey, assigned address, remote PublicKey, Endpoint, and any other fields required by your provider ready. Home manages connection entries; Config manages rule configuration files. Importing a rules file into Config does not create a working WireGuard entry.
-
Organize your details
Keep the original configuration somewhere secure, with local and remote settings clearly labeled. Note your current Global Routing setting. If you already have a working entry, keep it rather than overwriting it.
-
Choose the type
Open Home → tap “+” in the upper-right corner → Type → WireGuard. Enter values according to what each field means; editable fields and layouts vary by platform.
-
Enter the settings
Map Endpoint to the server address and port, then enter the local PrivateKey, local address, and remote PublicKey in their respective fields. Enter a PresharedKey only if it’s included in your original configuration.
-
Save and select
After saving, return to Home and select the WireGuard entry you just created. To reduce routing-rule variables, temporarily set Home → Global Routing to Proxy, then connect. If the system asks to add a VPN configuration, confirm as prompted.
-
Verify in stages
First, try a known reachable destination and check for ongoing data transfer. If you administer the server, check its latest handshake and traffic counters. When testing is done, restore Global Routing to your usual setting.
4. AllowedIPs and Global Routing operate at different layers
AllowedIPs is a set of IP prefixes in WireGuard. For outgoing traffic, it maps destination addresses to a Peer; for incoming traffic, it checks whether decrypted packet source addresses belong to that Peer. It does not accept domain rules—you can’t enter DOMAIN-SUFFIX,example.com,PROXY here.
0.0.0.0/0covers all IPv4 destination addresses, but not IPv6.::/0covers all IPv6 destination addresses. Confirm that the server can forward IPv6 traffic before using it.192.0.2.0/24represents one example IPv4 subnet; it does not include other subnets.- Some client integrations don’t expose an AllowedIPs field. If it isn’t available, don’t put the value in the PublicKey or address field, and don’t assume that pasting any standard configuration file will import every setting.
Shadowrocket’s Global Routing determines how traffic is handled at the app’s routing layer. Even if WireGuard’s AllowedIPs covers every address, traffic set to Direct in Global Routing won’t automatically use that entry. Conversely, selecting Proxy won’t fix missing server-side routes.
Config: Check your rules
RecommendedRoute traffic according to the rules and policies in the current Config. Check the order and target policies for DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL, and confirm that the requests you want are routed to the WireGuard entry or a policy group that includes it.
Best for: Everyday rule-based routing after verifying the connection.
Proxy: Reduce routing variables
Select a proxy route at the global routing layer to isolate differences caused by Config rules. Still check the selected entry, tunnel scope, and server reachability; this does not guarantee that every system request goes through the remote server.
Best for: Briefly checking whether routing rules are causing the issue.
Direct: Compare with a direct connection
Select a direct route at the global routing layer. This can help check whether the local network can reach the same destination, but a successful direct connection does not confirm that WireGuard is configured correctly.
Best for: Distinguishing an unreachable destination from a tunnel-path issue.
If you’re using Scene, first check which routing behavior the scene actually applies before comparing results. Settings → On Demand manages conditions for connecting on demand. It is not AllowedIPs and does not turn a domain into a proxy rule. Note its status while troubleshooting so automatic connection conditions don’t interfere with manual tests.
5. Adjust MTU and Keepalive based on symptoms, not a fixed value
MTU sets the maximum IP packet size the tunnel interface can carry. The outer network also needs to carry WireGuard, UDP, and IP headers, so the tunnel MTU is not simply the same as the physical interface’s MTU. 1420 is a common starting point, but the outer IPv4 or IPv6 connection, mobile networks, and other encapsulation can all affect the usable size.
| Observed symptom | Check first | What to try |
|---|---|---|
| No handshake at all | Endpoint, UDP access, key pairing, PresharedKey | Fix identity and reachability first; MTU is usually not the first thing to check. |
| Small requests work, but large pages or uploads stall | Path MTU, packet loss, and server forwarding | Record the original value. If the editor supports it, try lowering 1420 to 1380, then repeat the test with the same destination. |
| Access is slow to resume after the connection has been idle | NAT mapping timeout, network changes, server status | If both configurations allow it, consider PersistentKeepalive rather than repeatedly generating new keys. |
| Only domain names fail to load | DNS server reachability, resolution results, and the DNS route | Separate DNS resolution failures from connection failures. Don’t start by changing MTU or PublicKey. |
PersistentKeepalive = 25 sends a keepalive packet every 25 seconds when needed. It’s a common setting for clients behind NAT, not a requirement for every connection. It can help maintain a mapping, but increases background network activity and won’t fix a blocked port or incorrect keys.
Change only one variable per test, and record the network type, original value, new value, and reproduction steps. If lowering MTU doesn’t produce a consistent improvement, restore the original value and keep investigating. One successful page load is not a general conclusion.
6. How to read the example configuration and troubleshoot common issues
The text below uses standard WireGuard-style fields to illustrate their placement; it does not guarantee that every Shadowrocket platform can import it. All values are fake examples. The keys are deliberately invalid, and the domain and documentation address do not provide a real service. This configuration cannot connect and cannot be saved as a working setup.
[Interface]
PrivateKey = DEMO_PRIVATE_KEY_NOT_VALID
Address = 192.0.2.2/32
MTU = 1420
[Peer]
PublicKey = DEMO_SERVER_PUBLIC_KEY_NOT_VALID
PresharedKey = DEMO_PRESHARED_KEY_NOT_VALID
Endpoint = example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
When entering your settings, check each field against your own original details. If your provider hasn’t supplied a PresharedKey, don’t copy the example line. If you haven’t been assigned an IPv6 address or given IPv6 forwarding, don’t enable it just because the example includes ::/0. Verify MTU and keepalive values against your actual network as well.
Why is there no handshake even though I copied the PublicKey correctly?
First confirm that it’s the server’s public key, then ask the server administrator to verify that the Peer has the current client public key registered. Next, check the actual UDP port in Endpoint and the PresharedKey. A valid format only rules out formatting errors; it doesn’t prove the keys match.
The handshake works, but webpages won’t load. What should I check next?
First, confirm the selected WireGuard entry in Home and briefly test with Global Routing → Proxy. If it still fails, check IP forwarding, the outbound route, and the firewall on the server. If only domain names fail, check DNS; if only large requests fail, check MTU.
Can I copy the same configuration to my phone and computer?
Check first whether your provider assigns a separate Peer to each device. Reusing one private key and tunnel address across multiple devices can make the remote endpoint change unexpectedly. For simultaneous use, register each device’s public key, assign each one an address, and configure them separately.
The settings changed after a subscription update. Should I change them back manually?
First check whether the entry is managed by your own subscription. An update may overwrite settings supplied by the server. Distinguish manually created entries from subscription-managed ones, then ask your provider why the settings changed before deciding whether to keep your manual configuration or use the subscription-managed entry.
Get Shadowrocket and continue setup
The iPhone and iPad app is a one-time $2.99 purchase on the App Store; check the App Store listing for system requirements. The Mac (Apple silicon or Intel), Windows, Android, and Linux versions are free. Choose your device on the all-platform downloads page, then follow the setup guide. You’ll need to provide your own WireGuard server details.