vpnctl

vpnctl is a lightweight, fail-safe control plane designed for managing self-hosted VPN infrastructure on Linux. It provides a unified workspace containing a CLI, a daemon, and an administrative web UI, allowing operators to manage VPN nodes without installing agents on them. The system is built as a successor to bash-based deployment toolkits, emphasizing type-safe state, transactional inventory, and audit-on-mutation capabilities. The architecture relies on two orthogonal abstractions: Kernels (node-side daemons like sing-box, amneziawg, caddy, and xray) and Protocols (wire formats like vless+reality, hysteria2, tuic-v5, and wireguard). This plug-in design allows for easy extension; adding a new kernel or protocol involves creating a single file and registering it, without affecting the core CLI, inventory, or SSH layers. The control plane uses SSH for transport and SQLite for inventory management, ensuring data consistency and auditability. Key features include a bilingual (EN/RU) admin UI that serves as the primary operator surface, with every CLI action mirrored by a web button. The system supports complex operations such as adding servers via a wizard, managing user grants, generating subscription URLs (compatible with Mihomo and sing-box), and handling traffic accounting. It includes robust backup and recovery mechanisms, with scheduled encrypted bundles and self-test capabilities. Monitoring features provide uptime SLOs, traffic sparklines, and infrastructure alerts via Telegram. The project is currently in v0.9, with ongoing development for features like Xray/XHTTP support and fleet kernel version management.