ProxmoxVEx Wiki

Version: 1.2.619
Build: 2026.10.05
License: ProxmoxVEx Source-Available License (proprietary — see LICENSE)
Homepage: proxmoxvex.com
Source: github.com/ArMaTeC/proxmox-vex-public

Table of Contents

1. What is ProxmoxVEx?
2. Why Use ProxmoxVEx?
3. Key Capabilities
4. Architecture and Tech Stack
5. Project Layout
6. Installation and Deployment
7. Initial Configuration
8. Environment Variables
9. REST API and Monitoring
10. Security
11. Plugins and Extensibility
12. Updating and Maintenance
13. Troubleshooting
14. Support and Resources

What is ProxmoxVEx?

ProxmoxVEx is a web-based management layer for one or more Proxmox VE and ESXi clusters. It gives operators a single dashboard to monitor, operate, and automate virtual machines, LXC containers, storage, backups, and users across all of their clusters from one place, without logging into each cluster individually.

The project is aimed at homelabs, small service providers, and operations teams that need multi-tenant access control, scheduled automation, centralized observability, and compliance reporting.

At its core, ProxmoxVEx is a Python/Flask backend with a single-page React frontend, a PostgreSQL database, noVNC and xterm.js consoles, and an in-process plugin architecture for extensibility.

Why Use ProxmoxVEx?

• One dashboard for many clusters - health, resource usage, and alerts across all sites in real time.
• Built for teams - role-based access, multi-tenancy, LDAP/OIDC, and audit logging.
• Automation out of the box - schedule snapshots, rolling updates, backups, and cross-cluster replication.
• Compliance and cost visibility - cost chargeback, carbon estimates, right-sizing recommendations, and BSI/ISO/NIS2/SOC 2 mapping.
• Localized interface - the UI ships in English, German, Spanish and French.
• Air-gap ready - all static assets are bundled locally; offline mode disables external lookups for classified networks.

Key Capabilities

Multi-Cluster Operations

• Unified dashboard for Proxmox VE and ESXi resources.
• Live CPU, RAM, storage, and network metrics via Server-Sent Events and WebSockets.
• One-click VM power actions and live migration.
• Cross-cluster load balancing and storage-agnostic snapshot replication.
• Cross-hypervisor migration from ESXi, including near-zero-downtime and offline options.

Lifecycle and Scheduling

• VM and LXC configuration editing, snapshots, and backups.
• Workload conversion between LXC containers and VMs (Debian, Ubuntu, Alpine, Rocky, CentOS, RHEL, AlmaLinux, Fedora, Arch), plus guest-aware disk grow/shrink and clone-replace.
• Tag-based or per-VMID snapshot schedules with retention pruning.
• Backup verification: restore, boot, health-check, and cleanup.
• Cloud-Init template library for fast provisioning.
• Rolling node updates with automatic evacuation.

Access and Security

• Role-based access control with built-in and custom roles.
• Multi-tenancy, IP allow/block lists, and VM-level ACLs.
• TOTP and WebAuthn / FIDO2 two-factor authentication.
• LDAP and OIDC support for Active Directory, Entra ID, Keycloak, Authentik, and others.
• API tokens with bearer authentication.
• PostgreSQL with field-level Fernet encryption for sensitive columns; database volume encryption is provided by the PostgreSQL host.
• HMAC-signed, tamper-evident audit log.
• CVE scanning and CIS hardening baseline checks.

Monitoring, Reporting, and Automation

• Prometheus-compatible /api/metrics endpoint.
• Cost and chargeback reporting, power and carbon estimates.
• Right-sizing recommendations and capacity forecasts.
• Network topology visualization.
• Compliance dashboards for BSI Grundschutz, ISO 27001, NIS2, and SOC 2.
• Integrated syslog receiver and SIEM forwarding.
• Config drift detection with alerting.

Storage, Networking and Security

• Ceph, ZFS, TrueNAS, NetApp and Proxmox Backup Server management.
• Software-defined networking, VLANs, bridges and firewall rules.
• IPAM, DNS sync and certificate lifecycle management.
• VPN access portal, IDS/IPS and network topology visualization.

Automation and Alerting

• Scheduled snapshots, backups, rolling updates and maintenance windows.
• Backup verification, restore boot and cleanup workflows.
• Ansible runner and Terraform sync for infrastructure as code.
• Multi-channel notifications (Slack, Teams, Discord, webhooks, ntfy, PagerDuty).
• Alert correlation, incident timelines and syslog/SIEM forwarding.

Plugin Ecosystem

Plugins are loaded from plugins/ and published through the plugin directory. Installed examples include Docker Manager, NetApp Storage, OPNsense, TrueNAS, and Storage Rebalancer. They run alongside the plugin API so the tool can be extended with third-party modules.

Architecture and Tech Stack

ProxmoxVEx is a Python web application with a single-page React frontend. It uses gevent for high-concurrency I/O, PostgreSQL for persistence, and Paramiko-based SSH for cluster operations.

flowchart LR
    Browser -->|HTTPS / WebSocket| Server[Flask / gevent WSGI]
    Server --> API[REST API blueprints]
    Server --> WS[WebSocket / SSE realtime]
    API --> Core[Core services & PostgreSQL DB]
    Core --> SSH[Paramiko SSH to PVE/ESXi nodes]
    Core --> VNC[noVNC / xterm.js consoles]
    Core --> BG[Background workers]
    Core --> Plugins[Plugin registry]

Backend

• Python 3.14+ with Flask 3 and Werkzeug 3.
• gevent for asynchronous, high-concurrency request handling.
• PostgreSQL with field-level Fernet encryption for sensitive columns.
• Paramiko for SSH and websockets for console tunnels.
• cryptography, argon2-cffi, pyotp, fido2 for security primitives.
• ldap3, PyJWT for LDAP and OIDC authentication.

Frontend

• React single-page application.
• Tailwind CSS and Chart.js for UI and metrics.
• noVNC for QEMU graphical console.
• xterm.js for LXC and SSH terminal sessions.

Protocols and Ports

Project Layout

ProxmoxVEx/
├── ProxmoxVEx_multi_cluster.py   # Entry point
├── ProxmoxVEx/                   # Backend application package
│   ├── app.py                    # Flask app factory
│   ├── constants.py              # Configuration constants
│   ├── globals.py                # Shared runtime state
│   ├── api/                      # REST API blueprints
│   ├── core/                     # Business logic, DB, cache
│   ├── background/               # Background workers
│   ├── cli/                      # Maintenance utilities
│   ├── models/                   # Data models
│   └── native/                   # Built-in plugin packages
├── web/                          # Frontend build
│   ├── index.html                # Compiled UI
│   └── src/                      # Frontend source
├── config/                       # Runtime configuration and database
├── static/                       # Offline JS/CSS libraries
├── logs/                         # Application logs
├── plugins/                      # Plugin packages
├── docs/                         # Internal and user documentation
├── tests/                        # Test suite
├── Dockerfile                    # Container image
├── docker-compose.yml            # Docker Compose stack
└── install.sh / deploy.sh / update.sh   # Install and update scripts

Installation and Deployment

Requirements

• A 64-bit Linux host (x86_64 or aarch64); Windows and macOS are not supported.
• Python 3.14 or newer (not needed for Docker installs).
• PostgreSQL 13 or newer — the only supported database backend (not needed for Docker installs; the compose stack bundles it).
• Proxmox VE 8.0+ or 9.0+, and/or ESXi, and/or XCP-ng.
• A modern web browser.

Quick Start with Docker

The fastest way to try ProxmoxVEx is with the included docker-compose.yml:

docker compose up -d

Then open https://<host>:5000 and complete the first-run setup.

Option 1: One-Command Installer

On a fresh server, install.sh sets up everything in one pass — system packages, a local PostgreSQL role + database, the release archive in /opt/ProxmoxVEx, a Python venv, the systemd unit, the master encryption key, sudoers rules for self-restart, and firewall rules where a firewall is active:

apt update && apt install -y curl && \
    curl -fsSL https://proxmoxvex.com/downloads/install.sh | sudo bash

The apt install -y curl prefix bootstraps curl on minimal images that lack it — on RHEL-family use dnf install -y curl, on Arch pacman -Sy --noconfirm curl. On a terminal the installer opens a guided UI: it reports prerequisites, offers any pending OS updates, installs only the missing pieces, and streams progress into a live window.

Flags for unattended or customized runs (append after bash -s --):

curl -fsSL https://proxmoxvex.com/downloads/install.sh | sudo bash -s -- \
    --port=443 --no-interactive   # serve on 443, never prompt
# --no-firewall    skip ufw/firewalld rules
# --loopback-only  bind 127.0.0.1 only (behind a reverse proxy)
# --no-offline     skip caching static assets for offline mode
# --no-tui         force classic line output instead of the full-screen UI

PROXMOXVEX_SYSTEM_UPDATE=1 also applies pending OS updates without asking; the default is to offer them only on interactive runs.

To point at an existing PostgreSQL instead of installing a local one, export PROXMOXVEX_DATABASE_URL before running the installer. Re-running the script is safe — it upgrades in place and preserves /etc/ProxmoxVEx/ProxmoxVEx.env.

The older deploy.sh remains in the archive for advanced layouts (custom install roots, source checkouts); install.sh is the recommended path.

Option 2: Debian Package

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" | sudo tee /etc/apt/sources.list.d/gyptazy.list
sudo apt-get update
sudo apt-get install -y ProxmoxVEx

Option 3: Docker

Use the pre-built image:

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

Option 4: Release Archive

Download the latest release archive — it ships the prebuilt frontend bundle, so no Node.js or build step is needed. A running PostgreSQL instance is required; set PROXMOXVEX_DATABASE_URL or the standard PG* variables before first start:

curl -fSL -o ProxmoxVEx-latest.tar.gz https://proxmoxvex.com/downloads/ProxmoxVEx-latest.tar.gz
mkdir -p ProxmoxVEx
tar -xzf ProxmoxVEx-latest.tar.gz -C ProxmoxVEx
cd ProxmoxVEx
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export PROXMOXVEX_DATABASE_URL=postgresql://user:pass@localhost:5432/proxmoxvex
python3 ProxmoxVEx_multi_cluster.py

Systemd Service

After installing from the deploy script or .deb, ProxmoxVEx is managed by systemd:

sudo systemctl start ProxmoxVEx
sudo systemctl enable ProxmoxVEx
sudo systemctl status ProxmoxVEx

Logs are written to logs/ and to the systemd journal:

sudo journalctl -u ProxmoxVEx -f

Reverse Proxy

To run behind nginx, enable reverse-proxy mode:

PROXMOXVEX_BEHIND_PROXY=true PROXMOXVEX_TRUSTED_PROXIES="10.0.0.0/8,127.0.0.1" python3 ProxmoxVEx_multi_cluster.py

A sample nginx snippet is available in README.md.

Cloudflare Tunnel

ProxmoxVEx runs three separate listeners:

• Main web/API server on 127.0.0.1:5000
• VNC console WebSocket server on 127.0.0.1:5001
• SSH/LXC terminal WebSocket server on 127.0.0.1:5002

When PROXMOXVEX_BEHIND_PROXY=true is set, the frontend connects to the same public port (e.g. 443) for all three. A Cloudflare Tunnel must route the WebSocket paths to the correct origin ports, and this only works reliably with a locally-managed cloudflared tunnel. Remotely-managed/token tunnels can duplicate the 101 Switching Protocols handshake, causing the browser to fail with Invalid frame header.

Create a local tunnel:

cloudflared tunnel login
cloudflared tunnel create proxmoxvex-local
cloudflared tunnel route dns proxmoxvex-local proxmoxvex.example.com

This writes a credentials.json file, for example /root/.cloudflared/<tunnel-uuid>.json.

Edit /etc/cloudflared/config.yml:

tunnel: <tunnel-uuid>
credentials-file: /root/.cloudflared/<tunnel-uuid>.json

ingress:
  - hostname: proxmoxvex.example.com
    path: "^/api/clusters/.*/(shellws|termwebsocket)"
    service: http://127.0.0.1:5002
    originRequest:
      noTLSVerify: true

  - hostname: proxmoxvex.example.com
    path: "^/api/clusters/.*/vms/.*/vncwebsocket"
    service: http://127.0.0.1:5001
    originRequest:
      noTLSVerify: true

  - hostname: proxmoxvex.example.com
    service: http://127.0.0.1:5000
    originRequest:
      noTLSVerify: true

  - service: http_status:404

Then point the systemd ExecStart at the config file:

ExecStart=/usr/bin/cloudflared --no-autoupdate --config /etc/cloudflared/config.yml tunnel run

Reload and restart:

systemctl daemon-reload
systemctl restart cloudflared

Set PROXMOXVEX_BEHIND_PROXY=true and PROXMOXVEX_TRUSTED_PROXIES="127.0.0.1" so the app trusts X-Forwarded-* headers from cloudflared.

Initial Configuration

After starting ProxmoxVEx, open the web interface:

https://<server-ip>:5000

1. Complete the first-run setup wizard to create the administrator account.
2. Go to Settings > Clusters and add your Proxmox VE or ESXi credentials.
3. Start managing your clusters.

First-Run Security Notes

• A self-signed certificate is generated automatically if no custom certificate is provided. Replace it with a trusted certificate for production.
• The database is encrypted automatically on first boot on Linux x86_64 when a master key is available. Back up the key separately from the config/ directory.

Environment Variables

ProxmoxVEx behavior is tuned through PROXMOXVEX_* environment variables. Legacy mixed-case aliases are accepted as compatibility shims.

Networking

Concurrency and Performance

Security and Encryption

Logging and Auditing

Rate Limiting

Consoles

Internal / Advanced

REST API and Monitoring

REST API

All API routes live under /api/ and are protected by session cookie or Authorization: Bearer pgx_<token> header, except for the public blueprints listed below. API tokens are created in Settings > API Tokens and can be scoped to a role.

In-app API reference

Settings → API Reference renders a searchable view of every registered /api/ route — HTTP method badges, required permissions, path parameters — generated at runtime from the Flask URL map, so it can never drift from the deployed code. GET /api/openapi.json returns the machine-readable OpenAPI document for tooling.

Dashboard layouts (per-user)

The overview dashboard supports per-user layouts: enter Edit layout on the dashboard toolbar to reorder sections (drag or arrow buttons), resize them (1–3 columns), or hide them. Layouts can be saved under a name, optionally shared with the team (readonly to non-owners — adopting a shared layout copies it), applied from the dropdown, or reset to the built-in default.

Asset library (tracked uploads)

ISOs and disk images can be uploaded directly in the browser with resumable chunked uploads, per-chunk ordering enforcement, and SHA-256 checksum verification + dedupe (an identical file returns the existing asset instead of re-uploading). Uploaded assets appear under Storage → Library and Settings → Media library; “Deploy” opens the create-VM dialog prefilled with the asset’s volume. The create-VM ISO field also offers a From URL mode that downloads straight to PVE storage.

Health-score history

The cluster health score is snapshotted periodically (leader-elected worker, ~10 min cadence) and retained for 90 days. GET /api/clusters/<id>/health/history?days=N returns the series; the dashboard side column renders a sparkline plus a 7/30/90-day drill-down panel with per-point score factors.

Blueprints & custom images (vm-template-marketplace)

The paid vm-template-marketplace plugin (≥ v1.1.0) has a Library tab: register custom images from a download URL, an existing volume, or an uploaded asset, then compose blueprints (image + hardware + cloud-init + tags) and deploy them to a cluster as queued jobs. Deleting an image referenced by a blueprint marks it image_missing and blocks deploys until fixed.

Public Endpoints

The following blueprints can be accessed without authentication, depending on server settings:

• /api/auth (login challenge, WebAuthn attestation)
• /api/static_files (frontend assets)
• /api/sse/updates (public status page data, when enabled)
• /api/webauthn (public attestation options)
• /api/push (web push subscription)
• /api/metrics (Prometheus; can be toggled public)

Live Data

• Server-Sent Events: GET /api/sse/updates?token=<sse_token> for cluster and node metrics.
• WebSocket: GET /api/ws/updates for low-latency live updates; authenticate with a session_id JSON message after connect.

Prometheus Metrics

Scrape https://<host>:5000/api/metrics with an API token:

curl -H "Authorization: Bearer pgx_<token>" https://proxmoxvex.example.com:5000/api/metrics

The endpoint can also be made public in Settings > Server if ProxmoxVEx is placed behind a mutual-TLS reverse proxy.

Health Check

curl -k https://<host>:5000/api/health

Security

Security is documented in detail in SECURITY.md and docs/SECURITY.md. Highlights include:

• Database encryption at rest: PostgreSQL volume encryption is the operator’s responsibility; field-level Fernet encryption is used for sensitive columns.
• Master key custody: Multi-tier key loader supporting PROXMOXVEX_DB_KEY, systemd LoadCredentialEncrypted, PROXMOXVEX_KEY_FILE, and filesystem paths. The key should be backed up separately from config/.
• Password storage: Argon2id.
• API token storage: SHA-256 with constant-time comparison.
• Transport: HTTPS for production use; self-signed certificates are generated automatically if no certificate is provided.
• Session management: Time-limited sessions, optional IP binding, and per-endpoint rate limiting.
• Input and access control: server-side RBAC on every route, origin validation, and input sanitization.

For the full threat model, see docs/security/threat-model.md.

Plugins and Extensibility

Plugins are Python packages dropped into plugins/. A valid plugin exports a register(app) function and a manifest.json file that declares routes, frontend iframes, and compatibility. Plugins run in-process and are trusted by default.

Layout:

plugins/{plugin-name}/
├── manifest.json       # Required. Contract metadata.
├── __init__.py         # Required. Must export `register(app)`.
├── ui.html             # Optional. Frontend iframe markup (receives shared plugin-ui.css).
└── config.json         # Optional. Default configuration.

manifest.json fields include id, name, version, author, description, min_ProxmoxVEx, has_frontend, frontend_route, category, and min_license_tier. See docs/architecture/plugin-contract.md for the full contract, sample register(app) implementation, and UI rendering rules.

Native integrations include Active Directory, Microsoft Azure (Microsoft Entra service-principal authentication, ARM VM inventory, subscription discovery, and power lifecycle actions), Docker Swarm, NetApp ONTAP, OPNsense, pfSense, Portainer/Rancher, TrueNAS, VMware vCenter, VyOS, Zabbix and 60+ plugin extensions covering storage, networking, security, billing and automation. Proxmox Backup Server is a built-in core module (/api/pbs/*), not a native-integration card.

Updating and Maintenance

The recommended update path is the update.sh script:

cd /opt/ProxmoxVEx
# replace the host with your ProxmoxVEx instance or project mirror
curl -O https://<your-proxmoxvex-host>/update.sh
chmod +x update.sh
sudo ./update.sh

You can also check for updates from the web UI at Settings > Updates.

Troubleshooting

Cannot reach the web UI

1. Verify the process is running: sudo systemctl status ProxmoxVEx or docker ps.
2. Check the bind address: by default the server binds 127.0.0.1 unless PROXMOXVEX_BIND_ALL=true or PROXMOXVEX_HOST is set.
3. Confirm the firewall allows TCP 5000, 5001, and 5002.

Self-signed certificate warning

A self-signed certificate is generated on first start if no certificate is provided. Replace config/ssl/cert.pem and config/ssl/key.pem with a trusted certificate, or place ProxmoxVEx behind a reverse proxy that terminates TLS.

Consoles (noVNC / xterm.js) do not work

• noVNC and the SSH terminal require a valid certificate on the WebSocket ports 5001 and 5002, or a reverse proxy that terminates TLS.
• Ensure ports 5001 and 5002 are reachable from the client.
• Set PROXMOXVEX_BEHIND_PROXY=true when running behind nginx and add WebSocket Upgrade headers.

Database encryption

• If the master key is lost, the encrypted database is unreadable. Back up the key separately from config/.
• To check the active keystore tier: python3 ProxmoxVEx_multi_cluster.py --keystore-status.
• To migrate a plain database manually: python3 ProxmoxVEx_multi_cluster.py --migrate-db --dry-run.

Rate limiting or session issues

• PROXMOXVEX_API_RATE_LIMIT and PROXMOXVEX_API_RATE_WINDOW control request throttling.
• Sessions expire after inactivity. Enable strict-IP binding in Settings > Server if required.

Low file-descriptor limit

For 20+ clusters, increase the process limit:

# In the systemd unit override

[Service]
LimitNOFILE=65536

or set PROXMOXVEX_NOFILE=65536.

Support and Resources

• Documentation site: proxmoxvex.com
• Website: proxmoxvex.com
• Plugins: plugins.proxmoxvex.com
• Support: proxmoxvex.com/support
• Discord: Community Server
• Email: [email protected]