https://github.com/pegaprox/project-pegaprox

The ultimate datacenter management solution for Proxmox VE and XCP-NG. Unified multi-cluster control, intelligent load balancing, and seamless cross-cluster VM migrations — all in one beautiful interface.
https://github.com/pegaprox/project-pegaprox

backup-management cluster-management container-management datacenter high-availability load-balancing monitoring multi-cluster proxmox proxmox-ve self-hosted sysadmin virtualization vm-management web-dashboard

Last synced: 2 days ago
JSON representation

Host: GitHub
URL: https://github.com/pegaprox/project-pegaprox
Owner: PegaProx
License: agpl-3.0
Created: 2026-01-18T02:06:52.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-06-08T10:07:47.000Z (5 days ago)
Last Synced: 2026-06-08T10:18:47.767Z (5 days ago)
Topics: backup-management, cluster-management, container-management, datacenter, high-availability, load-balancing, monitoring, multi-cluster, proxmox, proxmox-ve, self-hosted, sysadmin, virtualization, vm-management, web-dashboard
Language: JavaScript
Homepage: https://pegaprox.com/
Size: 18.6 MB
Stars: 1,263
Watchers: 14
Forks: 87
Open Issues: 34
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

PegaProx

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

Website •
Documentation •
Releases •
Plugins •
Sponsoring

---

## 🚀 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.

Dashboard Screenshot

### 🪽 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](mailto:sponsor@pegaprox.com) or chipping in on [Open Collective](https://opencollective.com/pegaprox). Every euro keeps the lights on. 💛

### 💎 Platinum

### 🥇 Gold

### 🥈 Silver

### 🥉 Bronze

_{Individual supporters: Andreas Huemmer}

Become a Sponsor •
Open Collective

## ✨ 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
- 🔄 **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** - Auto-restart VMs on node failure with configurable timing
- 📍 **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 (Ubuntu 22.04/24.04, Debian 11/12, AlmaLinux 9, Rocky 9, Fedora 40, Alpine 3.19) 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.
- 🛠️ **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
- 🔌 **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, Korean, Italian
- 📱 **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 bearer auth for cluster + VM metrics

## 📋 Requirements

- Python 3.8+
- 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.

```bash
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.
```bash
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
```bash
git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox
pip install -r requirements.txt
python3 pegaprox_multi_cluster.py
```

### Docker
```bash
docker compose up -d
```

Or without Compose:
```bash
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
```

For local builds:
```bash
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)
```bash
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)**
```bash
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
```

Default credentials:

```
Username: pegaprox
Password: admin
```

1. **First Login**: Create your admin account on the setup page
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`](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](https://docs.pegaprox.com)**

## 📜 License

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

## 💬 Support

- 💬 Discord: [Community Server](https://discord.gg/AJPf3H62QW)
- 📧 Email: support@pegaprox.com
- 🐛 Issues: [GitHub Issues](https://github.com/PegaProx/project-pegaprox/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](https://www.ibm.com/solutions/ai-coding) , [IBM Case Studies](https://www.ibm.com/case-studies/ibm-software-team) , [MIT Tech Review](https://www.technologyreview.com/2025/12/15/1128352/rise-of-ai-coding-developers-2026/)

AI-driven security auditing is an industry-standard practice — see [Hacker News](https://thehackernews.com/2026/02/claude-opus-46-finds-500-high-severity.html), [IBM Research](https://www.ibm.com/think/insights/chatgpt-4-exploits-87-percent-one-day-vulnerabilities).

## ⭐ Star History

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

---

Made with ❤️ by the PegaProx Team

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pegaprox/project-pegaprox

Awesome Lists containing this project

README

PegaProx