Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AZhur771/pivpn-web/llms.txt

Use this file to discover all available pages before exploring further.

PiVPN Web is a self-hosted, open-source web dashboard that puts a clean browser UI in front of your PiVPN WireGuard installation. Instead of managing VPN clients over SSH from the command line, you get a point-and-click interface for every common task — creating users, toggling connections, scanning QR codes, and downloading .conf files — all running as a single Docker container that you deploy once and forget.
PiVPN Web supports WireGuard only. OpenVPN installations are not compatible. When installing PiVPN, make sure to select WireGuard as the VPN protocol.

​
Key features

Client management

List, create, delete, enable, and disable WireGuard clients directly from the dashboard — no command-line access required.

QR code provisioning

Display a scannable QR code for any client so mobile devices can import their configuration in seconds.

Live connection status

See which clients are currently connected and monitor their real-time traffic statistics.

Config file downloads

Download a ready-to-use .conf file for any client directly from the browser.

Session-based authentication

Secure, cookie-based sessions backed by SQLite. Role-based access lets you grant read-only or full-admin privileges per account.

SSH connectivity

Connects to your PiVPN host over SSH — works with a local installation on the same machine or a remote Raspberry Pi anywhere on your network.

Docker-native deployment

Ships as a single Docker image (andrew771/pivpn-web). One docker run command is all it takes to go from zero to a running dashboard.

Persistent SQLite store

User accounts, sessions, and banned-client records are stored in an embedded SQLite database managed by TypeORM — no external database needed.

​
Architecture overview

PiVPN Web is composed of three main layers that work together to bridge your browser and your PiVPN host. Express.js backend The server is written in TypeScript and runs under ts-node inside the Docker container. It exposes a REST API under /api/ that the frontend consumes. All WireGuard operations (listing clients, creating/deleting peers, retrieving configs and QR codes) are executed by the backend by shelling out commands over an SSH connection. SSH tunnel to the PiVPN host The backend uses the node-ssh library to open an authenticated SSH session to the target host using the credentials you supply via environment variables (SSH_HOST, SSH_PORT, SSH_USER, SSH_PASSWORD). Every WireGuard command (pivpn add, pivpn remove, pivpn list, etc.) is executed remotely over that tunnel. The connection is lazily established on the first request and reused for subsequent calls. SQLite / TypeORM persistence layer An embedded SQLite database, managed through TypeORM, stores three types of data:
  • Sessions — express-session records persisted via typeorm-store so users stay logged in across server processes (when a stable SECRET is provided).
  • Users — hashed credentials and the admin flag for every account. User records are seeded by TypeORM migrations that run automatically at startup, reading the ADMIN_USER, ADMIN_PASSWORD, VIEWER_USER, VIEWER_PASSWORD, TECH_USER, and TECH_PASSWORD environment variables.
  • Banned clients — records of WireGuard peers that have been flagged, including the ban expiry and total downloaded bytes.
Vue.js frontend The compiled Vue.js single-page application is served as static files from the www/ directory by the same Express process. There is no separate frontend server — the build artefacts are baked into the Docker image at build time. 
Browser
  │  HTTP / REST (port 3001)
  ▼
Express.js (Docker container)
  │  TypeORM + SQLite (sessions, users, banned clients)
  │
  │  SSH (node-ssh)
  ▼
PiVPN WireGuard host
  │  pivpn CLI commands
  ▼
WireGuard kernel module

​
Requirements

Before deploying PiVPN Web, make sure the following are in place:
  • Docker installed on the machine that will run the container.
  • PiVPN with WireGuard installed on the target host (local machine or remote server). OpenVPN installations are not supported.
  • SSH access enabled on the PiVPN host with a username and password that PiVPN Web can use to authenticate.

​
Next steps

Ready to deploy? Head to the Quickstart guide to have PiVPN Web running in under five minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us