Skip to main content

WGKeeper

WGKeeper is an open-source control plane for WireGuard® — a web Console plus a per-server Node service that replace hand-edited wg0.conf files with API-driven peer management across many servers.

How it works​

WGKeeper is split into two services:

  • Console — central control plane with a web UI and database. Holds the inventory of nodes and peers, and is the only component an operator interacts with directly.
  • Node — runs on each WireGuard server, owns the local wg interface, and exposes a REST API the Console talks to.
       ┌─────────────────────┐
       │      Operator       │
       └──────────┬──────────┘
                  │  HTTPS (Web UI)
       ┌──────────▼──────────┐
       │       Console       │  inventory, auth, audit
       └──────────┬──────────┘
                  │  REST API (HTTP/HTTPS + API key)
        ┌─────────┼──────────┐
        ▼         ▼          ▼
     ┌─────┐  ┌─────┐    ┌─────┐
     │Node │  │Node │ …  │Node │   wg interface, peers
     └─────┘  └─────┘    └─────┘

A single Console manages many Nodes. The Console is the source of truth; Nodes are stateless by default and can optionally persist their own peer store on disk for recovery if the Console is unreachable.

Core concepts​

  • Node — a server running the WGKeeper Node service and a WireGuard interface. Identified in the Console by a name, API endpoint, and API key.
  • Peer — a WireGuard client (laptop, phone, server) allocated an address on a Node and authorized to connect.
  • Config — the wg-quick-compatible client configuration generated by the Console for a peer. Distributed to the end user out of band.
  • Capacity — how many peer addresses remain free in a Node's address pool.

What you can do with it​

  • Track node health, version, and peer capacity from one screen.
  • Create peers, generate client configs, and verify handshakes after clients connect.
  • Roll out node upgrades without losing peer state.
  • Scrape per-node Prometheus metrics into the bundled Grafana dashboard.

What WGKeeper is not​

  • Not a hosted SaaS — you self-host the Console and Nodes.
  • Not a replacement for the WireGuard kernel module or wireguard-tools. The Node uses them under the hood.
  • Not a VPN client. End users connect with the standard WireGuard client of their choice using the config the Console generates.

Where to go next​

Pick the path that matches what you're doing right now:

You want to…Start here
Try it end-to-end on one hostQuick start
Stand up a production ConsoleConsole installation
Add a Node to an existing ConsoleNode installation
Look up a Node settingNode configuration
Wire up Prometheus and GrafanaMetrics
Day-to-day peer operationsUsing the Console

WGKeeper is licensed under AGPL-3.0. WireGuard® is a registered trademark of Jason A. Donenfeld.