I installed PegaProx in an LXC container to manage my Proxmox (and what it taught me on day one)

A few days ago I turned my old laptop into a Proxmox server for my sysadmin course lab. The Proxmox UI is fine, but it’s very much node by node and tab by tab, and I was missing a front page that tells me at a glance how everything is doing. Today I tried PegaProx, a free (AGPL) management panel for Proxmox VE that pitches itself as “vCenter for Proxmox”: inventory across every cluster, load balancing, migrations, alerts, console… Here’s how I installed it and what I found.

Spoiler: the install takes five minutes, the only problem was my fault (or my DNS’s), and the most useful thing on day one wasn’t a headline feature but a warning that made me blush.

1. Where to install it: an LXC, not the host

PegaProx can be installed four ways: a script, an APT repository, Docker or from source. And it runs on any Debian, including the Proxmox host itself.

I didn’t want it on the host. The hypervisor is the last thing I want to clutter with third-party packages and repos: if a PegaProx update breaks something in Python, I don’t want it dragging the node down. So I gave it its own LXC container:

Resource	Value
Template	Debian 13 (debian-13-standard)
Type	Unprivileged, with nesting=1
CPU / RAM	2 cores, 1 GB (+512 MB swap)
Disk	8 GB on the SSD
Network	Static IP on the home network

From the host shell:

pveam update
pveam download local debian-13-standard_13.6-1_amd64.tar.zst

pct create 105 local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst \
  --hostname pegaprox --cores 2 --memory 1024 --swap 512 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.75/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 \
  --unprivileged 1 --features nesting=1 --onboot 1 \
  --timezone Europe/Madrid \
  --ssh-public-keys /root/my-key.pub

pct start 105

Swap in your own IP, ID and storage. With --ssh-public-keys you can SSH in with your key without ever setting a root password.

2. Install from the APT repo (not the script)

The install script in the README is the shortest path, but it pulls the latest from the main branch, including changes that haven’t shipped in any release yet. The APT repository publishes packaged releases instead, and it updates with your usual apt upgrade. For something that’s going to hold the keys to my Proxmox, I’ll take the latter.

Inside the container (pct enter 105):

apt update && apt full-upgrade -y
apt install -y curl ca-certificates

install -d /etc/apt/keyrings
curl -fsSL 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" \
  > /etc/apt/sources.list.d/gyptazy.list

apt update
apt install -y pegaprox

The package creates a pegaprox user and a systemd service of the same name, and keeps its data in /var/lib/pegaprox. I got version 1.4.0.

The perl: warning: Setting locale failed messages during the install aren’t PegaProx’s fault: the Debian template ships without generated locales. Fix them with sed -i 's/^# *en_US.UTF-8/en_US.UTF-8/' /etc/locale.gen && locale-gen.

To check it’s alive:

systemctl is-active pegaprox
ss -tlnp | grep -E ':500[0-2]'

It listens on three ports: 5000 (the web UI, over HTTPS), 5001 (the VNC console over WebSocket) and 5002 (the SSH terminal over WebSocket).

3. First login and adding the node

Open https://container-IP:5000, accept the certificate warning (it’s self-signed, just like Proxmox’s) and there’s no default user: the first visit opens a wizard to create the admin. I like that; better than an admin/admin that someone forgets to change.

Then Add cluster and fill in:

• Name: whatever you like.
• Host: the node’s address. This is where the trap is, more on that in a second.
• User and password: root@pam and its password, or an API token (format user@realm!tokenid).
• SSL verification: off if your Proxmox uses its self-signed certificate.

The failure: “Cannot connect”

In Host I typed the node’s hostname instead of its IP. Result: Failed to connect: Cannot connect. The Proxmox API was answering just fine from the container, so I checked what that name resolved to:

getent hosts node-name

It returned the IP the laptop had before I reinstalled it, back when it was a CachyOS desktop. The router’s DNS had kept that mapping from when the machine got its IP via DHCP, and nothing had updated it. PegaProx was trying to talk to a machine that no longer existed.

With the IP in the Host field, it connected first time. The real fix is cleaning up that entry on the router, but for a management panel I’d rather use the IP anyway: if DNS goes down, I still want to see my machines.

What it does with root

I added the node with root@pam, and the log showed Connected to Proxmox ... using API Token. PegaProx creates an API token on its own on root@pam (you’ll see it under Datacenter > Permissions > API Tokens with the comment “PegaProx management token”) and uses that token from then on instead of the password.

Handy, but careful: the token is created without privilege separation, so it can do everything root can. Fine for a lab. For anything serious I’d create a dedicated PegaProx user with its own token and give it only the role it needs.

The config database is encrypted with SQLCipher on Linux x86_64, so credentials aren’t sitting in plain text on the container’s disk.

4. What I saw on day one

With a single node, PegaProx is basically a very well presented inventory: node status, running and stopped VMs and containers, CPU, RAM, storage (including the NAS share), a topology view and a top 10 of what’s using the most.

And then I saw this table: “Guests without a backup job: 5”. All of them. I have the NAS storage added in Proxmox for backups, I wrote an entire guide on backups and snapshots… and I hadn’t scheduled a single job on the laptop. Proxmox won’t tell you unless you go looking; PegaProx puts it on the front page. That alone made the install worth it.

Other things that caught my eye:

• It’s light: about 175 MB of RAM and under 1 GB of disk with everything installed.
• It flags pending updates on the nodes.
• It has plugins (status page, notifications, client portal…) I haven’t tried yet.

5. Does it make sense with one node?

Partly. PegaProx’s showpiece is automatic balancing (moving VMs between nodes based on load) and managing several clusters from one place. With a single node the balancer looks around, sees there’s nowhere to move anything and does nothing; the log says exactly that: “Not enough online nodes for balancing”.

Where it’ll really shine is the three-node Ceph cluster I’m planning for home, or anywhere with several clusters. For a standalone node, it’s a clearer front page than Proxmox’s and a watchdog for the things you forget.

What not to do

• Install it on the Proxmox host “because you can”. An LXC gives you the same thing and can be deleted in a second.
• Use the main-branch script for something that will have root rights over your infrastructure. Stick to published releases.
• Use the hostname if you don’t trust your DNS. Check what it resolves to with getent hosts before blaming the tool.
• Forget the token it creates. If you remove PegaProx, delete the token on root@pam too.

Summary

1. An unprivileged Debian 13 LXC with 1 GB of RAM and 8 GB of disk is plenty.
2. Install from the APT repo: published releases, updated with apt.
3. No default user: the first visit creates the admin.
4. Add the node by IP; if you use root, PegaProx creates a token with root rights.
5. On one node it’s an inventory and a watchdog; balancing needs at least two.

For a one-node homelab it’s not essential, but that backup warning has already done more for me than plenty of tools I’ve used for years. This week I’m scheduling those backups.