Getting Started — ProxmoxVEx

ProxmoxVEx is a self-hosted web application. This guide covers the supported platforms, system requirements, and every install method — pick your host OS below and the instructions will follow it.

Supported host operating systems

ProxmoxVEx runs on Linux only (x86_64 and aarch64). Windows and macOS are not supported as hosts — several Python dependencies ship Linux-only wheels.

Managed clusters (the systems ProxmoxVEx connects to): Proxmox VE 8.0+ or 9.0+, VMware ESXi/vCenter, and XCP-ng.

System requirements

Hardware

The minimum covers a small evaluation — a few VMs and the IDS/IPS disabled. Scale CPU and memory with the number of managed clusters; the anomaly-detection stack (scikit-learn, pandas, scapy) makes ProxmoxVEx heavier than a typical Flask app. These figures assume PostgreSQL runs on the same host — a remote database lowers the local requirement.

Software

The one-command installer and Docker image install/bundle all of these — this table is for the manual release-archive path.

Firewall and network ports

Inbound — on the ProxmoxVEx host

Notes on the defaults:

• The three app ports bind to loopback by default. Set PROXMOXVEX_BIND_ALL=1 (or Settings → Server) to serve the LAN, then restrict 5000–5002 to admin subnets.
• Behind a reverse proxy or Cloudflare Tunnel, keep the app on 127.0.0.1 and expose only the proxy’s port (443). The frontend routes the console WebSockets through the same public port; a locally-managed tunnel must map the WS paths to 5001/5002.
• Setting PROXMOXVEX_PORT shifts the console ports to PORT+1 and PORT+2 — adjust rules accordingly.

Outbound — to managed infrastructure

Example firewall rules

UFW (Debian/Ubuntu):

sudo ufw allow 5000:5002/tcp comment 'ProxmoxVEx UI + consoles'
sudo ufw allow 80/tcp comment 'ProxmoxVEx HTTP redirect'   # only when running as root, no proxy
sudo ufw allow 1514 comment 'ProxmoxVEx syslog'            # only with PROXMOXVEX_SYSLOG_BIND_ALL

firewalld (RHEL/Rocky/Alma/Fedora):

sudo firewall-cmd --permanent --add-port=5000-5002/tcp
sudo firewall-cmd --permanent --add-service=http                              # optional redirect
sudo firewall-cmd --permanent --add-port=1514/tcp --add-port=1514/udp         # optional syslog
sudo firewall-cmd --reload

Your hypervisor nodes must in turn allow inbound SSH (22) and the API ports above from the ProxmoxVEx host.

Choose an install method

The leading apt update && apt install -y curl bootstraps curl on minimal Debian/Ubuntu images that lack it — on RHEL-family use dnf install -y curl, on Arch pacman -Sy --noconfirm curl; if curl is already present you can go straight to curl -fsSL https://proxmoxvex.com/downloads/install.sh | sudo bash. On a terminal the installer opens a guided UI that reports prerequisites, offers any pending OS updates, and installs only what is missing; --no-interactive gives a plain unattended run.

The one-command installer accepts flags for unattended runs — e.g. curl -fsSL …/install.sh | sudo bash -s -- --port=443 --no-interactive (--no-firewall, --loopback-only, --no-offline, --no-tui are also available). To use an existing PostgreSQL instead of a local one, set PROXMOXVEX_DATABASE_URL before running it.

Docker, installer, and package installs can skip straight to first login. The rest of this page is the manual release-archive install.

Install from the release archive

1. Install system dependencies

Only the instructions matching the host OS selected above are shown. The packages cover the Python runtime, the PostgreSQL server, and the SSH helpers ProxmoxVEx uses for node-level operations.

sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv \
    postgresql postgresql-client \
    openssh-client sshpass sudo \
    curl wget git openssl ca-certificates

sudo -u postgres psql -c "CREATE USER proxmoxvex WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "CREATE DATABASE proxmoxvex OWNER proxmoxvex;"

sudo dnf install -y epel-release   # provides sshpass on RHEL-family
sudo dnf install -y python3 python3-pip \
    postgresql-server postgresql \
    openssh-clients sshpass sudo \
    curl wget git openssl ca-certificates

# First-time PostgreSQL setup on RHEL-family:
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

sudo -u postgres psql -c "CREATE USER proxmoxvex WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "CREATE DATABASE proxmoxvex OWNER proxmoxvex;"

sudo pacman -Syu --needed python python-pip \
    postgresql \
    openssh sshpass sudo \
    curl wget git ca-certificates

sudo -u postgres initdb -D /var/lib/postgres/data
sudo systemctl enable --now postgresql
sudo -u postgres psql -c "CREATE USER proxmoxvex WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "CREATE DATABASE proxmoxvex OWNER proxmoxvex;"

curl -fSL -o docker-compose.yml https://proxmoxvex.com/downloads/docker-compose.yml
docker compose up -d

2. Download ProxmoxVEx

Download the latest release archive from the Downloads page and extract it into its own directory — the archive has no top-level folder, and it already contains the prebuilt frontend bundle, so no build step is required:

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

3. Install Python dependencies

Create a virtual environment and install the requirements pinned in requirements.txt:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

This installs the full stack: Flask 3 + gevent (web/WSGI), psycopg2 (PostgreSQL), paramiko (SSH), pyvmomi (ESXi), XenAPI (XCP-ng), cryptography/argon2-cffi/fido2 (security), ldap3 + PyJWT (SSO), and scapy/scikit-learn/pandas (IDS).

4. Configure and start

Point ProxmoxVEx at PostgreSQL and start the server. The schema is created automatically on first launch — no manual migration step:

export PROXMOXVEX_DATABASE_URL=postgresql://proxmoxvex:changeme@localhost:5432/proxmoxvex
python3 ProxmoxVEx_multi_cluster.py

Alternatively, pip install . provides a proxmoxvex console command equivalent to python3 ProxmoxVEx_multi_cluster.py. Standard PGHOST/PGUSER/PGPASSWORD/PGDATABASE variables are honored if PROXMOXVEX_DATABASE_URL is unset.

If you did not install as root, the app serves HTTPS on port 5000 with a generated self-signed certificate. To serve plain HTTP behind a reverse proxy instead, add PROXMOXVEX_BEHIND_PROXY=true.

5. Run as a systemd service

For anything beyond a quick evaluation, run ProxmoxVEx under systemd so it starts automatically on boot and restarts on failure. (The install.sh installer and the .deb package already create this unit — this section is for manual installs from the release archive.)

Create a dedicated service user and hand it ownership of the install directory (adjust /opt/ProxmoxVEx to wherever you unpacked the release):

sudo useradd --system --no-create-home --shell /bin/false ProxmoxVEx
sudo chown -R ProxmoxVEx:ProxmoxVEx /opt/ProxmoxVEx

Store runtime configuration in a root-only environment file so the database password stays out of the unit:

sudo mkdir -p /etc/ProxmoxVEx
sudo tee /etc/ProxmoxVEx/ProxmoxVEx.env > /dev/null <<'EOF'
PROXMOXVEX_DATABASE_URL=postgresql://proxmoxvex:changeme@localhost:5432/proxmoxvex
# PROXMOXVEX_BEHIND_PROXY=true
# PROXMOXVEX_PORT=5000
EOF
sudo chmod 600 /etc/ProxmoxVEx/ProxmoxVEx.env

Create /etc/systemd/system/ProxmoxVEx.service:

[Unit]
Description=ProxmoxVEx - Proxmox Cluster Management
After=network.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=ProxmoxVEx
Group=ProxmoxVEx
WorkingDirectory=/opt/ProxmoxVEx
Environment=PATH=/opt/ProxmoxVEx/.venv/bin:/usr/local/bin:/usr/bin:/bin
EnvironmentFile=-/etc/ProxmoxVEx/ProxmoxVEx.env
ExecStart=/opt/ProxmoxVEx/.venv/bin/python /opt/ProxmoxVEx/ProxmoxVEx_multi_cluster.py
Restart=always
RestartSec=5

# Lets the service bind privileged ports (e.g. 443) without running as root
AmbientCapabilities=CAP_NET_BIND_SERVICE
PrivateTmp=true

StandardOutput=journal
StandardError=journal
SyslogIdentifier=ProxmoxVEx

[Install]
WantedBy=multi-user.target

Reload systemd, then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now ProxmoxVEx
sudo systemctl status ProxmoxVEx

• enable --now starts the service immediately and marks it to launch on every boot (WantedBy=multi-user.target).
• Restart=always with RestartSec=5 brings the app back automatically after a crash or reboot.
• After=postgresql.service ensures the database is up first when PostgreSQL runs on the same host — drop it if you use a remote database.
• Follow logs with sudo journalctl -u ProxmoxVEx -f; the app also writes to logs/ inside the install directory.

To change the port or other settings later, edit /etc/ProxmoxVEx/ProxmoxVEx.env and run sudo systemctl restart ProxmoxVEx.

First login

Open https://<server-ip>:5000 (http:// when PROXMOXVEX_BEHIND_PROXY=true). The first visit shows the setup wizard, where you create the administrator account. Two-factor setup (TOTP or WebAuthn/FIDO2) is available immediately after.

Connect a Proxmox VE cluster

After logging in, navigate to Clusters → Add Cluster and provide:

• Cluster name
• Proxmox VE host URL (e.g. https://pve.example.com:8006)
• API user (root@pam or a dedicated user such as proxmoxvex@pve)
• API token or password

ProxmoxVEx will validate the connection and begin streaming live metrics. Repeat for ESXi/vCenter or XCP-ng hosts to manage them side by side.

Next steps

• Browse the feature catalog.
• Review the architecture overview.
• Compare ProxmoxVEx with other platforms on the comparison page.
• Open a support request on the Support page.