wg-easy runs a WireGuard VPN server with a simple web page for adding devices and showing their QR codes. It's separate from LibrePortal's own VPN, for when you want a VPN for other reasons.
On this page
Good to know before you install
This is a separate VPN from LibrePortal's built-in private network and is not used for LibrePortal's own access control. Its admin panel accepts logins over plain HTTP, so reach it only over your LAN or a VPN, or behind HTTPS.
At a glance#
- What it is
- Standalone VPN Server Networking
- Where it opens
- Admin Panel
On its own port at
http://your-server:port, orwireguard.your-domainonce you have a domain - Updates
- When you choose New versions wait for you to press Update
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- One per server
What it's good for#
Most people don't need this app. LibrePortal already has a built-in VPN for reaching your apps from outside, and that's the one LibrePortal trusts: its devices count as trusted places, and it decides which apps each device can open. Devices on wg-easy don't count as trusted places, however they connect.
wg-easy is for the other jobs a VPN does. Giving the whole family a way to route their phone's traffic through home when they're on café Wi-Fi, for instance, or giving friends access to your network without giving them anything in LibrePortal. It's a plain WireGuard server with a friendly admin page, and you manage its devices there rather than in LibrePortal.
That's also why it only appears in the App Center when the WebUI is in Advanced mode.
Signing in#
Open it with the Admin Panel button. The username is admin, and the password is in the Login Details shown when the install finishes; press Welcome on the app's page to see it again. LibrePortal hands both to wg-easy for its very first start, so its setup wizard never appears and there's no moment when someone else could claim it.
The admin panel starts private, so only your trusted places and LibrePortal VPN devices can open it. Leave it that way: whoever gets into it can add themselves a device.
To change the password, use Reset Admin Password on the Tools tab, which keeps LibrePortal's copy in step. Leave the box empty to have a strong one made for you.
Adding a device#
- Install the WireGuard app on the phone or computer, from its app store or wireguard.com.
- Add a client in wg-easy. Give it a name you'll recognise, like
anna-phone. - Give the device its config. On a phone, add a tunnel in the WireGuard app and scan the QR code wg-easy shows. On a computer, download the config file from wg-easy and import it into the WireGuard app.
- Turn the tunnel on.
Android: 15 characters at most
The WireGuard app on Android refuses a tunnel whose name is longer than 15 characters, and when you import a file it takes the name from the file name. Keep client names short (anna-phone, not annas-new-phone-2026), or rename the tunnel as you import it.
List VPN Clients on the Tools tab lists every device wg-easy knows, with whether it's enabled, which is handy for checking without opening the admin panel. To switch a device off or remove it, use wg-easy's own page.
Making it reachable from outside#
Devices connect to the VPN on UDP port 51820, which is public. LibrePortal writes your server's address into each device's config when wg-easy is first installed: its public internet address when it knows one, or its home network address if not.
- On a VPS, that just works.
- At home behind a router, forward UDP port 51820 on your router to your server. If your home internet address changes now and then, a dynamic DNS name is better than the bare address: change the Host in wg-easy's admin panel, then give each device a fresh config.
It won't clash with LibrePortal's VPN
LibrePortal's built-in VPN uses a different port (51830) and a different address range (10.87.0.x), and wg-easy uses 51820 and 10.8.0.x. The install stops if the two would share a port, warns you if they'd share an address range, and also refuses to go ahead if there's already a WireGuard server installed directly on the machine.
Good to know#
- wg-easy owns its settings after the first start. The address, port and address range are only read from LibrePortal the first time. After that, change them in wg-easy's admin panel; changing LibrePortal's copy does nothing.
- Updates wait for you. wg-easy is pinned to an exact version (15.4.0), because a VPN you rely on to get home isn't something to change while you're away. Update only brings rebuilds of that version; the Updates tab may offer a newer one, but Upgrade can't move wg-easy to it yet.
- Backups include it, with every device's keys. Treat the backup as you would the VPN itself.
- Uninstalling removes the network forwarding setting the install switched on for it.
- Metrics. With Prometheus and Grafana installed, Export metrics to Grafana in its settings adds a Grafana dashboard of connected devices and traffic.
Addresses and ports#
wg-easy has 3 ports. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one. "Anyone" means it's reachable from wherever your server is reachable; you can make it private later.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Admin Panel | Trusted places only | wireguard.your-domain |
| VPN Server (devices connect here) UDP | Anyone | Port only |
| Metrics Exporter (shares wireguard-service netns) TCP | Off until you turn it on | Port only |
Settings#
In its config file#
wg-easy's own settings aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
NameCFG_WIREGUARD_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_WIREGUARD_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
false |
Tools#
wg-easy's Tools tab has 2 buttons for jobs you'd otherwise need a terminal for. Each one runs as a task, so you can watch it on the Tasks page and read what it did. More about Tools.
Set a new password for the wg-easy admin account. Leave blank to generate one.
Show every device (client) wg-easy knows, with its public key and whether it is enabled.
Works with#
These are the other apps wg-easy knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
All clear The VPN manager does not report on you, and LibrePortal has turned off its update check. Its login runs over plain HTTP, so reach it only over your LAN or a VPN.
What leaves this server#
Nothing leaves this server on its own.
What LibrePortal turns off#
- Update check against GitHub
Licence: AGPL-3.0. Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs this image:
ghcr.io/wg-easy/wg-easy:15.4.0@sha256:0e7bc9d34e86ddcaa92bc700d4d7dc9b33291dbc07ac8d13382f7c2095f949ec. The version is pinned, and moves only when you update it. - It only shows in the App Center when the WebUI is in Advanced mode.
- It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: github.com/wg-easy/wg-easy
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.