Project Pegaprox

PegaProx

Modern Multi-Cluster Management for Proxmox VE & XCP-ng

Website • Documentation • Releases • Plugins • Sponsoring • Commercial Support

#🚀 What is PegaProx?

PegaProx is a powerful web-based management interface for Proxmox VE and XCP-ng clusters. Manage multiple clusters from a single dashboard with features like live monitoring, VM management, automated tasks, and more.

#🪽 What's in the name?

The name PegaProx is inspired by Pegasus, the winged horse of Greek mythology, combined with Prox as a reference to Proxmox VE. Pegasus symbolises speed, freedom and elegant flight - qualities we aspire to bring to multi-cluster hypervisor management.

#❤️ Sponsors

PegaProx is a community-driven open source project that lives entirely from sponsorships and donations. Server costs, domains, code-signing certificates and the developer hours behind every release come straight out of our own pockets — and out of the contributions of the wonderful companies and individuals below. If PegaProx saves you time at work, please consider becoming a sponsor or chipping in on Open Collective. Every euro keeps the lights on. 💛

#💎 Platinum

#🥇 Gold

#🥈 Silver

#🥉 Bronze

_{Individual supporters:  Andreas Huemmer}

Become a Sponsor • Open Collective • Commercial Support

#✨ Features

#Multi-Cluster Management

• 🖥️ Unified Dashboard - Manage all your Proxmox clusters from one place
• 📊 Live Metrics - Real-time CPU, RAM, and storage monitoring via SSE
• 🔄 Live Migration - Migrate VMs between nodes with one click
• ⚖️ Cross-Cluster Load Balancing - Distribute workloads across clusters
• 🛣️ Transfer Network - A dedicated network per cluster for the disk data of cross-cluster migrations, replications and Site Recovery runs, off the management network (docs)
• 🔄 Cross-Hypervisor Migration - Migrate VMs between ESXi, Proxmox VE, and XCP-ng

#VM & Container Management

• ▶️ Quick Actions - Start, stop, restart VMs and containers
• ⚙️ VM Configuration - Edit CPU, RAM, disks, network, EFI, Secure Boot & more
• 📸 Snapshots - Standard and space-efficient LVM snapshots for shared storage
• 🔁 Snapshot Replication - Storage-agnostic replication for clusters without ZFS
• 💾 Backups - Schedule and manage backups
• ✅ Backup Verification (Experimental) - Automated restore → boot → health check → cleanup (ISO 27001, SOC 2, HIPAA compliance)
• 🖱️ noVNC / xterm.js Console - Browser-based console for QEMU and LXC
• ⚖️ Load Balancing - Automatic VM distribution across nodes
• 🔁 High Availability - Restart the guests of a failed node elsewhere, with fencing, a self-fence agent and only guests whose volumes are on shared storage
• 📍 Affinity Rules - Keep VMs together or apart on hosts (QEMU + LXC)

#XCP-ng Integration (Tech Preview)

• 🟢 XCP-ng Pool Support - Connect XCP-ng / Xen hypervisor pools alongside Proxmox clusters
• ▶️ VM Power Actions - Start, stop, shutdown, reboot, suspend/resume
• 🖥️ VNC Console - Browser-based remote console via XAPI
• 💽 Disk & Network Management - Add, resize, remove disks and NICs
• 🔧 Maintenance Mode - Enter/exit with automatic VM evacuation

#ESXi Migration

• 🔀 ESXi Import Wizard - Migrate VMs from ESXi hosts to Proxmox
• ⚡ Near-Zero Downtime - Transfer running VMs with minimal interruption (max. 1 VM recommended)
• 🔌 Offline Migration - Shut down and transfer for maximum reliability
• 🔑 SSH Required - ESXi host must have SSH enabled

#Security & Access Control

• 👥 Multi-User Support - Role-based access control (Admin, Operator, Viewer) + custom roles
• 🛠️ API Token Management - Create, list, and revoke Bearer tokens (scoped per role)
• 🔐 2FA Authentication - TOTP-based two-factor authentication (with force option)
• 🔑 WebAuthn / FIDO2 - Hardware-key login (YubiKey, Nitrokey, Touch ID, Windows Hello) - passwordless or as 2FA factor
• 🏛️ LDAP / OIDC - Active Directory, OpenLDAP, Entra ID, Keycloak, Google Workspace, Authentik (with PKCE)
• 🛡️ VM-Level ACLs - Fine-grained permissions per VM
• 🏢 Multi-Tenancy - Isolate clusters for different customers
• 🚫 IP Whitelisting / Blacklisting - Restrict access by IP or CIDR range
• 🔒 Full-DB Encryption - SQLCipher (AES-256-CBC + HMAC-SHA512, format v4) wraps the entire database at rest on Linux x86_64; sensitive fields stay individually Fernet-encrypted everywhere else. Multi-tier master-key loader resolves from env / systemd LoadCredentialEncrypted / /etc/pegaprox/secret.key, so a config/ backup never carries the key alongside the data. Auto-migrates plain DBs on first boot post-update.
• 🔍 CVE Scanner - Per-node package vulnerability scanning via debsecan
• 🛡️ CIS Hardening - One-click security audit and hardening against CIS benchmarks
• 🧾 HMAC-Signed Audit Log - Tamper-evident integrity verification on every entry

#Automation & Monitoring

• ⏰ Scheduled Tasks - Automate VM actions (start, stop, snapshot, backup)
• 📸 Snapshot Schedules - Tag-based or VMID-list snapshot policies with retention pruning (hourly / daily / weekly + “keep last N” + “keep N days”)
• 🔄 Rolling Node Updates - Update cluster nodes one by one with automatic evacuation
• 🚨 Alerts - Get notified on high CPU, memory, or disk usage
• 📜 Audit Logging - Track all user actions with IP addresses
• 🔎 Audit Search - Full-text + date-range + severity + IP filter, paginated, CSV export
• 🛰️ SIEM Forwarder - Stream audit events to Syslog (UDP/TCP RFC 5424), Splunk HEC, Elasticsearch, Loki, or generic webhooks. VAPID-style per-target TLS verification.
• 🔧 Custom Scripts - Run scripts across nodes
• 💿 Ceph Management - Monitor and manage Ceph storage pools, RBD mirroring
• 🔐 ACME / Let's Encrypt - Automatic SSL certificate renewal with HTTP-01 challenge (+ custom ACME CAs)
• 📋 Integrated Syslog Server - Receive and view syslog messages (UDP/TCP) with filtering, search, and severity-based coloring
• 🧬 Config Drift Detection - Nightly snapshot of cluster config (VM configs, storage.cfg, network, datacenter options) - alerts on any unauthorized change vs the admin-set baseline. Pairs with the Compliance Dashboard.

#Reports & Analytics

• 💰 Cost Dashboard / Chargeback - €/VM/Month from real metrics (CPU-h × node tariff + RAM-GB-h + Storage-GB-month). Currency-configurable, per-cluster rates, top-spender table, by-node breakdown. CSV + PDF export.
• ⚡ Power & Carbon Tracking - Estimated kWh + €/Month + kg CO₂/Month per VM, based on metrics history × node-power profile × PUE × grid CO₂ intensity. Defaults for DE/EU; admin-tunable for any hardware/grid. CSV + PDF export.
• 🧠 Insights - Right-sizing recommendations (oversized / undersized CPU + RAM, idle VMs) and capacity forecasts (linear regression + ETA to threshold) over 30 days of history. PDF export.
• 🌐 Network Topology Visualization - Interactive SVG graph: Cluster → Nodes → Bridges/Bonds/SDN VNets → VMs. Click to highlight connections.
• 📊 Compliance Dashboard - Read-only BSI Grundschutz / ISO 27001 / NIS2 / SOC 2 mapping per cluster, hardening score, exportable PDF. Visible to ops/auditors without admin rights.
• 🛡️ CVE Reporting - Per-cluster severity counts + per-package detail + historical view of when each CVE first appeared.

#Operations & Deployment

• ☁️ Cloud-Init Template Library - Curated catalog of the supported Ubuntu LTS, Debian, AlmaLinux, Rocky Linux, Fedora and Alpine cloud images (a weekly CI job checks every image URL and flags releases past their end of life) plus admin-defined custom templates. One-click deploy to any cluster (download → import → cloudinit drive → convert to template).
• 🚑 Site Recovery - Configure DR plans (boot order, dependencies, replication mappings) and execute controlled failover with audit trail.
• 📦 Backup SLA Tracking - SLA dashboard per cluster + datastore: last-backup age vs configured RPO, integrated with the Alert pipeline.
• 🔁 ZFS / Cross-Cluster Replication - Native PVE replication monitor + cross-cluster replication for clusters without shared storage.
• 🪽 PegaProx High Availability - Pair up to 4 PegaProx instances: standbys keep a copy of the configuration, show a live view and pass changes on to the leader; failover is a confirmed, manual promote, or (beta, switched on per group) automatic by majority vote, with an optional witness as the third vote
• 🧩 Automated PVE Installations - Serve answer files for the Proxmox VE auto-installer from profiles (guided setup or editor) and follow every installation run
• 🛠️ V2P / ESXi Migration - Pyvmomi + SSHFS-based, with VirtIO driver pre-staging via MSI bulk-install (Windows guests).

#Notifications

• 📢 Webhook Channels - Slack, Discord, Microsoft Teams, ntfy, generic JSON webhooks (multi-channel, per-alert routing)
• 🔔 Web Push Notifications - Browser push via VAPID, “wake-up” pattern (no payload leaks to push provider). Inbox view in the topbar bell with unread badge.
• 📲 PWA / Installable App - Service Worker shell-cache, offline boot, install prompt, theme-color matching layout.

#Plugins

• 🌐 Client Portal - Self-service portal for hosting customers with VM power actions, noVNC console, snapshots, ISO mount, snapshot policies (read-only), 2FA, and password management
• 📊 Public Status Page - Cluster health dashboard for monitoring screens with URL-based auth key (no login required)
• 🔔 Notifications Plugin - ntfy + Apprise integration for unified channel routing
• 🐳 Docker Swarm Manager (Community) - Manage Swarm services from the same UI
• 🗄️ TrueNAS SCALE Manager (Community) - Monitor and administer TrueNAS SCALE (pools, datasets, snapshots, SMB/NFS shares, replication, apps/VMs, services, data-protection posture, telemetry) over JSON-RPC 2.0
• 🔌 Plugin Config Editor - Edit plugin configuration directly from the UI

#Advanced Features

• 🌐 Offline Mode - Works without internet (local assets, air-gap mode disables external CVE/sponsor lookups for VS-NfD / classified networks)
• 🎨 Themes - 17 themes including Dark/Light, Proxmox, Corporate (light/dark), Dracula, Nord, Monokai, Solarized, Cyberpunk, etc.
• 🏢 Corporate Layout - Tree-based sidebar with dense tables
• 🌍 Multi-Language - English, German, French, Spanish, Portuguese, Polish, Korean, Italian, Simplified Chinese
• 📱 Responsive + PWA - Works on desktop and mobile, installable as native-feeling app
• 📦 PBS Integration - Proxmox Backup Server management with backup verification
• 🔭 Prometheus Exporter - Scrape /api/metrics with a bearer token (an admin's or one with metrics.view) for cluster, node, guest, storage, replication and backup-age metrics

#📋 Requirements

• Python 3.10 to 3.13 (3.12 recommended)
• Proxmox VE 8.0+ or 9.0+ and/or XCP-ng 8.2+
• Modern web browser (Chrome, Firefox, Edge, Safari)

#⚡ Quick Start / Installation

#Automated Installation

This installation method pulls the deployment script directly from the current HEAD of the main branch. This means you will always receive the latest available version, including the most recent features and improvements. However, because it is not tied to a specific release, it may also contain unreleased changes or bugs that have not yet been fully tested. If you prefer a stable and tested version, consider installing PegaProx from a tagged release instead.

curl -O https://raw.githubusercontent.com/PegaProx/project-pegaprox/refs/heads/main/deploy.sh
chmod +x deploy.sh
sudo ./deploy.sh

#Debian Repository

This installation method uses the official APT repository provided by gyptazy. The repository and its associated build and packaging pipeline are fully hosted and maintained by gyptazy, where PegaProx releases are automatically built and published as Debian packages. Unlike the automated installation script, which pulls the latest code directly from the repository branch, the APT repository distributes packaged and versioned releases. This generally provides a more stable and predictable installation, making it the recommended approach for production environments.

curl https://git.gyptazy.com/api/packages/gyptazy/debian/repository.key -o /etc/apt/keyrings/gyptazy.asc
echo "deb [signed-by=/etc/apt/keyrings/gyptazy.asc] https://packages.gyptazy.com/api/packages/gyptazy/debian trixie main" | sudo tee -a /etc/apt/sources.list.d/gyptazy.list
apt-get update

apt-get -y install pegaprox

#Installation from Source

This installation methods run PegaProx directly from the source code repository. It is primarily intended for development, testing, or advanced users who want full control over the codebase or want to modify and extend the project.

By default, cloning the repository will pull the latest state of the main branch, which contains the most recent changes and features. While this ensures you always have the newest code available, it may also include in-progress changes that are not part of an official release yet. If you prefer a more stable version, you can optionally checkout a specific release tag from the repository before installing dependencies and starting the application. This allows you to run the exact code corresponding to an official release while still using the source-based installation method.

Running PegaProx from source can be useful for debugging, contributing to the project, or integrating custom functionality, since you have direct access to the entire codebase and can easily update it using standard Git workflows.

#Manual Installation

git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox
pip install -r requirements.txt
python3 pegaprox_multi_cluster.py

#Docker

docker compose up -d

Or without Compose:

docker run -d --name pegaprox \
  -p 5000:5000 -p 5001:5001 -p 5002:5002 \
  -v pegaprox-config:/app/config \
  -v pegaprox-logs:/app/logs \
  --restart unless-stopped \
  ghcr.io/pegaprox/pegaprox:latest

The same image is on Docker Hub as pegaprox/pegaprox, with the identical digest, so pegaprox/pegaprox:latest works just as well. Other PegaProx images on Docker Hub are not ours and may be outdated.

From 1.4.1 on, the Docker images and the VM/LXC appliance images carry a signed build provenance attestation, so you can check that an image was built by our release workflow from this repository:

gh attestation verify oci://ghcr.io/pegaprox/pegaprox:<version> -R PegaProx/project-pegaprox
gh attestation verify oci://docker.io/pegaprox/pegaprox:<version> -R PegaProx/project-pegaprox
gh attestation verify pegaprox-v<version>-vm-amd64.qcow2 -R PegaProx/project-pegaprox

For local builds:

git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox
docker build -t pegaprox .
docker run -d --name pegaprox \
  -p 5000:5000 -p 5001:5001 -p 5002:5002 \
  -v pegaprox-config:/app/config \
  -v pegaprox-logs:/app/logs \
  --restart unless-stopped \
  pegaprox

#Debian Package (.deb build)

git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox

dpkg-buildpackage -us -uc
sudo dpkg -i ../pegaprox_*.deb

#🔄 Updating

Option 1: Update Script (Recommended)

cd /opt/PegaProx
curl -O https://raw.githubusercontent.com/PegaProx/project-pegaprox/refs/heads/main/update.sh
chmod +x update.sh
sudo ./update.sh

Option 2: Web UI

Go to Settings → Updates and click "Check for Updates".

#🔧 Configuration

After starting PegaProx, open your browser and navigate to:

https://your-server-ip:5000

A fresh install has no default credentials:

1. Setup wizard: The first visit opens the setup wizard, where you create the first admin account
2. Add Cluster: Go to Settings → Clusters → Add your Proxmox credentials
3. Done! Start managing your VMs

#📁 Directory Structure

/opt/PegaProx/
├── pegaprox_multi_cluster.py   # Entry point
├── pegaprox/                   # Application package
│   ├── app.py                  # Flask app factory
│   ├── constants.py            # Configuration constants
│   ├── globals.py              # Shared state
│   ├── api/                    # REST API blueprints
│   ├── core/                   # Business logic (manager, db, cache)
│   ├── background/             # Background tasks (scheduler, alerts)
│   ├── utils/                  # Utilities (auth, RBAC, LDAP, OIDC)
│   └── models/                 # Data models
├── web/
│   ├── index.html              # Compiled frontend
│   └── src/                    # Frontend source (JSX)
├── config/
│   └── pegaprox.db             # SQLite database - fully encrypted at rest via SQLCipher (Linux x86_64); plain SQLite + Fernet-encrypted fields elsewhere
├── static/                     # JS/CSS libraries (offline mode)
├── logs/                       # Application logs
└── update.sh                   # Update script

#🔒 Security

• Database at rest → SQLCipher (AES-256-CBC + HMAC-SHA512, SQLCipher format v4) on Linux x86_64. Plain SQLite + per-field Fernet on other platforms (ARM / macOS / Windows). See docs/SECURITY.md for the threat model and recovery story.
• Master key custody → Multi-tier loader: PEGAPROX_DB_KEY env / systemd LoadCredentialEncrypted (TPM2-bound) / /etc/pegaprox/secret.key / ~/.config/pegaprox/secret.key / legacy config/. Default chmod 0600, files with loose permissions are skipped rather than used silently.
• Sensitive fields (Cluster PW, SSH keys, TOTP secrets, OIDC client secrets, LDAP bind) → Fernet (AES-256-GCM equivalent), works even when full-DB encryption isn't available.
• API Tokens → SHA-256 hash (constant-time compare).
• Passwords → Argon2id (3 iter, 64 MB memory cost).
• HTTPS required for production.
• Session tokens expire after inactivity; optional strict-IP binding.
• Per-IP rate limiting on login + every authenticated endpoint.
• Input sanitization, CSRF Origin matching, RBAC enforced server-side on every route.
• Auto-encryption on first boot - operators can opt out with PEGAPROX_DISABLE_AUTO_ENCRYPT=1 if they want to take their own pre-encryption backup first.

#📖 Documentation

Full documentation is available at docs.pegaprox.com

#📜 License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Attribution (AGPL §7b): Under Section 7(b) of the AGPL, the "Powered by PegaProx" attribution shown in the client portal is a required author attribution and must be preserved in every copy and modified/derivative version — see the NOTICE file. Note also that AGPL §13 requires anyone hosting a modified version for network users to publish that version's complete source to those users. PegaProx is AGPL-3.0 only — the attribution applies to everyone, without exception.

#💬 Support

• 💬 Discord: Community Server
• 📧 Email: support@pegaprox.com
• 🐛 Issues: GitHub Issues

#🤖 Development Tools

Like most modern dev teams, we use AI-assisted tooling (code completion, docs generation, review automation, security audits). All architecture decisions, implementation, and testing are handled by our three-person team. - see IBM , IBM Case Studies , MIT Tech Review

AI-driven security auditing is an industry-standard practice - see Hacker News, IBM Research.

#⭐ Star History

If you find PegaProx useful, please consider giving it a star! ⭐

Made with ❤️ by the PegaProx Team