VirtDeck

A fast, native desktop client for Proxmox VE — monitor clusters and hosts, manage virtual machines and containers, browse Proxmox Backup Server backups. Everything in one window, no browser needed.

VirtDeck speaks directly to the PVE API (port 8006) and to PBS (port 8007), and adds what no competitor has: Fleet Health — a single report across all your independent clusters: backup compliance, version drift, storage runway and snapshot sprawl.

Website: virtdeck.mclure.ru

Highlights

Fleet Health (multi-cluster) — one report across all independent clusters: backup compliance, version drift, storage runway with a 95% confidence interval, snapshot sprawl; an offline cluster degrades to a "data from HH:MM" plate instead of an empty report
Full VM/CT lifecycle — create, clone, migrate, snapshots, bulk power actions with optimistic UI (instant apply, rollback on error)
PBS integration — direct Proxmox Backup Server connection: datastores, snapshots, sync/verify/prune jobs, restore into a new VM or container
Command palette (Ctrl+K) — fuzzy search over every action; the palette and the tree context menu are built from one declarative registry
Built-in noVNC console for QEMU VMs + SPICE support
Themes — Light, exact KDE Breeze / Breeze Dark (24px icons), Oxygen, Graphite, System; plugin API in docs/THEMES.md
Security by default — user-bound API tokens in the system keyring, encrypted config export/import, per-host SSL trust and HTTP(S) proxy
6 UI languages — English, Russian, Arabic, Chinese, French, Spanish

Full feature list →

Download

Platform	Format	Link
Windows	.zip / .exe installer	Releases
Debian / Ubuntu	package repository	Installation — `apt install virtdeck`
Fedora	package repository	Installation — `dnf install virtdeck`
Any	.tar.gz / .whl	Releases

Downloads are also listed on the website.

Latest release: v3.0.5

How VirtDeck compares

	Proxmox VE web GUI	Proxmox Datacenter Manager	VirtDeck
Where it runs	in a browser, per cluster	web, requires deploying and maintaining its own server/VM	a window on your desktop — no server to deploy, no extra VM to keep alive
Scope	one cluster per login	multi-cluster aggregation, live cross-cluster migration	multi-cluster tree, management, PBS, consoles — in one app
Extra value	full API coverage	enterprise: RBAC, LDAP/OIDC, SDN	Fleet Health across independent clusters, command palette, themes, offline "data from HH:MM" plates

VirtDeck is not a replacement for the PVE web GUI (it stays the source of truth for administration) and not a competitor to PDM's enterprise feature set. Its niche is different: launch an app and work with your whole fleet right now — nothing to install server-side, nothing to babysit. Details and the full competitive landscape: docs/COMPETITORS.md.

Changelog

See CHANGELOG.md for the full version history.

Requirements

Python 3.10+ (for source install; not needed for Windows .zip or installer)
PySide6 (full package, incl. WebEngine — for the built-in noVNC console)
proxmoxer (Debian 12+/Ubuntu 23.04+ have python3-proxmoxer; older — via pip)
requests / urllib3
pyqtgraph
keyring — system keyring access (KWallet / GNOME Keyring / Windows Credential Manager)
cryptography (export/import encrypted config bundle)
websockets — optional on Linux: required only for the built-in noVNC console (pip install websockets); the app runs fine without it. On Windows it is a hard dependency — Windows builds (zip/installer) bundle everything, no system Python needed.
Proxmox VE (cluster or standalone host)
API access to PVE host (port 8006)
Proxmox Backup Server (port 8007) — for direct PBS integration
virt-viewer (for SPICE/VNC console via remote-viewer)

Installation

Windows

Download virtdeck-windows.zip or virtdeck-*-setup.exe from GitHub Releases.

Portable: Extract .zip to any folder, run virtdeck.exe.

Installer: Run virtdeck-*-setup.exe — multilingual NSIS installer (English, Russian, Arabic, French, Spanish, Chinese). Creates Start Menu and Desktop shortcuts, registers uninstaller.

For SPICE console, install virt-viewer for Windows.

Package repository (Debian / Ubuntu / Fedora) — recommended

repo.mclure.ru hosts VirtDeck plus the packages the distro archives lack: full PySide6 (incl. WebEngine for the built-in console) and proxmoxer on Fedora. No pip steps needed.

Debian 12 (bookworm) / 13 (trixie) / Ubuntu 24.04 (noble) / Ubuntu 26.04 (resolute):

sudo install -d /etc/apt/keyrings
curl -fsSL https://repo.mclure.ru/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/virtdeck.gpg
echo "deb [signed-by=/etc/apt/keyrings/virtdeck.gpg] https://repo.mclure.ru/apt bookworm main" \
  | sudo tee /etc/apt/sources.list.d/virtdeck.list
sudo apt update
sudo apt install virtdeck

(Ubuntu 24.04 — replace bookworm with noble; Ubuntu 26.04 — with resolute; Debian 13 — with trixie.)

Fedora 43 / 44 ($releasever resolves to the running Fedora release):

sudo tee /etc/yum.repos.d/virtdeck.repo <<'EOF'
[virtdeck]
name=VirtDeck
baseurl=https://repo.mclure.ru/rpm/fedora/$releasever
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://repo.mclure.ru/KEY.gpg
EOF
sudo dnf install virtdeck

Verify the repository key fingerprint after downloading it. The key and the packages travel over the same domain — checking the fingerprint against this value (published separately in the README, on the website and at repo.mclure.ru) is what protects you if the domain is ever compromised:

117D EABD 3EA4 8810 B219 BA6B 401F 700F B97D E8B8

curl -fsSL https://repo.mclure.ru/KEY.gpg | gpg --show-keys
# expect: pub   rsa3072 ... [SC]  VirtDeck Repo <repo@mclure.ru>
#         117D EABD 3EA4 8810 B219 BA6B 401F 700F B97D E8B8

Machine check of the downloaded key — verifies it matches the value published here. Note this proves equality with the published value only: the published value itself is as trustworthy as the channel you received it through, so compare it against a second independent source (this site and repo.mclure.ru both carry it):

expected=117DEABD3EA48810B219BA6B401F700FB97DE8B8

actual=$(curl -fsSL https://repo.mclure.ru/KEY.gpg |
  gpg --show-keys --with-colons |
  awk -F: '$1 == "fpr" {print toupper($10); exit}')

if [ "$actual" = "$expected" ]; then
    echo "Fingerprint OK"
else
    echo "Fingerprint MISMATCH"
    exit 1
fi

Launch from the menu or via virtdeck.

From source (any Linux)

# download virtdeck-3.0.5-py3-none-any.whl (or the .tar.gz) from Releases,
# then install the package together with its dependencies:
pip install virtdeck-3.0.5-py3-none-any.whl PySide6 proxmoxer requests \
  urllib3 pyqtgraph cryptography keyring
virtdeck

(On a system with PEP 668 protection of the system Python, install into a virtual environment (venv); --break-system-packages bypasses that protection and should stay a conscious exception.)

Fedora releases older than 43 are end-of-life: the frozen fedora/41 catalog still serves its last published build but receives no updates — upgrade Fedora or use the From source route.

Linux system packages (system Python, no venv)

# Arch Linux
sudo pacman -S --needed pyside6 python-proxmoxer python-requests \
  python-urllib3 python-pyqtgraph python-keyring python-cryptography
# optional: built-in noVNC console + remote-viewer console
sudo pacman -S --needed python-websockets virt-viewer

# Debian / Ubuntu
sudo apt install python3-pyside6 python3-proxmoxer python3-requests \
  python3-urllib3 python3-pyqtgraph python3-keyring python3-cryptography
# optional
sudo apt install python3-websockets virt-viewer

# Fedora
sudo dnf install python3-pyside6 python3-proxmoxer python3-requests \
  python3-urllib3 python3-pyqtgraph python3-keyring python3-cryptography
# optional
sudo dnf install python3-websockets virt-viewer

Then run from the repo: ./run (or python -m virtdeck).

Isolated environment

git clone https://github.com/mcluremail/virtdeck.git
cd virtdeck
python -m venv venv
source venv/bin/activate
pip install PySide6 proxmoxer requests urllib3 pyqtgraph cryptography keyring
# optional: built-in noVNC console
pip install websockets

.deb package (Debian / Ubuntu)

The repository above is the primary install path. If you prefer a bare .deb from GitHub Releases, note that it depends on python3-pyside6, which only exists in our repository — add the repository first (see above), then:

# download .deb from release page
sudo apt install ./virtdeck_*.deb   # apt resolves the dependencies
# virt-viewer (if SPICE/VNC console via remote-viewer needed)
sudo apt install virt-viewer
# optional: built-in noVNC console
sudo apt install python3-websockets

After installing the .deb package, launch from the menu or via virtdeck.

Build from source (for custom versions):

sudo apt install devscripts debhelper dh-python python3-all python3-setuptools
cd virtdeck
dpkg-buildpackage -b
sudo dpkg -i ../virtdeck_*.deb

virt-viewer (for SPICE console)

# Debian / Ubuntu
sudo apt install virt-viewer

# Arch Linux
sudo pacman -S virt-viewer

# Fedora
sudo dnf install virt-viewer

# Windows
# Download from https://virt-manager.org/download/

# macOS
brew install virt-viewer

Usage

# Windows
# Portable: Extract .zip, run virtdeck.exe
# Installer: Run virtdeck-*-setup.exe

# If installed via .deb:
virtdeck

# From local repository:
./run
# or
python -m virtdeck

First run

Launch the application.
Click [+] in the tree panel toolbar.
In the dialog that opens, enter:
- Host address (FQDN or IP)
- User (e.g., root@pam)
- User password
The API token is created automatically and stored in the system keyring. The application connects to the host and starts monitoring.

For a cluster, adding a single node is sufficient — others are discovered dynamically via /cluster/resources.

Dependencies

Package	Purpose
PySide6	GUI framework (WebEngine — built-in noVNC console)
proxmoxer	Proxmox VE API client
requests	HTTP library
urllib3	TLS/session handling (imported directly)
pyqtgraph	Charts and plotting
cryptography	PBKDF2 + Fernet encryption (export/import bundle)
keyring	System keyring for token storage
websockets	Optional — built-in noVNC console WS bridge

For .deb package: python3-pyside6, python3-proxmoxer, python3-requests, python3-urllib3, python3-pyqtgraph, python3-cryptography, python3-keyring are available from Debian/Ubuntu repos. python3-websockets (noVNC console) and virt-viewer (remote-viewer console) are Recommends.

The application is designed to run on the system Python and system packages (no venv required): ./run uses plain python -m virtdeck.

Project structure

File	Purpose
`virtdeck/__main__.py`	Module entry (`python -m virtdeck`)
`virtdeck/main.py`	Application entry point
`virtdeck/backend/`	API client package: workers, `RefreshCoordinator` (hard/soft refresh), event bus seed, unified PVE error parsing
`virtdeck/backend/fleet.py`	Fleet Health API workers (per-cluster collection)
`virtdeck/pbs/`	Proxmox Backup Server API client (ticket auth) and workers
`virtdeck/plugins/_pbs.py`	PBS plugin (dispatch by `cfg["type"] = "pbs"`)
`virtdeck/domain/pbs.py`	PBS domain models (datastores, snapshots, jobs)
`virtdeck/domain/backup_coverage.py`	Backup compliance matching engine (vzdump job semantics, pure domain)
`virtdeck/fleet/`	Fleet Health collectors and analytics (drift, storage runway, snapshot sprawl)
`virtdeck/config.py`	Keyring, SQLite config storage, export/import
`virtdeck/ui/mainwindow.py`	Main window
`virtdeck/ui/tree_panel.py`	Tree panel for clusters, hosts, and VMs
`virtdeck/ui/detail_panel/`	VM/host detail panel (package)
`virtdeck/ui/add_server_dialog.py`	Add server dialog (with SSL trust toggle)
`virtdeck/ui/create_vm_dialog.py`	Create VM dialog
`virtdeck/ui/migrate_vm_dialog.py`	VM migration dialog
`virtdeck/ui/clone_vm_dialog.py`	VM cloning dialog
`virtdeck/ui/vm_config_editor_dialog.py`	VM config editor dialog
`virtdeck/ui/vm_device_editors.py`	Specialized device editors
`virtdeck/ui/vm_config_display.py`	VM config display widget
`virtdeck/ui/vm_actions.py`	VM power action labels and confirmation
`virtdeck/ui/pbs_panel.py`	PBS panel: datastores, snapshots, jobs
`virtdeck/ui/fleet_health.py`	Fleet Health report dialog (multi-cluster)
`virtdeck/ui/command_palette.py`	Command palette (Ctrl+K)
`virtdeck/ui/action_registry.py`	Declarative action registry — shared source for the palette and context menus
`virtdeck/ui/brand.py`	VirtDeck brand assets: toolbar lockup, app/tray icons
`virtdeck/ui/about_dialog.py`	About dialog
`virtdeck/ui/theme.py`	Color constants, fonts, QSS theme
`virtdeck/plugins/_themes.py`	Built-in theme plugins (Light, Breeze, Breeze Dark, Oxygen, Graphite, System)
`virtdeck/ui/icons.py`	SVG icon registry
`virtdeck/ui/notification.py`	Toast notifications
`virtdeck/ui/i18n/`	Translation module (tr()), JSON translation files
`virtdeck/ui/widgets/`	Widget modules (metrics, pool, tasks, hardware, options, card_list)
`virtdeck/ui/api/`	API workers (RRD data, storage content)
`tests/harness/`	Fake PVE/PBS API harness for UI tests (in-memory scenes)
`virtdeck/ui/console/`	Built-in noVNC console: window, WebSocket bridge (vendored noVNC assets)
`virtdeck/provider/`	Data provider seam: `ProxmoxProvider` facade, session with per-host proxy
`packaging/virtdeck-win.spec`	PyInstaller spec for Windows build
`packaging/virtdeck-installer.nsi`	NSIS multilingual installer script
`.github/workflows/ci.yml`	CI: ruff lint + pytest on PR/push (Python 3.10–3.14); release doc consistency checks
`.github/workflows/release.yml`	Release: build deb/rpm/zip/installer, create GitHub release
`docs/DEV_PROCESS.md`	Development methodology (workflow, gates, coding rules)
`docs/AUDIT_PROCESS.md`	Code audit methodology + audit reports

Language switching

The interface language is stored in the app config database (ui_state table, key language):

Linux: ~/.config/virtdeck/config.sqlite
Windows: %APPDATA%/virtdeck/config.sqlite
macOS: ~/Library/Application Support/virtdeck/config.sqlite

Supported languages:

English (en)
Russian (ru)
Arabic (ar)
Chinese Simplified (zh)
French (fr)
Spanish (es)

How translations work — the source of truth is the repo, not the database:

English strings are the reference: they are written in the UI code and wrapped in tr(); with English selected tr() returns them unchanged.
Every other language ships as a JSON file in virtdeck/ui/i18n/ (ru.json, ar.json, zh.json, fr.json, es.json) — a flat "msgid": "msgstr" map keyed by the English string. On set_language() the JSON is loaded into memory and tr() looks translations up there, falling back to English for missing keys. All JSON files must keep the same key set (scripts/check_release.py enforces this).
The SQLite translations table is a derived copy, not a source: set_language() seeds the active language's JSON into it (config.seed_translations()), and a re-seed is forced whenever the built-in strings change (the i18n_version counter in ui_state). Runtime translation lookup never reads the table.
To add or change a translation, edit the JSON file and bump _I18N_VERSION in virtdeck/ui/i18n/__init__.py so existing installs re-seed. No manual database editing is required — rows inserted into translations alone have no effect at runtime.
To add a new language: add virtdeck/ui/i18n/<lang>.json and register it in _SUPPORTED_LANGUAGES and _JSON_LANGS in virtdeck/ui/i18n/__init__.py (plus the README list above).

Third-party software

This project bundles noVNC (vendored, MPL-2.0, unmodified — see virtdeck/ui/console/novnc/LICENSE.txt) and uses several third-party Python packages (PySide6/LGPL-3.0, proxmoxer/MIT, requests/Apache-2.0, etc.). Full list with licenses and sources: docs/THIRD-PARTY-NOTICES.md.

License

GNU General Public License v3.0. See LICENSE file.

VirtDeck is an unofficial third-party client. It is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH or KDE e.V. See docs/THIRD-PARTY-NOTICES.md.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
Screenshots		Screenshots
debian		debian
docs		docs
packaging		packaging
scripts		scripts
tests		tests
virtdeck		virtdeck
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
FEATURES_BACKLOG.md		FEATURES_BACKLOG.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
VISION.md		VISION.md
pyproject.toml		pyproject.toml
ruff.toml		ruff.toml
run		run
setup.py		setup.py
uv.lock		uv.lock
virtdeck.spec		virtdeck.spec

Navigation Menu

Repository navigation

About

Repository files navigation

VirtDeck

Highlights

Download

How VirtDeck compares

Changelog

Requirements

Installation

Windows

Package repository (Debian / Ubuntu / Fedora) — recommended

From source (any Linux)

Linux system packages (system Python, no venv)

Isolated environment

.deb package (Debian / Ubuntu)

virt-viewer (for SPICE console)

Usage

First run

Dependencies

Project structure

Language switching

Third-party software

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

VirtDeck

Highlights

Download

How VirtDeck compares

Changelog

Requirements

Installation

Windows

Package repository (Debian / Ubuntu / Fedora) — recommended

From source (any Linux)

Linux system packages (system Python, no venv)

Isolated environment

.deb package (Debian / Ubuntu)

virt-viewer (for SPICE console)

Usage

First run

Dependencies

Project structure

Language switching

Third-party software

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages