Proxman

Multi-cluster management for Proxmox VE, XCP-ng, and ESXi migration workflows.

Version	0.9.16
License	AGPL-3.0
Python	3.10–3.13 (3.8+ declared; tested on 3.10–3.13)
Repository	code.koetsier.org/sebas/proxman

Overview

Proxman is a web-based control plane for virtualisation clusters. It connects to multiple Proxmox VE clusters (and optionally XCP-ng pools or ESXi hosts for migration) and provides a single interface for VM lifecycle, storage, backups, automation, monitoring, and access control.

This repository is a maintained fork with a refactored backend, an automated test suite, and a Core Node UI layout (documented in .design/core_node/).

Capabilities include:

• Multi-cluster dashboard with live metrics over Server-Sent Events
• VM and LXC management: power actions, configuration, snapshots, backups, browser consoles (noVNC, xterm.js)
• Scheduled tasks, rolling node updates, load balancing, and high availability
• Role-based access control, two-factor authentication, WebAuthn, LDAP/OIDC integration
• Encrypted configuration database and tamper-evident audit logging
• Proxmox Backup Server, Ceph, Prometheus metrics export, SIEM forwarding, and a plugin framework

Requirements

• Python 3.10 or newer (3.12 recommended)
• Proxmox VE 8.0 or 9.0, and/or XCP-ng 8.2+
• A current Chromium, Firefox, Edge, or Safari browser

Installation

Deploy script (recommended for servers)

From a checkout:

sudo ./deploy.sh

Remote install (defaults to this fork):

curl -sSL https://code.koetsier.org/sebas/proxman/raw/branch/main/deploy.sh | sudo bash

The script installs to /opt/Proxman, creates a systemd unit (proxman.service), and generates a master key at /etc/proxman/secret.key.

Override the clone URL if needed:

PROXMAN_REPO=ssh://git@code.koetsier.org/sebas/proxman.git sudo ./deploy.sh

From source (development)

git clone ssh://git@code.koetsier.org/sebas/proxman.git
cd proxman
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m proxman.server

On first access, open https://<host>:5000 and complete the setup wizard (admin account, first cluster).

Docker

docker compose up -d

Local image build:

docker build -t proxman .
docker run -d --name proxman \
  -p 5000:5000 -p 5001:5001 -p 5002:5002 \
  -v proxman-config:/app/config \
  -v proxman-logs:/app/logs \
  --restart unless-stopped \
  proxman

Persistent data lives under config/ (excluded from version control). Back up that directory before upgrades.

Network ports

Port	Service
5000	Web UI and REST API
5001	VNC WebSocket proxy
5002	SSH WebSocket proxy

When the web port is set to 443, VNC and SSH proxies use 444 and 445 respectively.

Configuration

Path	Description
config/proxman.db	Application database (SQLCipher on supported platforms)
config/settings.json	Server settings
/etc/proxman/secret.key	Database master key (default on systemd installs)

Additional key sources (environment variables, systemd credentials) are documented in proxman/core/dbcrypto.py.

Development

Backend

source .venv/bin/activate
pip install -r requirements-dev.txt
pytest tests/ -v
python3 -m proxman.server

Application entry point: proxman.server.main (gevent WSGI, TLS termination, console proxy servers).

Frontend

UI sources are in web/src/. The production bundle is built into web/index.html:

./web/Dev/build.sh

For live iteration with in-browser Babel compilation:

./web/Dev/build.sh --restore

Rebuild after any change under web/src/.

Repository layout

proxman/
  app.py                 Flask application factory
  server.py              Process startup and WSGI
  core/manager_pkg/      ProxmanManager (API client, HA, load balancing, SSH)
  api/vms_pkg/           VM-related HTTP blueprints
  services/              ClusterRegistry, SessionStore, RateLimiter
  background/            Schedulers, metrics broadcast, alerts
  utils/                 Authentication, RBAC, audit, SSH pool

web/
  index.html.original    HTML shell and theme definitions
  src/                   React application sources
  Dev/build.sh           Concatenation and Babel pre-compile

tests/                   pytest suite
.design/                 Core Node design system

Architecture

Application layer. proxman.app.create_app() registers the HTTP API and serves the single-page UI. Shared runtime state is held in proxman.services rather than module-level globals.

Manager layer. ProxmanManager in proxman/core/manager_pkg/ encapsulates Proxmox API access, cluster caching, load balancing, HA operations, and SSH execution.

API layer. VM endpoints are split into domain blueprints under proxman/api/vms_pkg/ and registered through register_vms_blueprints(app).

User interface. The front end is a React 18 application compiled into one HTML file. Layout modes:

Layout	Description
core-node	Default. Light, mobile-first overview (Core Node design system)
modern	Dark theme with card-based navigation
corporate	Tree sidebar and dense data tables
cloud	Experimental card-grid layout

Layout and colour theme are selected under My Profile. Token definitions are in .design/core_node/DESIGN.md.

Testing

.venv/bin/pytest tests/ -v

The suite covers authentication, session handling, rate limiting, host validation, negative caching, RBAC, and service-layer behaviour.

Upstream and license

Proxman originates from the Proxman open-source project (AGPL-3.0). This fork maintains independent deployment, structural refactors, and the Core Node interface.

Upstream documentation remains available at docs.proxman.com.

Contributing

1. Clone from code.koetsier.org/sebas/proxman
2. Create a branch named feat/<short-description> or fix/<short-description>
3. Run pytest tests/ -v and ./web/Dev/build.sh before submitting changes
4. Use Conventional Commits for commit messages