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 does not need to run on the same machine as PiVPN. The application connects to the PiVPN host using node-ssh and executes pivpn and wg commands over the SSH session. This means you can host the web UI on any Docker-capable machine — a home server, a cloud VM, or your workstation — while the WireGuard installation lives on a separate Raspberry Pi or Linux server.

​
How the SSH connection works

When PiVPN Web receives a request that requires WireGuard data (for example, listing clients or downloading a config file), it checks whether an SSH connection is already open. If not, it establishes one using the credentials supplied via environment variables. The connection is kept alive and reused for subsequent commands, and it reconnects automatically the next time a command is needed after a disconnection. The SSH class (lib/SSH.ts) validates that all four required variables are present at startup and throws an error immediately if any are missing, so misconfigured deployments fail fast rather than silently.

​
Requirements

  • SSH is enabled on the PiVPN host (sudo systemctl enable --now ssh).
  • The SSH user has permission to run pivpn and wg commands (typically via sudo).
  • The Docker host running PiVPN Web has network connectivity to the PiVPN host on the SSH port (default 22).

​
Environment variables

VariableDefaultDescription
SSH_HOST(required)IP address or hostname of the PiVPN host.
SSH_PORT22SSH port on the PiVPN host.
SSH_USER(required)Username used to open the SSH session.
SSH_PASSWORD(required)Password for the SSH user.

​
Quick start with docker run

docker run -d \
  -p 3001:3001 \
  --name pivpn-web \
  --restart=unless-stopped \
  -e SSH_HOST=192.168.1.100 \
  -e SSH_PORT=22 \
  -e SSH_USER=pi \
  -e SSH_PASSWORD=raspberry \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=yourpassword \
  andrew771/pivpn-web
After the container starts, open http://<docker-host>:3001 in your browser and log in with the ADMIN_USER and ADMIN_PASSWORD credentials you provided.
PiVPN Web uses password-based SSH authentication. Exposing the dashboard on a public IP with weak credentials is a security risk — anyone who can log in to the web UI can enable, disable, and download WireGuard client configurations. Use a strong, unique ADMIN_PASSWORD, restrict dashboard access to your internal network or a VPN, and consider placing the UI behind a reverse proxy with TLS.

​
Troubleshooting

PiVPN Web logs an error and the dashboard shows no client data.Things to check:
  • Verify SSH_HOST is the correct IP address or hostname of the PiVPN machine.
  • Confirm the PiVPN host is reachable from the Docker host: ping <SSH_HOST>.
  • Check that a firewall on the PiVPN host is not blocking the SSH port: sudo ufw status or sudo iptables -L.
  • Confirm the SSH service is running on the PiVPN host: sudo systemctl status ssh.
The SSH session connects successfully but pivpn or wg commands fail with a permission error.Things to check:
  • The SSH_USER account must be able to run pivpn and sudo wg without a password prompt. Add a sudoers entry if needed: 
    echo "pi ALL=(ALL) NOPASSWD: /usr/bin/wg, /usr/local/bin/pivpn" | sudo tee /etc/sudoers.d/pivpn-web
  • Verify the user is a member of any required groups on the PiVPN host.
The container exits immediately with Error: connect ECONNREFUSED.Things to check:
  • Confirm the SSH daemon is listening on port 22: sudo ss -tlnp | grep :22.
  • If the PiVPN host uses a non-standard SSH port, set SSH_PORT to match. For example, if SSH listens on port 2222, add -e SSH_PORT=2222 to your docker run command.
  • Make sure no firewall rule is blocking connections to the SSH port from the Docker host’s IP.

Build docs developers (and LLMs) love

Get started for freeTalk to us