wg-easy
WireGuard server with a web UI for adding clients and scanning QR codes
wg-easy runs a WireGuard interface in a container and gives you a web page for creating peers, showing their QR codes and watching transfer counters. It replaces hand-editing wg0.conf and mailing config files around.
Our verdict on wg-easy#
wg-easy is a WireGuard config generator with a QR code, which is the right amount of software for a single-admin road-warrior VPN. Treat v15 as a different product from v14, because it is: a full rewrite with, in the maintainer's words, no migration path at all. You export from v14, stand up a fresh v15 and import during the setup wizard. Nearly every environment variable is gone, configuration moved into SQLite behind that wizard, /lib/modules:ro is now a required mount, and the licence changed from CC BY-NC-SA 4.0 to AGPL-3.0-only, which matters if you were depending on the old non-commercial terms one way or the other. The latest Docker tag still points at v14, so pin :15. The UI refuses plain HTTP unless you set INSECURE=true, which pushes you toward a reverse proxy. Ports did not change: 51820/udp for WireGuard, 51821/tcp for the interface. Current line is 15.4.0, August 2026.
Who wg-easy is for#
Choose it if
- One person who needs their phone and laptop back onto the home LAN, and wants to hand a QR code to a family member without explaining public keys
- A VPS or home server where you control the firewall and can forward a single UDP port
- Anyone who wants full-tunnel or split-tunnel WireGuard without the mesh coordination machinery of Tailscale or Headscale
- Setups already fronted by Caddy or Traefik, since the documented happy path is a reverse proxy in front of 51821
Look elsewhere if
- Your clients are behind CGNAT on both ends and you need NAT traversal, which is a mesh VPN problem, not a WireGuard-server problem
- You are on armv6 or armv7 hardware, since those builds were dropped in 15.0 and 15.2
- You want per-user self-service; every peer is created by the admin in the UI
What running it actually looks like#
One container with NET_ADMIN and SYS_MODULE, the sysctls net.ipv4.ip_forward=1 and net.ipv4.conf.all.src_valid_mark=1, a volume at /etc/wireguard, and a read-only bind of /lib/modules that v15 requires so it can load the kernel module. The shipped compose file puts the container on a dedicated dual-stack bridge with fixed v4 and v6 addresses and adds the IPv6 forwarding sysctls. Publish 51820/udp and 51821/tcp. Nothing needs to exist first: on first boot you open the UI and a setup wizard asks for the hostname clients will dial, an admin username and password, and optionally TOTP. For unattended provisioning set INIT_HOST, INIT_PORT, INIT_USERNAME and INIT_PASSWORD before that first boot. Only x86_64 and arm64 images are published. Dockerless installation was deprecated in v15.
Resource profile#
- Memory
- 90 MB idle, around 160 MB in ordinary use. The WireGuard data path is in the kernel and costs nothing; the number is the Nuxt/Node process serving the UI and API.
- CPU and acceleration
- Encryption happens in the kernel module, so throughput is close to line rate on anything modern. The container itself only burns CPU when the UI polls peer status.
- Storage growth
- Under a megabyte. The SQLite database holds peer keys and settings; nothing accumulates over time.
- Operational load
- 2 of 5, Light. Single container that mostly sits there, but it needs privileged capabilities and host sysctls, and the v14 to v15 jump was a hard cutover with no migration path. Peer key material makes restores security-sensitive rather than routine.
Figures describe a small single-household install and are the working assumptions behind our stack planner. Your numbers will differ with library size, user count and hardware. See methodology.
Data and backup surface#
Back up the /etc/wireguard volume. In v15 it holds the SQLite database with your admin account, every client, every private key and the interface settings, plus the generated wg0.conf. Those keys are the entire security boundary, so encrypt the backup and keep it off the machine that is exposed to the internet. Stop the container or use SQLite's .backup before copying, since a live copy of an open WAL database can restore torn. Size is trivial: a 30-peer setup is well under a megabyte. Client configs and QR codes are rendered from the database on demand, so there is nothing separate to export, but the reverse is also true: lose the database and every peer has to be recreated and re-enrolled by hand.
Derived backup shape
SQLite backup. sqlite3 <db> ".backup out.db" while running, or stop the container and copy. A live cp of a WAL-mode SQLite file can restore corrupt.
Traps and surprises#
There is no v14 to v15 upgrade, at all
The maintainer's answer to "what is the migration path" was "there is and will be none". Pulling the :15 tag over a v14 volume does not migrate your peers. The supported route is: export the configuration from v14, deploy v15 into a clean volume, and import during the initial setup wizard. Import is not available after setup completes, so if you click past it you start over.
The `latest` tag is still v14
ghcr.io/wg-easy/wg-easy:latest points at the v14 release and the docs tell you to avoid it. Anyone who copied a compose file from a blog post in the last few years is running v14 without knowing it, on the old CC BY-NC-SA licence and without the v15 security work. Pin the major (:15), which the project recommends, so you get patches without a rewrite landing on you unannounced.
Plain HTTP is refused unless you opt in
v15 will not serve the admin interface over an unencrypted connection unless INSECURE=true is set in the environment. The documented default assumes a reverse proxy terminating TLS in front of 51821. If you hit the port directly and get nothing useful, this is why. The docs label the INSECURE path as not recommended and tell you to keep the UI off any network you do not control.
Licence changed to AGPL-3.0-only in v15
Through v14 the project was CC BY-NC-SA 4.0, a non-OSI, non-commercial-use licence that made it awkward inside a business. v15 relicensed to AGPL-3.0-only. Commercial internal use is now unambiguously fine, but the network copyleft clause applies if you modify it and offer it as a service. Either way, the terms you evaluated in 2024 are not the terms you get today.
32-bit ARM images are gone
armv6 was dropped in 15.0 and armv7 in 15.2.0; only x86_64 and arm64 are built. A Raspberry Pi 3 or Zero running a 32-bit OS cannot pull v15 at all, and there is no v14 fallback that shares a config format. The practical fix is reinstalling a 64-bit OS on the same board, which for a Pi 3 means Pi OS 64-bit, or moving the VPN endpoint to a different host.
Specifications#
- Category
- Networking, DNS and remote access
- Licence
- AGPL-3.0-only (Copyleft)
- Written in
- TypeScript / Node.js (Nuxt)
- First release
- 2021
- Maturity
- Stable
- Datastore
- SQLite since v15; v14 and earlier used a JSON file
- Default ports
51820,51821- Ships as
- docker, podman
- arm64 builds
- Yes
- Identity
- Native OIDC. Local admin accounts with optional TOTP by default; OAuth/OIDC external authentication landed in 15.4.0 (August 2026).
- Replaces
- OpenVPN Access Server, Tailscale, NordVPN Meshnet
- Project site
- wg-easy.github.io/wg-easy/latest
- Source
- github.com/wg-easy/wg-easy
- Documentation
- wg-easy.github.io/wg-easy/latest/getting-started
Alternatives to wg-easy#
Everything else in networking, dns and remote access, closest in operational weight first.
| Tool | Ops load | Idle RAM | Licence |
|---|---|---|---|
| AdGuard Home | 2, Light | 60 MB | GPL-3.0 |
| Nginx Proxy Manager | 2, Light | 100 MB | MIT |
| Pi-hole | 2, Light | 100 MB | EUPL-1.2 |
| Caddy | 1, Set and forget | 25 MB | Apache-2.0 |
| Headscale | 3, Moderate | 40 MB | BSD-3-Clause |
| Technitium DNS Server | 3, Moderate | 130 MB | GPL-3.0 |
Where wg-easy comes up elsewhere#
Reference
Sources#
Facts on this page were checked against the project's own material. Where a number is our own estimate rather than a published figure, the text says so.
Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.