blinklabs/wireguard repository overview

⁠docker-wireguard

WireGuard VPN container with JWT-authenticated peer management API for the NABU VPN service.

⁠Overview

This container provides a WireGuard VPN server with a REST API for dynamic peer management. The API accepts JWT-authenticated requests from the vpn-indexer to add and remove WireGuard peers on-the-fly.

⁠Quick Start

docker run -d \
  --name wireguard \
  --cap-add=NET_ADMIN \
  -e WG_ENDPOINT=vpn.example.com:51820 \
  -e WG_PRIVATE_KEY=$(wg genkey) \
  -v /path/to/jwt-verify.pub:/etc/wireguard/jwt-verify.pub:ro \
  -p 51820:51820/udp \
  -p 8080:8080 \
  ghcr.io/blinklabs-io/docker-wireguard:latest

⁠Environment Variables

⁠API Endpoints

⁠Health Check

GET /health

Returns the health status of the API.

Response:

{"status": "healthy"}

⁠Server Info

GET /info

Returns the server's public key and endpoint.

Response:

{
  "server_pubkey": "base64_encoded_public_key",
  "endpoint": "vpn.example.com:51820"
}

⁠Add Peer

POST /peer
Content-Type: application/json

{
  "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "pubkey": "client_wireguard_public_key"
}

Adds a WireGuard peer. Requires a valid JWT token.

Response:

{
  "success": true,
  "server_pubkey": "base64_encoded_public_key",
  "endpoint": "vpn.example.com:51820",
  "allowed_ips": "0.0.0.0/0"
}

⁠Remove Peer

DELETE /peer
Content-Type: application/json

{
  "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "pubkey": "client_wireguard_public_key"
}

Removes a WireGuard peer. Requires a valid JWT token.

Response:

{"success": true}

⁠Prometheus Metrics

GET /metrics

Returns Prometheus-formatted metrics for monitoring.

Available Metrics:

• wg_peers_added_total - Total number of WireGuard peers added
• wg_peers_removed_total - Total number of WireGuard peers removed
• wg_active_peers - Current number of active WireGuard peers
• wg_peer_operation_errors_total - Peer operation errors by type (add/remove)
• wg_api_requests_total - API requests by endpoint, method, and status code
• wg_api_request_duration_seconds - API request duration histogram
• wg_jwt_validation_errors_total - JWT validation errors

⁠JWT Requirements

JWTs must be:

• Signed with Ed25519 (EdDSA algorithm)
• Have sub claim set to wg_peer
• Include pubkey claim matching the request pubkey
• Include allowed_ip claim with the client's assigned IP
• Have exp (expiration) claim set (recommended: 60 seconds from issuance)

Example JWT Claims:

{
  "sub": "wg_peer",
  "pubkey": "client_wireguard_public_key",
  "allowed_ip": "10.8.0.42",
  "exp": 1705123516,
  "iat": 1705123456
}

⁠Security

• Container requires NET_ADMIN capability for WireGuard kernel operations
• Private keys should be stored in secrets, never logged
• Default firewall policy is DROP; only forwarded traffic from wg0 is allowed
• API mutations require valid, non-expired JWT
• Network policies should restrict API access to trusted services only

⁠Building

# Build Docker image
docker build -t wireguard:latest .

# Build Go binary locally
go build -o wg-peer-api ./cmd/wg-peer-api

# Run tests
go test ./...

⁠Kubernetes Deployment

See the vpn-infrastructure⁠ repository for Helm charts and deployment configurations.

⁠License

Copyright 2026 Blink Labs Software

Licensed under the Apache License, Version 2.0. See LICENSE⁠ for details.