PVEmanager

Modern web panel for managing Proxmox servers, virtual machines and LXC containers

---

Overview

PVEmanager is a self-hosted web panel that provides a unified interface for managing multiple Proxmox VE servers and clusters. It covers the full VM/LXC lifecycle — from provisioning to monitoring — with role-based access control, notifications, and IP address management.

Features

Infrastructure

• Multi-server management — connect and manage multiple Proxmox servers and clusters from a single panel
• VM & LXC lifecycle — create, start, stop, restart, resize, delete virtual machines and containers
• Bulk operations — mass start / stop / restart / delete with queue and progress tracking
• Snapshot management — create, rollback, delete snapshots with an async queue system
• OS templates — deploy VMs from templates; cross-node replication handled automatically
• Cloud image catalog — browse, download, and convert OS images from cloud repositories (default Proxmox mirrors and custom sources); auto-convert to VM templates with architecture-aware filtering
• ISO eject/mount — attach or eject an ISO on a running VM, with a boot-order switch (boot from disk or from the ISO) applied via a graceful ACPI-then-forceStop hybrid reboot
• CT template deployment — create LXC containers directly from Proxmox CT template files (.tar.zst, .tar.gz) with full IPAM and SSH key integration
• Unified Create Instance Wizard — multi-step wizard supporting both QEMU VM templates and LXC CT templates in a single flow
• SDN support — manage Software-Defined Networking zones, VNets, and subnets; edit zones and VNets; auto-create IPAM networks for subnets
• Node networking — manage node-level network interfaces (bridges, bonds, VLANs); apply/revert pending config
• Networks page — unified UI for SDN and node interface management
• Several IP addresses per instance — a guest can hold a primary address plus extra ones, managed from its Network tab; extras are applied inside the guest as aliases (pct exec for LXC, guest agent for VMs) and survive a reboot

App Store

• Self-hosted app catalog — one-click install of self-hosted apps, each into its own unprivileged LXC running Docker Compose (1 app = 1 LXC); multi-source catalog — runtipi/runtipi-appstore (~265 apps) plus optional getumbrel/umbrel-apps (~380 apps), selectable via APPSTORE_SOURCES
• Install wizard — dynamic app parameters (form fields), advanced LXC resources, auto-generated secrets, live install progress over WebSocket, and one-time credential display
• My Apps lifecycle — start / stop / restart / logs / delete, with background reconciliation (orphan detection) and per-app status
• Update & Rollback — snapshot-backed updates (docker compose pull) with health-check and one-click rollback to the pre-update snapshot
• Global operations tray — minimize a running install or golden-template build into a global tray that survives page navigation and tab reload; click a chip to resume the dialog where you left off
• Secure by design — unprivileged LXC only, Fernet-encrypted secrets, injection-safe pct exec/pct push, RBAC app:view / app:install / app:manage

Access & Console

• VNC console — in-browser console via noVNC, no client software required
• xterm.js terminal — full interactive shell directly in the browser for LXC containers
• Remote commands — execute bash commands via QEMU Guest Agent
• SSH Keys Management — personal SSH key library per user; keys selectable when deploying VMs/LXC; admin can manage keys for any user
• RBAC v2 — granular role-based access control with per-resource permissions; routes are guarded server- and client-side, not just hidden from the sidebar
• Permission-free profile page — account settings (profile, password, 2FA, SSH keys) live at /profile and never require a panel-settings permission, so restricting setting:view can't lock a user out of their own account
• Server assignment — directly assign specific Proxmox servers to users with workspace-conflict validation
• VM/LXC ownership — assign an owner user to any VM or LXC container; non-privileged users see only their own instances everywhere, including the dashboard and per-node resource views; owner is set automatically on create, with a migration to backfill pre-existing instances
• Per-user quotas — limit each user's number of instances and total vCPU, RAM and disk; enforced at deploy time (HTTP 429); the Create Instance entry point itself is disabled once a quota has no headroom left, naming which limit is full
• Session management — active session list, remote session revocation, login protection
• Smart login redirect — users are automatically routed to the first page they have access to

Monitoring & Alerts

• Real-time metrics — CPU, RAM, Disk, Network charts per node and per VM; live per-disk fill, IOPS and network I/O rates (bytes/sec) on the instance Overview tab and instances list
• Background sync — automatic VM state synchronization from Proxmox API (status/current at 1 s granularity for running VMs)
• Notifications — In-App (bell icon), Email (SMTP), Telegram (Bot API)
• Audit log — full action log with user, timestamp, and details

Other

• Command palette — Ctrl+K palette with search over a unified navigation registry for keyboard-driven jumps to any page
• IPAM — IP Address Management with allocation history, orphan detection and several addresses per instance
• Multilingual — Russian and English interface; language preference is per-user account
• Encrypted credentials — sensitive fields stored encrypted in the database
• Styled confirmation dialogs — all destructive actions use a consistent themed modal instead of the native browser confirm()

---

Quick Start

# 1. Clone
git clone https://git.tzim.uz/markmorado/pvemanager.git
cd pvemanager

# 2. Configure
cp .env.example .env
cp backend/.env.example backend/.env
# Edit .env — set POSTGRES_PASSWORD and TZ

# 3. Start
docker compose up -d

# 4. Open
# http://localhost:3001
# Default login: admin / admin123

Important: Change the default password immediately after first login.

One-command bootstrap

bootstrap.sh installs the panel with a single command, on either a plain Debian/Ubuntu host or directly on a Proxmox VE host — on a PVE host it provisions a Debian 12 LXC, installs the panel inside it, and registers that host as the panel's first node automatically (no Proxmox password is ever transmitted):

git clone https://git.tzim.uz/markmorado/pvemanager.git
cd pvemanager
bash bootstrap.sh

---

Requirements

Requirement	Minimum
Docker	24.x+
Docker Compose	v2.x+
RAM	512 MB (app) + 256 MB (DB)
Proxmox VE	7.x / 8.x / 9.x

---

Configuration

Environment variables (.env)

# Database
POSTGRES_PASSWORD=your_secure_password

# Timezone (IANA format)
TZ=Europe/Moscow

# Update checks (for private repos — disable or provide a token)
DISABLE_UPDATE_CHECK=false
GITHUB_TOKEN=                     # optional, for private repo update checks

Notifications

Configured via the web interface — Settings → Notifications:

• Email — SMTP server, port, login, password (Yandex, Gmail, Mail.ru and others)
• Telegram — Bot token and Chat ID via @BotFather

---

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI, SQLAlchemy
Frontend	React 19, TypeScript, Vite 8
UI Components	shadcn/ui, Tailwind CSS v4, lucide-react
State & Data	TanStack Query v5, Zustand, React Router v7
Database	PostgreSQL 16
Containerization	Docker, Alpine Linux
Proxmox API	proxmoxer
VNC	noVNC
Charts	Recharts
Terminal	xterm.js
i18n	i18next, react-i18next

---

Documentation

Document	Description
WIKI.md	Full user and administrator guide
CHANGELOG.md	Version history and release notes
CONTRIBUTING.md	How to contribute — setup, code style, PR process
SECURITY.md	Security policy and vulnerability reporting

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions, code style, commit conventions, and the PR process.

---

License

MIT — free to use, modify, and distribute.

---

Made with ❤️ for Proxmox users

Issues · Changelog · Wiki · Contributing · Security