PatchMox

PatchMox is a host-side Bash orchestrator for Proxmox VE that keeps Windows VMs up to date with the latest VirtIO drivers and QEMU Guest Agent releases.

It discovers Windows VMs automatically, queries installed versions via the QEMU Guest Agent, fetches the latest releases from the Fedora People Archive, and renders SVG update banners directly inside the Proxmox VE UI.

What works

• Automatic discovery of Windows VMs on the Proxmox cluster
• Installed VirtIO / QEMU Guest Agent version detection via QEMU Guest Agent
• Latest version lookup from the Fedora People Archive
• SVG update banners in the Proxmox UI
• Persistent per-VM state with vmgenid clone/restore detection
• Version fetch caching to avoid repeated network requests
• Filesystem-based job queue with patchmox worker
• Policy-driven decisions (default: notify-only)
• Inbound webhook support for clickable SVG banners

What is not ready

• In-VM auto-update execution is a stub; the worker calls a placeholder action
• Node-level concurrency for large clusters is planned

See PLAN.md for the full roadmap.

Quick start

git clone https://github.com/fs1n/PVE-QEMU-VirtIO-Updater.git /opt/patchmox
cd /opt/patchmox
cp .env.example .env
nano .env
chmod +x bin/patchmox install.sh
./install.sh
patchmox check

Documentation

• Installation
• Configuration
• Architecture
• CLI usage
• Development plan

Example

# Check all running Windows VMs
patchmox check

# Check a specific VM, bypassing the version cache
patchmox check --vmid 100 --force-refresh

# Process one pending auto-update job
patchmox worker --once

# Show stored state for a VM
patchmox state --vmid 100

Requirements

• Proxmox VE 8.0+
• Bash 4+
• jq, curl, pvesh, qm
• Windows guests with QEMU Guest Agent and VirtIO drivers installed

License

MIT — see LICENSE.