Homelab & Virtualization

PegaProx: A Free, Open-Source Dashboard for Proxmox and XCP-ng

Getting it installed, connecting your first cluster, and what its current beta status actually means for you.

My own homelab is one three-node Proxmox cluster, so I've never needed to manage more than a single Proxmox web UI at once. That's exactly why PegaProx caught my attention: it's built for multi-cluster management, but it's worth installing even if, like me, you've only got the one cluster. It's a free, AGPL-licensed replacement for Proxmox's own dashboard, with role-based access, automation, and a Proxmox Datacenter Manager-style overview built in from day one, so it's already doing something useful the moment you connect it and ready to scale the day a second cluster shows up.

Why Bother, With Just One Cluster?

Proxmox's own Datacenter Manager (PDM) covers basic multi-cluster visibility, but it's thin: no in-place VM creation, no host-configuration management, and no built-in load balancing across nodes. PegaProx does all three, plus role-based access control, 2FA, API tokens, audit logging, and scheduled snapshot policies, all from one interface that talks to Proxmox's existing API rather than replacing it. None of that requires a second cluster to be useful; it's simply a nicer, more capable front end for the one you already have.

The multi-cluster piece is what makes it worth knowing about ahead of time rather than after the fact, though. If you ever pick up a second Proxmox box, at a parent's house, a colo cage, or just a second physical location, PegaProx already has a real-time dashboard, cross-cluster VM migration, and load-balancing across clusters ready to go the moment you connect it, with no re-architecting required.

Getting It Running

PegaProx is a Python app, not a Docker image you drop into an existing container host, so it needs its own small guest rather than joining whatever's already running your other self-hosted services. Given how low the resource floor is, a small dedicated LXC is the natural fit, the same instinct behind running most things in an LXC first that I use for Docker itself. There are three real ways to get it installed:

Pre-built LXC/VM image: the project publishes a ready-to-import container template and a qcow2 VM disk with everything pre-installed. The CT template imports through Proxmox's own CT Templates section like any other template; the VM image needs a CLI import since Proxmox has no upload path for raw disk images.
Automated script (main branch): curl -sSL https://raw.githubusercontent.com/PegaProx/project-pegaprox/refs/heads/main/deploy.sh | sudo bash against a fresh Debian/Ubuntu guest. It handles dependencies, SSL, the systemd service, and firewall rules automatically, but it pulls straight from the current main branch, so it can carry unreleased changes.
Debian repository: an official APT repo (maintained by gyptazy) that ships versioned, tested releases. This is the one the project itself recommends for anything other than casual testing.

Minimum requirements are 1 CPU core, 1GB RAM, and 1GB disk for managing up to five clusters; the project's own recommendation for a comfortable deployment is 4 cores, 8GB RAM, and 20GB disk. Either fits comfortably in a small LXC, which is where mine lives.

First Login and Connecting Your First Cluster

A fresh install ships with no default credentials. Point a browser at https://your-server-ip:5000 and the setup wizard walks through creating an administrator account (username, password, email, and an optional TOTP 2FA enrollment) before it lets you in anywhere else.

From there, adding a cluster is under Settings → Clusters: point it at your Proxmox host (https://host:8006) and authenticate. An API token scoped to what PegaProx actually needs is the safer long-term choice over handing it the root@pam password directly, especially once role-based access control matters to you. Repeat the same step for a second cluster whenever you have one, and it shows up in the same unified dashboard alongside the first.

What You Actually Get

The feature list is long enough that it's easier to group than list. These are the categories that matter for a homelab-to-small-business scale deployment:

Cluster & VM Operations

Live metrics and global search across every connected cluster, in-place VM/container creation and config edits, snapshots, backups with verification, and noVNC/xterm.js consoles without leaving the browser.

Load Balancing & Migration

A score-based algorithm weighing CPU and RAM utilization spreads workloads across nodes, and cross-cluster VM migration and snapshot-based replication move guests between clusters entirely, not just between nodes in one.

Security & Access

Role-based access control, API token management, TOTP 2FA, WebAuthn/FIDO2, LDAP/OIDC, VM-level ACLs, IP allow/deny lists, and HMAC-signed audit logging that exports to CSV or forwards to a SIEM.

Automation & Reporting

Scheduled tasks and snapshot policies, rolling node updates, config drift detection, Cloud-Init templates for common distros, and cost/power dashboards if you're tracking either at home or for a client.

Where It's Rough Right Now

PegaProx moves fast, and that cuts both ways. It's still tagged as a pre-1.0 release on GitHub, and early hands-on testing found offline VM copies reliable while live cross-cluster migration and replication were still described as work in progress. None of that makes it unusable, but it does mean the newest features are the ones most worth testing carefully before trusting them with anything you'd be upset to lose.

The practical takeaway: the main-branch install script is convenient for kicking the tires, but it's also the path most likely to hand you an unreleased bug. If PegaProx becomes something you actually rely on day to day, move to the maintained Debian repository build instead, and keep it as an addition to your normal Proxmox backup routine, not a replacement for one.

A Few Things I'd Get Right From the Start

1. Don't run PegaProx on the only cluster it manages

If your single dashboard lives as a VM or LXC inside the one cluster it's watching, a hardware problem on that cluster takes down your management layer at the exact moment you'd want it most. A small separate node, even an old mini PC, is worth it for this alone.

2. Use an API token, not the root password

Handing PegaProx root@pam's actual password works, but a scoped API token limits the blast radius if the PegaProx instance itself is ever compromised. Set this up before you get comfortable and forget to revisit it.

3. Pick the Debian repo over the script for anything you'll keep

The one-line install script is the fastest way to try PegaProx, but it tracks the main branch. Once you know you're keeping it, switching to the versioned APT repository trades a little convenience for landing on tested releases instead of whatever merged an hour ago.

4. Turn on 2FA immediately

A tool with this much reach into your infrastructure, VM creation, snapshots, node configuration, is worth the thirty seconds TOTP enrollment takes during initial setup, even on a homelab nobody else can reach.

5. Keep Proxmox's own backups running independently

PegaProx can trigger and verify backups, but it's still new enough that your actual disaster-recovery plan should keep working exactly as it did before you installed it. Treat PegaProx as a better window into your infrastructure, not the thing standing between you and data loss.

Related Resources

PegaProx

The official project site.

Installation Docs

Full install instructions, including the Docker and pre-built image options this guide summarizes.

Source on GitHub

AGPL-3.0 licensed, current release notes, and where to file issues.

Docker on Proxmox & Windows

The same LXC-first instinct behind where PegaProx itself should live.

OpenClaw AI Homelab

Another self-hosted service running on the same three-node cluster.

SFF Proxmox Nodes

Where to start if you're eyeing a second cluster to actually use PegaProx's multi-cluster side.

Frequently Asked Questions

Is PegaProx free to use?

Yes. It's licensed under AGPL-3.0 and fully open source, with no paid tier or subscription warnings to click past. The one AGPL obligation worth knowing is that if you build on it and expose it to others over a network, you need to make your modified source available, and any client-facing portal you build has to keep the "Powered by PegaProx" attribution.

Do I need more than one Proxmox cluster to get anything out of PegaProx?

No. It works fine pointed at a single cluster, and a lot of people run it that way just for the nicer dashboard, role-based access control, and automation it adds on top of Proxmox's own UI. The multi-cluster features simply sit there ready to use the day you add a second cluster.

Does PegaProx replace the Proxmox web UI entirely?

For most day-to-day tasks, yes; it covers VM and container management, snapshots, backups, consoles, and node administration well enough that you can stop opening Proxmox's own interface for routine work. Proxmox's native UI is still there underneath and still the right place for anything PegaProx doesn't expose yet, since PegaProx talks to Proxmox's API rather than replacing it.

Is PegaProx ready for production use?

Treat it as a fast-moving beta rather than a finished 1.0 product. The GitHub repo's own releases are still tagged pre-1.0, and early hands-on reviews found live cross-cluster migration and replication less polished than the rest of the app. If you do run it against anything you care about, install from the maintained Debian repository instead of the main-branch script, and keep your normal Proxmox backup routine as the actual safety net, not PegaProx itself.

What are the minimum system requirements?

The documented floor is 1 CPU core, 1GB of RAM, and 1GB of disk for managing up to about 5 clusters, which is light enough for a small LXC container. For a comfortable production-style deployment the project recommends 4 cores, 8GB of RAM, and 20GB of disk; requirements scale up from there only if you're managing dozens of clusters at once.

Does PegaProx support XCP-ng as well as Proxmox?

Yes, XCP-ng 8.2 and newer is supported alongside Proxmox VE 8.0+ and 9.0+, and PegaProx can manage both hypervisor types from the same dashboard. It also includes tooling for migrating VMs off VMware ESXi, which is useful if you're consolidating hypervisors rather than running two long-term.