WireGuard peer configuration is the process of telling each device in a WireGuard VPN who its partners are, how to reach them, and which traffic they should accept. Every device, called a peer, holds a private key and lists the public keys of the peers it trusts.
This guide explains each setting in plain language, shows how the pieces fit together, and offers a checklist you can use before you connect. It assumes you already run or plan to run a self-hosted VPN server, and it focuses on the peer settings rather than the operating system steps, which differ between platforms and change over time.
Why a Single Peer Entry Decides Whether Your Tunnel Works
Imagine you have just installed WireGuard on a home server and a laptop, and the tunnel refuses to come up. Often the cause is not the software but one missing line in a configuration file. WireGuard is deliberately minimal, so each peer entry carries real weight, and a single wrong value can silently block all traffic.
A peer entry tells a device three things: which key identifies the other side, where that side can be reached, and which network addresses should travel through the tunnel. Each piece must agree with the matching settings on the other device. When they do, the handshake succeeds and encrypted packets begin to flow.
Understanding this structure makes troubleshooting far easier. Instead of guessing, you can check each value in order, starting with keys, then endpoints, then allowed addresses. The rest of this article walks through that order so the logic stays clear.
The Building Blocks: Keys, Endpoints and Allowed Addresses
WireGuard uses public key cryptography, meaning each device has a private key it never shares and a public key it can distribute freely.
A public key is derived from the private key using a mathematical function, so the two always belong together. Your server and each client generate their own pair, and each side stores only the other side’s public key in its peer section.
The endpoint is the network address and port where a peer can be contacted, written as a host name or IP address followed by a colon and a port number.
Only the side that is reachable on the internet, typically your server, needs a fixed endpoint. A client behind a home router usually omits it and simply waits for the server to respond.
AllowedIPs is the most misunderstood setting. It serves two purposes at once: it lists which addresses a peer may send traffic from, and which destinations should be routed to that peer. Setting it to a broad range sends more traffic through the tunnel, while a narrow range sends less. Choosing carefully here shapes what your VPN actually protects.
Core Settings Every Peer Section Should Include
Most WireGuard peer sections rely on a short set of directives. Knowing each one lets you read an existing file or write a new one with confidence. The following items cover the settings you will encounter most often in a basic setup.
- PublicKey, the base64 string that identifies the remote peer and must match its private key
- Endpoint, the host name or IP address and UDP port where the remote peer accepts connections
- AllowedIPs, the list of addresses this peer may use as sources and the routes sent to it
- PersistentKeepalive, an optional number of seconds that keeps a connection open behind some firewalls and NAT devices
These four directives form the heart of a peer entry. Not every peer needs all of them. A server often omits PersistentKeepalive because it waits for clients to start contact, while a roaming laptop frequently benefits from it. Keep the list short, verify each value, and avoid adding settings you do not yet understand.
Generating and Exchanging Keys Without Exposing Secrets
Key generation should happen on the device that will use the key, so the private half never travels across a network. WireGuard provides command line tools that create a private key and derive the matching public key.
Store the private key in a file readable only by the administrator, and treat it like a password that must never appear in a chat message or screenshot.
Exchanging public keys is safe, because a public key reveals nothing that helps someone impersonate a peer. You can copy them between devices through a trusted channel, such as a note on your own network or a file you transfer directly. Verify each copy carefully, since a single character error produces a peer that never matches.
Plan a simple rotation habit as well. Keys can be replaced when a device is lost, sold, or reinstalled. Update the peer entry on the other side at the same time, otherwise the tunnel will stop working. Recording which key belongs to which device, in a private note, makes these updates far less error prone.
Matching Server and Client Peer Entries Correctly
A working tunnel requires that each side lists the other with consistent information. The server holds one peer section per client, each containing that client’s public key and a single AllowedIPs address assigned to it.
The client holds one peer section for the server, containing the server’s public key, its public endpoint, and the networks it should route through the tunnel.
Address planning is where many setups go wrong. Each client needs its own unique address inside the tunnel subnet, and the server’s AllowedIPs entry for that client should match exactly. If two clients claim the same address, the server cannot tell them apart, and traffic may reach the wrong device or be dropped entirely.
Think of the two sides as mirror images. Whatever the server expects from a client must be what the client sends, and whatever the client expects from the server must be what the server provides. Checking this symmetry before you test saves considerable time.
Common Peer Configuration Patterns for Real Networks
Peer settings change depending on what you want the VPN to do. Three patterns cover most home and small office needs, and each uses the same building blocks in a different way. Choosing the pattern first makes the individual values easier to fill in correctly.
Remote Access for a Single Laptop
This pattern lets one laptop reach your home network from anywhere. The client’s peer entry for the server sets AllowedIPs to the home subnet plus the tunnel subnet, so only home-bound traffic travels through the tunnel. Ordinary browsing continues over the normal connection, which often keeps speeds higher and reduces load on your server.
The server side lists the laptop with a single address in its AllowedIPs. Because the laptop initiates contact from behind a router, enabling PersistentKeepalive on the client, often set to a modest value such as 25 seconds, helps keep the path open. Test by reaching a device on the home network from the laptop using its local address.
Keep the laptop’s peer section tidy and avoid listing the entire internet unless you intend to route all traffic. This pattern is a good first project because it exercises every core setting without introducing the complexity of routing everything.
Full Tunnel for Privacy on Untrusted Networks
A full tunnel sends all of a device’s traffic through the VPN, which suits people using public Wi-Fi.
To achieve this, the client’s AllowedIPs for the server peer is set to a route covering all IPv4 addresses, commonly written as the full address range with a zero-length prefix. The tunnel then carries every outbound packet, and the server forwards it onward.
This configuration demands more from the server, which must forward traffic, perform network address translation, and handle DNS correctly. A full tunnel also requires attention to IPv6, because traffic that bypasses the tunnel over IPv6 can expose activity even when IPv4 is protected. Verify the path with a leak test after setup.
Full tunnels do not make you anonymous, and they shift trust to whoever operates the server. Be realistic about what the setting protects, and understand that it hides your traffic from the local network while leaving the destination sites able to see the server’s address.
Site to Site Links Between Two Networks
Connecting two separate home or office networks lets devices on each side reach the other as if they shared a building. Each side defines the other as a peer, and each lists the remote network’s subnet in its AllowedIPs.
Both sides need an endpoint if they can be reached, or one side can be the initiator while the other is publicly reachable.
Address planning matters more here because the two local networks must not overlap. If both use the same common home range, traffic will be routed incorrectly and connections will fail in confusing ways. Choose distinct private subnets before writing any peer section, and document them so future changes remain consistent.
Routing on each local network may also need a rule or a static route so that return traffic reaches the tunnel. Without this, the link may appear up in the configuration yet still fail to pass data. Test from a device on each side to confirm traffic moves in both directions.
Testing and Troubleshooting Your Peer Settings
Testing is most reliable when you change one setting at a time and verify the result. Start by confirming that the interface comes up and that each side reports a recent handshake. A handshake that never appears usually points to a wrong public key, a wrong endpoint, or a firewall blocking the UDP port, which is a useful early clue.
If the handshake succeeds but traffic does not pass, examine AllowedIPs first. A narrow range that omits the destination will silently discard packets, and a missing route on the operating system can have the same effect. Confirm that forwarding is enabled on the server and that the firewall permits traffic from the tunnel interface.
Keep a written record of the working configuration before you experiment. Restoring a known good file is far quicker than reconstructing settings from memory. Logs and status commands from the WireGuard tools reveal handshake timing and transfer counters, which help you see exactly where the path breaks.
Keeping Your Peer Configuration Secure Over Time
A peer configuration is only as safe as the files that hold it. The private key in each interface section is the most sensitive value in the entire setup, so restrict file permissions to the administrator account and avoid storing copies in shared folders or cloud notes.
If a private key is exposed, generate a new pair immediately and update every peer that trusts it.
Review peer lists periodically and remove entries for devices you no longer own or use. A forgotten peer is an unnecessary way in, even though WireGuard only accepts traffic from known keys. Consider assigning meaningful comments in your configuration so you can recognize each entry months later without guessing.
Security also depends on keeping the software current and on protecting the server itself. Apply operating system and WireGuard updates promptly, limit administrative access to trusted accounts, and enable a host firewall that allows only the UDP port your tunnel uses. These habits reduce risk far more than any single setting.
A Pre-Connection Checklist for Peer Configuration
Before you bring a new tunnel into daily use, run through a short checklist. Each item targets a mistake that appears frequently in home and small office deployments, and confirming them takes only a few minutes compared with the time lost to troubleshooting later.
- Confirm each peer’s public key matches the private key stored on the device it describes
- Verify the server endpoint uses the correct public address or host name and the configured UDP port
- Ensure every client has a unique address inside the tunnel subnet with no overlap between peers
- Check that AllowedIPs on each side covers exactly the networks you intend to route through the tunnel
Once these items check out, bring the tunnel up and confirm a recent handshake on both sides. Run a short connectivity test to a device on the far network, then a leak test if privacy is the goal.
If anything fails, return to the checklist before changing several values at once, since that approach makes the original cause harder to find.
Planning Your Next Steps With Self-Hosted WireGuard
With peer configuration understood, you can plan the next stage of your self-hosted VPN with more confidence. Begin with a single client and a clear goal, such as reaching one home device securely while travelling. Once that works reliably, add further clients one at a time, documenting each new address and key so the setup stays manageable as it grows.
Consider how you will manage changes over the long term. A simple inventory listing each device, its assigned address, its public key, and the date it was added helps when you need to rotate keys, retire a device, or move the server to new hardware. Keeping this record current is one of the most practical habits you can adopt.
Remember that a VPN protects specific parts of your traffic and no more. Pair your tunnel with sound habits such as current software, strong account passwords, and careful review of what your devices share. A well-configured WireGuard setup is a valuable part of a broader privacy practice rather than a complete solution on its own.