1Production (Docker Compose)

# Clone the repository
git clone https://github.com/bartei/wiregui.git
cd wiregui

# Start everything
docker compose -f compose.prod.yml up -d

The container runs migrations automatically, manages the WireGuard interface, and requiresNET_ADMIN +SYS_MODULE capabilities.

2Development

# Install dependencies
uv sync

# Start PostgreSQL & Valkey
docker compose up -d

# Run migrations and start
alembic upgrade head
uv run python -m wiregui.main

Open http://localhost:13000— an admin account is created on first run (check the logs for the generated password).

WireGUI is a Python application that shells out to ip,wg andnft. The container image adds no magic — it installs those three tools, runsalembic upgrade head, and startspython -m wiregui.main withNET_ADMIN. A bare-metal install does exactly the same thing under systemd. What you give up is the bundled PostgreSQL, Valkey and VictoriaMetrics — you provide those yourself.

Python version. WireGUI needs 3.13+. If your distro ships something older, you do not need a PPA — uv will fetch the right interpreter itself with uv python install 3.13, and uv sync will use it.

sudo -u postgres psql -c "CREATE USER wiregui WITH PASSWORD 'choose-a-real-password';"
sudo -u postgres psql -c "CREATE DATABASE wiregui OWNER wiregui;"

systemctl enable --now postgresql valkey-server

useradd --system --home /opt/wiregui --shell /usr/sbin/nologin wiregui

git clone https://github.com/bartei/wiregui.git /opt/wiregui
chown -R wiregui:wiregui /opt/wiregui

# Build the virtualenv in /opt/wiregui/.venv
cd /opt/wiregui
sudo -u wiregui uv sync --no-dev

WG_DATABASE_URL=postgresql+asyncpg://wiregui:choose-a-real-password@localhost/wiregui
WG_REDIS_URL=redis://localhost:6379/0

# openssl rand -hex 32 — rotating this invalidates sessions and
# the encrypted secrets already stored in the database
WG_SECRET_KEY=replace-with-32-random-bytes

# WireGuard
WG_WG_ENABLED=true
WG_WG_ENDPOINT_HOST=vpn.example.com
WG_WG_ENDPOINT_PORT=51820
WG_WG_IPV4_NETWORK=10.3.2.0/24
WG_WG_IPV6_NETWORK=fd00::3:2:0/120

# Web
WG_HOST=0.0.0.0
WG_PORT=13000
WG_EXTERNAL_URL=https://vpn.example.com
[email protected]

# systemd captures stderr into the journal already
WG_LOG_TO_FILE=false

# /etc/sysctl.d/99-wiregui.conf
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1

# Apply now
sysctl --system

cd /opt/wiregui
set -a; . /etc/wiregui/wiregui.env; set +a

sudo -u wiregui --preserve-env uv run alembic upgrade head

[Unit]
Description=WireGUI
After=network-online.target postgresql.service valkey-server.service
Wants=network-online.target

[Service]
Type=simple
User=wiregui
Group=wiregui
WorkingDirectory=/opt/wiregui
EnvironmentFile=/etc/wiregui/wiregui.env
ExecStart=/opt/wiregui/.venv/bin/python -m wiregui.main
Restart=on-failure
RestartSec=5

# Manage wg0 and the nftables ruleset without being root
AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMIN
NoNewPrivileges=yes

# Hardening that does not interfere with networking.
# NiceGUI keeps session storage in .nicegui/ under the working
# directory, so that tree has to stay writable.
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/opt/wiregui

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now wiregui

# The generated admin password appears here on first start
journalctl -u wiregui -f

Do not put wg0 under a host network manager. systemd-networkd, NetworkManager and dhcpcd will happily claim an interface they did not create and strip its addresses. WireGUI restores them periodically and logs a warning when it has to, but the fix is to excludewg0 from the manager.

# The interface exists and carries the tunnel addresses
ip addr show wg0

# The server key and listen port are set
wg show wg0

# WireGUI's own nftables table is present
nft list table inet wiregui

# The app answers
curl -s localhost:13000/api/health

Proxmox notes

• •Kernel WireGuard needs no /dev/net/tun passthrough. Guides that add it are configuring the userspace wireguard-goimplementation, which WireGUI does not use.
• •If the container also runs PostgreSQL and Valkey, give it at least 2 GB of RAM. WireGUI itself is small; PostgreSQL is what wants headroom.
• •Forward the WireGuard UDP port from the host or router to the container's address, and setWG_WG_ENDPOINT_HOST to whatever clients see from the internet — not the container's private IP.
• •A privileged container works too, but it buys nothing here and costs isolation.

cd /opt/wiregui
sudo -u postgres pg_dump wiregui > /var/backups/wiregui-$(date +%F).sql

systemctl stop wiregui
sudo -u wiregui git pull
sudo -u wiregui uv sync --no-dev

set -a; . /etc/wiregui/wiregui.env; set +a
sudo -u wiregui --preserve-env uv run alembic upgrade head

systemctl start wiregui

Backup

The database is the single source of truth. WireGuard interface state is fully reconciled from the database on startup.

Without this route, LAN devices can't reach VPN peers even if the policy is enabled — the router will forward WireGuard-subnet traffic to its WAN gateway where it gets dropped. The static route tells the router: "to reach the VPN subnet, forward packets to the WireGUI server."

Verification

From any LAN device, confirm the route is working:

# Should show the WireGUI server (192.168.1.100) as the next hop
traceroute 10.3.2.1

# Ping a connected peer (the peer must be online)
ping 10.3.2.2

If the traceroute shows your WAN gateway instead of the WireGUI server, the static route is missing or not applied.