What Is WireGuard? Config Files, QR Codes and AmneziaWG

What is WireGuard?

WireGuard is an open-source VPN protocol that creates an encrypted tunnel between two devices over UDP. It was created by Jason A. Donenfeld, was merged into the mainline Linux kernel in version 5.6 in 2020, and has official apps for Windows, macOS, Android and iOS, plus command-line tools for Linux.

The WireGuard protocol is built around minimalism. OpenVPN and IPsec support many cipher suites and modes that the two sides negotiate. WireGuard has no negotiation: every installation uses the same fixed set of modern primitives.

• Curve25519 for the key exchange between peers
• ChaCha20-Poly1305 for authenticated encryption of every packet
• BLAKE2s for hashing
• HKDF for deriving session keys
• the Noise protocol framework as the basis of the handshake

If one of these primitives is ever found to be weak, the plan is to move all endpoints to a new protocol version rather than allow fallback to an older option. Fewer settings mean fewer ways to misconfigure a tunnel and a codebase small enough to review properly. Note that WireGuard is a protocol, not a VPN service: someone still has to run a server and issue keys. For a comparison with an older design, see WireGuard vs OpenVPN.

How does a WireGuard VPN work? Keys, peers and the handshake

Key pairs instead of logins

Every WireGuard device has a private key and a matching public key, each 32 bytes and written as a 44-character base64 string ending in an equals sign. The private key stays on the device; the public key goes to the other side. There are no usernames, passwords or certificates. The wg genkey command creates a private key and wg pubkey derives its public half.

Peers and cryptokey routing

WireGuard calls each side of a tunnel a peer, and each peer entry ties a public key to a list of address ranges called AllowedIPs. Outgoing packets go to the peer whose AllowedIPs include the destination and are encrypted for that peer. An incoming packet is accepted only if it decrypts with that peer's session key and its inner source address falls within the peer's AllowedIPs. One table thus serves as both routing table and access list, which the WireGuard documentation calls cryptokey routing.

The handshake

When there is data to send and no current session, the initiating side (usually your device) sends a handshake initiation and the other side replies. That single round trip lets both sides derive fresh session keys. While traffic flows, the handshake repeats about every two minutes and old keys are discarded, which gives forward secrecy: a private key stolen later cannot decrypt traffic recorded earlier.

This design has three practical consequences:

• Silence towards unknown senders. A WireGuard server does not reply to packets that are not authenticated with a known key, so random scans get no response.
• No connection in the usual sense. With nothing to send, nothing crosses the network, so an app can show a tunnel as active while the server is unreachable; the latest handshake time is a better health check.
• Seamless roaming. After your phone moves from Wi-Fi to mobile data, the next authenticated packet tells the server your new address.

Inside a WireGuard config file

Most apps use the wg-quick format: a short INI-style text file with a .conf extension. [Interface] describes your device, and each [Peer] describes a device you connect to; a typical client config has one peer, the server. Here is what a client config contains, with placeholder values:

A few details often cause confusion:

• Address, DNS and MTU belong to wg-quick, not to the core WireGuard format, so the lower-level wg setconf command rejects them.
• Port 51820 is only a convention. A server can listen on any UDP port as long as the Endpoint matches.
• AllowedIPs decides what enters the tunnel. 0.0.0.0/0 and ::/0 send everything through the VPN; specific subnets send only those. Choosing individual apps or sites is a separate client feature, covered in our guide to split tunneling.

Handling WireGuard config files safely

• Treat a config file like a password: it contains your private key, and anyone who has it can use the tunnel as you.
• Use a separate config for each device. WireGuard identifies a peer only by its key, so two devices sharing one config keep overwriting each other's endpoint on the server and both connections become unreliable.
• Move a config as a file over a channel you trust; pasted text can pick up line breaks or altered characters.

WireGuard QR codes: scanning and generating

A WireGuard QR code is the full text of a config file encoded as an image. It does not link to a server or start a download: scanning it in a mobile app creates the same tunnel as importing the .conf file, which is handy when you set up a phone from a computer screen.

Scanning a QR code on your phone

1. Install a client for your config type: a standard WireGuard config works in the official WireGuard app, while an AmneziaWG config needs an AmneziaWG-compatible client such as Amnezia VPN.
2. Choose to add a tunnel by scanning a QR code and allow camera access if asked.
3. Hold the phone steady over the code until the app reads it.
4. If the app asks for a name, enter one you will recognize, then save the tunnel and turn it on.
5. Check the result: the latest handshake time, if the app shows it, should be recent, and an IP-check website should show the server's address.

Generating a QR code from a config

If you run your own server, the qrencode utility turns a config into a code: qrencode -t ansiutf8 < client.conf prints it in the terminal, and qrencode -o client.png < client.conf saves an image. Desktop clients import the file directly, so QR codes are mainly useful for phones and tablets.

A QR code contains your private key, just like the file. Do not share screenshots of it or paste a config into an online QR generator, which would upload your key to someone else's server. Generate the code locally, scan it once and delete the image.

AmneziaWG vs WireGuard: what changes

AmneziaWG is a protocol based on WireGuard with additional masking of service packets. It keeps WireGuard's cryptography, key format, handshake logic and peer model. What changes is the outward form of the packets that set up the tunnel: headers use configurable values instead of fixed ones, handshake packets can carry random-length padding, and the client can send junk packets of random size before the handshake.

Header and padding values must match on client and server, so AmneziaWG and standard configs are not interchangeable. The official WireGuard app rejects the extra fields, and deleting them does not help: the server still expects the modified packets, so the handshake never completes. With zero junk and padding fields and standard header values (1 to 4), AmneziaWG behaves like ordinary WireGuard. Newer releases add further optional fields on the same principle.

Data packets are encrypted exactly as in WireGuard and the extra work happens around the handshake, so everyday performance generally stays close to standard WireGuard. Flex-VPN uses AmneziaWG as its quick-start option: you import a ready key into Amnezia VPN instead of entering these parameters by hand, and the key is not meant for the standard WireGuard app. The Amnezia VPN setup guide covers each platform.

Which apps read which configs

Most import errors come from opening a valid file in the wrong app:

The last row is a common source of confusion. VLESS is a separate protocol, usually carried over TCP with TLS, so its links cannot go into a WireGuard or AmneziaWG client; see what VLESS is. Compatible apps for each platform, including the Flex VPN app for Android, are on the apps page.

Quick fixes for import problems

• Invalid key or parse error: the file was probably altered in transit. Look for a key missing its trailing equals sign or a value split across two lines.
• An unknown-field error in the WireGuard app: the config is AmneziaWG; import it into Amnezia VPN.
• Tunnel on, but nothing loads: if the handshake time does not update, your device is not reaching the server; check the Endpoint and whether your network allows outgoing UDP. If the handshake is recent, check the DNS line and try a lower MTU.

Is WireGuard a good VPN protocol for you?

For most everyday use, yes. Its strengths are a small, reviewable codebase, modern cryptography with no weak options, a one-round-trip handshake that makes connecting feel almost instant, and smooth roaming between networks. When idle, it sends nothing unless keepalive is on, which suits phones.

It also has limits worth knowing:

• UDP only. There is no TCP mode, so WireGuard cannot connect on networks that allow only TCP traffic, as some guest and corporate networks do.
• No user management. Issuing keys, assigning addresses and revoking lost devices are left to whoever runs the server.
• State on the server. While running, the server keeps each peer's tunnel address and latest public IP in memory; how long a provider retains such data is a policy matter, not a protocol one.

A sensible setup is a WireGuard-family protocol as the default and a TCP-based profile as a fallback for networks where UDP works poorly. Flex-VPN follows this pattern with AmneziaWG and VLESS + Reality profiles; AmneziaWG vs VLESS + Reality explains when to switch.