ragnarok22/wireguard-api repository overview

⁠wireguard-api

VPN node based in Wireguard with a RESTful API exposed to manage peers.

⁠Deployment on AWS (Critical)

Security Groups:

• UDP 51820: Allow Inbound from 0.0.0.0/0 (WireGuard VPN protocol).
• TCP 8008: Allow Inbound from your Management IP (API access).

⁠Run with Docker Compose (Recommended)

This project uses a modern compose.yaml configuration.

1. Create a compose.yaml (or clone the repo):

   # See compose.yaml in the repo
   

   Copy

2. Run the stack:

   API_TOKEN=your_token docker compose up --build
   

   Copy

⁠Run with Docker

docker run -d \
    --name=wireguard_api \
    --cap-add=NET_ADMIN \
    --cap-add=SYS_MODULE \
    -e API_TOKEN=your_secret_token \
    -e SERVERURL=vpn.yourdomain.com \
    -p 51820:51820/udp \
    -p 8008:8008 \
    -v /lib/modules:/lib/modules \
    --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
    --sysctl="net.ipv4.ip_forward=1" \
    --restart unless-stopped \
    ghcr.io/lugodev/wireguard-api:main

Environment Variables:

• API_TOKEN: Secret token for authentication (Header X-API-Token).
• API_PORT: (Optional) Port where the API listens inside the container. Defaults to 8008.
• SERVER_PUBLIC_KEY: Public key of the server interface (used for client config generation).
• SERVER_ENDPOINT: (Optional) Full endpoint host:port for client config. Defaults to vpn.example.com:51820.
• WG_INTERFACE: (Optional) WireGuard interface to manage. Defaults to wg0.
• VPN_PORT: (Optional) Port where WireGuard listens. Defaults to 51820.

⁠Usage

The API is RESTful and served on port 8008. Authentication is done via the X-API-Token header.

⁠List Peers

curl -X GET http://localhost:8008/peers \
  -H "X-API-Token: your_secret_token"

⁠Create Peer

curl -X POST http://localhost:8008/peers \
  -H "X-API-Token: your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"allowed_ips": ["10.13.13.2/32"]}'

If public_key is omitted, one will be generated. If allowed_ips is omitted, the next available IP in the subnet will be automatically allocated.

⁠Create Peer (One-Liner Config)

To generate a ready-to-use WireGuard configuration file directly:

curl -X POST "http://localhost:8008/peers?format=config" \
  -H "X-API-Token: your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{}' > client.conf

⁠Get Peer Details

curl -X GET http://localhost:8008/peers/<PUBLIC_KEY> \
  -H "X-API-Token: your_secret_token"

⁠Get Peer Config

Returns a partial config block for the client.

curl -X GET http://localhost:8008/peers/<PUBLIC_KEY>/config \
  -H "X-API-Token: your_secret_token"

⁠Delete Peer

curl -X DELETE http://localhost:8008/peers/<PUBLIC_KEY> \
  -H "X-API-Token: your_secret_token"

⁠Development

This project uses uv⁠ for dependency management and Python 3.13.

⁠Prerequisites

• Python 3.13+
• uv installed
• make

⁠Commands

make install       # Sync dependencies
make run           # Run dev server (uvicorn)
make lint          # Run ruff check
make format        # Run ruff format

⁠Contributors ✨

Thanks goes to these wonderful people (emoji key⁠):

Reinier Hernández⁠

Carlos Lugones⁠

This project follows the all-contributors⁠ specification. Contributions of any kind welcome!