How to Use a WireGuard Config File

What is inside a .conf file, line by line

Every WireGuard config has the same two-part shape. [Interface] describes your end of the tunnel; [Peer] describes the machine you are connecting to. Here is a complete client config with the secrets replaced by placeholders:

[Interface]
PrivateKey = YOUR_PRIVATE_KEY_KEEP_THIS_SECRET
Address    = 10.7.0.4/32
DNS        = 10.7.0.1

[Peer]
PublicKey           = THE_SERVER_PUBLIC_KEY_FROM_YOUR_PROVIDER
Endpoint            = 198.51.100.10:51820
AllowedIPs          = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

The [Interface] block: your side

• PrivateKey — this is your identity on the VPN. Anyone holding it can be you. It is 44 base64 characters ending in =; if yours is a different length, the file was truncated somewhere in copying.
• Address — the IP your device holds inside the tunnel, not your public IP. The /32 means "just this one address", which is normal for a client.
• DNS — the resolver used while the tunnel is up. Without it your device keeps asking your old resolver, which both leaks what you are looking up and often fails to resolve anything on the far side.
• MTU — optional, and the single most useful line to know about. It is missing from most files because the default is right; see troubleshooting for the case where it is not.

The [Peer] block: the server's side

• PublicKey — the server's public key. Yours never appears in your own file; the server holds it.
• Endpoint — where to send packets, as host:port. WireGuard is UDP only, and 51820 is the conventional port rather than a required one.
• AllowedIPs — which destinations go through the tunnel. 0.0.0.0/0, ::/0 means everything, which is what a privacy VPN is for. A narrower list — say only your company's internal range — sends just that through and leaves the rest on your normal connection. That arrangement is called a split tunnel, and it is a deliberate choice, not a broken full tunnel.
• PersistentKeepalive — sends a small packet every 25 seconds so the NAT device between you and the server keeps the return path open. Needed whenever you are behind NAT, which on a phone or a home connection you always are.

Windows: import the tunnel

Windows has an official WireGuard app, and importing a file into it is the whole job.

1. Install WireGuard from wireguard.com/install.
2. Click Add Tunnel at the bottom left, which opens a file picker filtered to Configuration Files (*.zip, *.conf). Pick your .conf and it appears in the tunnel list, named after the file.
3. Or paste it instead. The arrow next to Add Tunnel offers Add empty tunnel…, which gives you a text box — useful when the config arrived in a message rather than as a file. It pre-fills a fresh private key, so delete that line and paste your own config over the top.
4. Click Activate. The status changes to Active and the panel starts counting transferred bytes. That byte counter is the fastest sanity check you have: if it shows data going out and nothing coming back, your handshake is not completing.

Android and iPhone: scan the QR code or import the file

On a phone you have two ways in, and the QR code exists precisely because typing a 44-character key on a touchscreen is miserable.

Android

1. Install WireGuard from the Play Store and tap the + button.
2. The Create WireGuard Tunnel screen offers Scan from QR code, Import from file or archive, and creating one from scratch. Pick whichever matches what you were given.
3. Give the tunnel a name if prompted, then flip its switch. Android asks once for permission to add a VPN configuration — that prompt is the operating system's, not the app's.

iPhone and iPad

1. Install WireGuard from the App Store and tap Add a tunnel.
2. Under Add a new WireGuard tunnel, choose Create from QR code or Create from file or archive. The scanner screen is titled Scan QR code; after a successful scan it asks you to name the tunnel.
3. Toggle it on and allow the VPN configuration when iOS asks.

Making a QR code from a config file you already have

A QR code is not something the provider must give you — it is just your config file drawn as a picture, and you can produce it yourself in one command. The WireGuard app even suggests this itself:

# prints the code straight into the terminal, ready to scan off the screen
qrencode -t ansiutf8 < wg0.conf

# or write it to an image file
qrencode -o wg0.png < wg0.conf

On Debian or Ubuntu, qrencode comes from apt install qrencode; on macOS, brew install qrencode.

macOS and Linux

macOS

Install WireGuard from the Mac App Store. The Mac app is not the iPhone app on a bigger screen: it lives in the menu bar, and its window opens from Manage Tunnels. Click Import tunnel(s) from file (the menu bar has the same thing as Import Tunnel(s) from File…), pick your .conf, then select the tunnel and click Activate. There is no QR scanner on the Mac — QR codes are for phones — so use the file itself, or choose Add Empty Tunnel… and paste the config in.

If you would rather work in a terminal, brew install wireguard-tools gives you the same wg-quick commands as Linux, described next.

Linux

1. Install the tools. On Debian or Ubuntu: sudo apt install wireguard. Most distributions have a package by the same name.
2. Put the file where wg-quick looks for it. This is the step people get wrong, because the filename becomes the interface name:

   sudo install -m 600 -o root -g root wg0.conf /etc/wireguard/wg0.conf

   The 600 matters — the file contains your private key and should not be readable by other users on the machine. Keep the name short and simple; it has to be a valid network interface name.
3. Bring it up:

   sudo wg-quick up wg0
   sudo wg show

   wg show is the one command worth remembering. It prints the peer, the endpoint, a latest handshake line and transfer counters. A handshake timestamp that never appears is the signature of the problem in the next section.
4. Start it at boot: sudo systemctl enable --now wg-quick@wg0. To stop the tunnel by hand, sudo wg-quick down wg0.

On the router, so the whole house is covered

Putting the tunnel on the router covers every device behind it, including the ones that cannot run a VPN app at all — a games console, a TV, a smart speaker. Whether you can do it comes down entirely to your firmware.

If your router is the box the internet company handed you, the realistic options are to put a router you control behind it, or to keep using per-device configs. Neither is a failure; a per-device setup is often better anyway, because you can leave the tunnel off on the devices that do not need it.

One thing to decide before you route the whole house through a tunnel: everything then goes through it. Banking sites that dislike foreign addresses, streaming that checks your region, and anything talking to devices on your own network can all behave differently. This is where a narrower AllowedIPs earns its keep — send only what needs to go, and leave the rest alone.

It connects but nothing loads, and other real problems

WireGuard is unusually quiet when it fails, which is a deliberate design choice — an unauthenticated packet gets no reply at all, so a scanner cannot tell whether anything is listening. The side effect is that a wrong key, a wrong port and a blocked network all look identical from your end: silence. Work from the symptom.

"Handshake did not complete"

Your device sent an initiation packet and got nothing back. Check, in this order:

• The endpoint. Right host, right port, and the port is UDP. A typo here produces exactly this symptom and nothing else.
• UDP reaching the outside at all. Guest wifi, hotel networks, some corporate networks and a few mobile operators allow only TCP on common ports. If the same config works on your home connection and fails on one specific network, the config is fine and the network is the problem.
• The keys are the right way round. PublicKey in [Peer] is the server's public key, and the server must separately hold the public key that matches your PrivateKey. A config that was copied for a different device fails here.
• Your clock. WireGuard's handshake includes a timestamp and rejects one that is far out. Rare, but it happens on devices that have lost their time.

If the tunnel works from home but never from a mobile connection, the cause may be on your provider's side rather than yours — carrier-grade NAT and similar arrangements change what can reach you. The port forwarding guide explains how to identify that from your own router in a couple of minutes.

The MTU problem, which is worth understanding once

This is the classic "connected but the internet is broken" case, and the pattern is distinctive: ping works, DNS works, small pages work, and anything substantial stalls forever.

The cause is size. Wrapping your traffic for the tunnel adds headers, so a packet that exactly fitted your normal connection no longer fits once it is inside WireGuard. Small packets sail through; large ones are dropped. Normally the network tells the sender to use smaller packets, but the message that does this is frequently filtered, so instead of an error you simply wait.

The fix is to tell WireGuard to use smaller packets from the start. wg-quick already tries: it takes the MTU of your normal route and subtracts 80 bytes for the tunnel's overhead, so on an ordinary 1500-byte connection you get 1420. When that is still too big — some mobile networks, most connections that already run over another tunnel — set it explicitly and walk down:

[Interface]
MTU = 1420      # what wg-quick would have picked
# still stalling? try 1380, then 1280

1280 is the floor worth trying, because it is the smallest packet size IPv6 requires everything to carry, so it survives essentially any path. It costs a little efficiency and is far better than a tunnel that hangs.

The tunnel is up but nothing goes through it

Check AllowedIPs first. It is not a firewall or a permission list — it decides which destinations are routed into the tunnel at all. If it does not include 0.0.0.0/0, then traffic for the rest of the internet was never meant to go through, and your connection is behaving exactly as configured. On Linux, ip route show table all | grep wg0 shows what actually got routed.

If routing is right and names simply do not resolve, it is the DNS line — either missing, or present but not applied because resolvconf is not installed.

Where the config file comes from

Everything above assumes you have a file. There are exactly two ways to get one.

Run the server yourself

You generate a key pair, install WireGuard on a machine with a public address, add your device as a peer, and write the client config by hand. It is not difficult and it is a genuinely good thing to learn. What it costs is ongoing: a server to pay for and keep patched, and a manual edit on both ends every time you add a device — because remember, one peer is one device.

Get one from a provider

The alternative is that the file is generated for you and you download it. With HytHost VPN, from €0.99/mo, that is where it lives:

1. Order the service and sign in to the client area, then open your VPN service from the list.
2. Find the WireGuard Configuration section. It gives you two buttons — Copy to Clipboard, which puts the config text on your clipboard, and Download Configuration, which hands you the ready-made file.
3. If you copied it, paste it into a plain text editor and save it with a .conf extension — wg0.conf is a good name. Make sure your editor has not added .txt to the end.
4. Import it using the section above for your device. On a phone, turn it into a QR code first with qrencode.

The same page shows whether the tunnel is currently connected to the server, which settles the "is it me or is it them" question before you start changing settings. There is no QR code button — generate it yourself from the file, which also means the code never travels anywhere it did not need to go.