Self-hosted VPN operations

VPN server solution based on Xray VLESS + REALITY

ovpn is a Go CLI and agent system for operating self-hosted Xray servers over SSH. It keeps the public surface small, manages runtime state locally, and deploys Docker Compose services on your own hosts.

View repository Client guide Support development

SSH control plane No public admin API for normal operations.

Xray on 443 VLESS + REALITY runtime for client entry.

Local desired state Operator data lives under ~/.ovpn.

Optional monitoring Prometheus, Grafana, Alertmanager, and Telegram relay.

What it manages

The public repository focuses on the operator CLI, runtime agent, host bootstrap guidance, monitoring definitions, and release automation. Real production inventory and secrets are intentionally kept outside the repo.

Server lifecycle

Add servers, initialize hosts, deploy runtime config, check status, inspect logs, run doctor checks, and clean up old runtime safely.

User operations

Create users, generate VLESS links, mirror users across enabled servers, set expiry dates, and enforce rolling 30 day quota limits.

HA proxy topology

Add proxy entrypoints in front of existing VPN backends with split routing, local HAProxy failover, and country-specific presets.

Backups and restore

Create local and remote archives, keep automatic retention, and restore server runtime state when operational recovery is needed.

Operator workflow

Ansible prepares the host baseline and security posture. ovpn owns Xray runtime rendering, deploys the Compose stack, manages users, and exposes optional operational monitoring.

Minimal public surface

The recommended production model exposes Xray on 443/tcp and SSH on 22/tcp. Internal agent and monitoring endpoints stay private.

Security defaults

The default minimal profile blocks BitTorrent and public tracker categories and uses threat DNS resolvers unless explicitly disabled.

go build -o ovpn ./cmd/ovpn
./ovpn version

./ovpn server add \
  --name <server> \
  --host <server-ip> \
  --domain <domain> \
  --ssh-user root \
  --ssh-port 22

./ovpn server init <server>
./ovpn deploy <server>
./ovpn doctor <server>

Documentation

Start with the README for operator setup. The docs below cover client onboarding, monitoring, high availability, security, CI, testing, and upgrades.

README Operator entrypoint and quick start. Client guide End-user VLESS setup for iOS, Android, Windows, and macOS. Monitoring Prometheus, Grafana, alerts, and Telegram bot operations. HA topology Proxy role, backend pools, split routing, and failure model. Security model Threat surface, REALITY guidance, host hardening, and secrets handling. CI/CD Public workflow boundaries, release rules, and local parity checks. Testing Repository test strategy and validation commands. Upgrades Version bumps, rollback, cleanup, and operational recovery.

Support maintenance

Donations help fund bug fixes, documentation, release work, and operator tooling for the project.

Donate