Skip to content
greenloglesPublic

About

A modern web-based management interface for Proxmox VE with multi-cluster support and focus on desktop and mobile experience.

Topics

Resources

Stars

78 stars

Watchers

1 watching

Forks

Latest commit

 

History

249 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ProxUI

A modern web-based management interface for Proxmox VE with multi-cluster support and focus on desktop and mobile experience.

Features

ProxUI isn't a replacement for Proxmox web interface, but a light-weight addition to represent available information in more user friendy way as well as filling some gaps. It has essential functionality to manage single instance(s) or cluster(s).

Virtual Machine Management

  • Represents VM and container status and performance metrics in more readable way
  • Live VM status and resource metrics polling on the detail page
  • Creation VMs and containers from templates
  • Cloud VM Templates: Create VM templates from popular cloud images (Ubuntu, Debian, Rocky, Alma, Fedora) with cloud-init support
  • Cloud-init editing: Native cloud-init settings plus custom snippets written to nodes over SSH, with a storage picker and migration warnings
  • Built-in configuration editor
  • QEMU Guest Agent: disk usage monitoring plus an opt-in per-VM toggle (off by default for new VMs)
  • Reset the guest root password from the Edit page
  • Consolidated configuration single-page view incluing cloud-init params (like ssh keys)
  • Background job queue for long-running operations with real-time progress tracking

LXC / Container Advanced Configuration

  • Container feature flags (nesting, keyctl, fuse, mount) with a safety layer
  • Device passthrough and bind mounts
  • Unprivileged container idmap editor
  • Reusable LXC configuration profiles

Storage Management

  • Unified storage view across all cluster nodes
  • Group shared media
  • Real-time storage usage monitoring

System Monitoring

  • Dashboard with cluster overview and statistics
  • Unified task list (see Tasks and background jobs)
  • Network configuration viewing
  • Real-time basic resource usage charts

Tasks and background jobs

The Tasks page, the dashboard and the Activity menu in the top bar show two kinds of entries in one list:

  • Proxmox tasks: native tasks from the cluster task log (start, migrate, backup, ...), including ones started outside ProxUI. Running migrations, clones, disk moves, backups and restores show progress parsed from the task log.
  • ProxUI jobs: multi-step workflows run by ProxUI itself, such as cloud template creation or cloning. The Proxmox tasks a job starts are grouped under it instead of being listed separately.

Every entry opens a detail page with the full Proxmox task log, or with the job's steps and the logs of its Proxmox tasks.

ProxUI jobs, and with them the grouping, are kept in memory only. After ProxUI restarts, past jobs are gone and the Proxmox tasks they started appear as ordinary, ungrouped tasks.

Multi-Cluster Management

  • Connect and manage multiple Proxmox clusters or individual servers from a single interface
  • Easy cluster switching with persistent user preferences
  • Cluster connection management and status monitoring

User Experience

  • Focus on desktop and mobile devices
  • Light and dark mode with saved browser preference

Screencast

ProxUI screen cast

Demo

Demo instance with read-only access is available at https://demo.proxui.app

Quick Start

Using Docker Compose (Recommended)

  1. Download docker-compose.yml file:
wget -O docker-compose.yml https://raw.githubusercontent.com/greenlogles/ProxUI/refs/heads/main/docker-compose.yml
  1. Start the application:
docker-compose up -d
  1. Access the web interface at http://localhost:8080

  2. Configure your first Proxmox cluster through the connect page

Manual Installation

  1. Install dependencies:
pip install -r requirements.txt
  1. Run the application:
python app.py
  1. Access the web interface at http://localhost:8080

Configuration

The application stores configuration in /app/data/config.toml (or ./data/config.toml in development). The configuration file supports multiple clusters:

# Password authentication
[[clusters]]
id = "homelab"
name = "Home Lab"
[[clusters.nodes]]
host = "192.168.1.100:8006"
user = "root@pam"
password = "your-password"
verify_ssl = false

# API Token authentication (recommended for production)
[[clusters]]
id = "production"
name = "Production Cluster"
[[clusters.nodes]]
host = "pve.example.com"
user = "root@pam"
token_name = "proxui"
token_value = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
verify_ssl = true

Authentication Methods

ProxUI supports two authentication methods:

  1. Password Authentication: Traditional username/password login. Simple but less secure for production.

  2. API Token Authentication (Recommended): Uses Proxmox API tokens for authentication. To create a token:

    • Go to Datacenter → Permissions → API Tokens in Proxmox
    • Click "Add" and select a user (e.g., root@pam)
    • Enter a token ID (e.g., proxui)
    • Optionally uncheck "Privilege Separation" for full user permissions
    • Copy the token secret (shown only once!)

Configuration file can be managed manually or through the web UI (Cluster Management page).

Environment Variables

Variable Description Default
CONFIG_FILE_PATH Path to the main configuration file ./data/config.toml
CLOUD_IMAGES_PATH Path to custom cloud images JSON file ./cloud_images.json
CLOUD_IMAGE_CACHE How to handle existing cloud images: REUSE (skip download if exists) or OVERWRITE (delete and re-download) REUSE
PROXUI_SECRET_KEY Secret key used to sign Flask sessions and CSRF tokens. Set this to a long random value for deployments. Temporary random key per process
PROXUI_AUTH_USERNAME Optional HTTP Basic Auth username for protecting the whole UI. Requires PROXUI_AUTH_PASSWORD. Disabled
PROXUI_AUTH_PASSWORD Optional HTTP Basic Auth password for protecting the whole UI. Requires PROXUI_AUTH_USERNAME. Disabled
PROXUI_SESSION_COOKIE_SECURE Set to true when serving ProxUI over HTTPS so browsers only send session cookies over TLS. false
PROXUI_DEBUG Enables Flask debug mode when set to true. Do not enable in production. false
PROXUI_HOST Host interface for the built-in Flask server. 0.0.0.0
PROXUI_PORT Port for the built-in Flask server. 8080

Custom Cloud Images

ProxUI includes a default list of popular cloud images (Ubuntu, Debian, Rocky Linux, AlmaLinux, Fedora). You can customize this list by:

  1. Create your own cloud_images.json file:
{
    "my-custom-image": {
        "name": "My Custom Linux",
        "url": "https://example.com/my-image.qcow2",
        "os_type": "l26",
        "description": "My custom cloud image"
    }
}
  1. Mount it and set the environment variable:
docker run -d \
  -e CLOUD_IMAGES_PATH=/config/my-images.json \
  -v ./my-images.json:/config/my-images.json \
  ghcr.io/greenlogles/proxui:latest

Custom User creation

If you are willing to use ProxUI with read-only user, create new one by running next command on one of the ProxMox servers:

# Create new user
pveum user add proxui-readonly@pve --password yourpassword --comment "ProxUI read-only user"

# Assign built-in PVEAuditor role to root path with propagation
pveum acl modify / --users proxui-readonly@pve --roles PVEAuditor --propagate 1

Docker Deployment

The application is designed for Docker deployment with persistent volume mounting. Docker images are automatically built and published via CI/CD pipeline.

Available Image Tags

  • ghcr.io/greenlogles/proxui:latest - Latest stable release (recommended for production)
  • ghcr.io/greenlogles/proxui:testing - Latest development build from main branch
  • ghcr.io/greenlogles/proxui:v1.2.3 - Specific version tags for releases

Docker Compose (Recommended)

version: '3.8'
services:
  proxui:
    image: ghcr.io/greenlogles/proxui:latest  # or :testing for latest development
    container_name: proxui
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      # Optional: mount custom cloud images config
      # - ./my-cloud-images.json:/config/cloud-images.json
    environment:
      - CONFIG_FILE_PATH=/app/data/config.toml
      # Optional: use custom cloud images
      # - CLOUD_IMAGES_PATH=/config/cloud-images.json
    restart: unless-stopped

Docker Run

# Latest stable release
docker run -d \
  --name proxui \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e CONFIG_FILE_PATH=/app/data/config.toml \
  ghcr.io/greenlogles/proxui:latest

# Latest development build
docker run -d \
  --name proxui \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e CONFIG_FILE_PATH=/app/data/config.toml \
  ghcr.io/greenlogles/proxui:testing

CI/CD and Automated Builds

ProxUI uses GitHub Actions for automated testing and Docker image building with GitHub Container Registry:

  • Testing Images: Built automatically on every push to main branch (:testing tag)
  • Release Images: Built automatically when GitHub releases are created (:latest + version tags)
  • Multi-platform: Images support both linux/amd64 and linux/arm64
  • No Setup Required: Uses built-in GitHub authentication and permissions

Images are published to GitHub Container Registry at ghcr.io/greenlogles/proxui.

Requirements

  • Python 3.7+
  • Flask 2.3.3
  • proxmoxer 2.0.1
  • Access to Proxmox VE cluster(s)

Security Notes

  • Configuration files contain sensitive credentials
  • Set PROXUI_SECRET_KEY to a stable random value before exposing the app
  • Set PROXUI_AUTH_USERNAME and PROXUI_AUTH_PASSWORD, or place ProxUI behind another authenticated reverse proxy
  • Use strong passwords and consider API tokens instead of root passwords
  • SSL certificate verification can be disabled for self-signed certificates
  • Ensure proper network security when exposing the web interface
  • URL-based template and ISO downloads only accept http:// and https:// URLs with simple filenames

Support

If you have any questions, need assistance, please open issue or discussion here on GitHub.

Author(s)

Alex Shut @greenlogles (https://github.com/greenlogles/ProxUI)

About

A modern web-based management interface for Proxmox VE with multi-cluster support and focus on desktop and mobile experience.

Topics

Resources

Stars

78 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages