Running a Proxmox VE cluster is fantastic for virtualization — until patch day arrives. Then it becomes a repetitive routine: migrate VMs, update packages, reboot nodes, wait for quorum, and repeat for every server.

On clusters with more than a handful of nodes, this process is not only time-consuming, it is also easy to get wrong. A missed migration or poorly timed reboot can cause downtime.

ProxPatch (official website proxpatch.de) is a lightweight rolling update orchestrator for Proxmox VE. It keeps clusters up-to-date with zero-touch execution, predictable behavior, and no service interruption.

ProxPatch Logo for Proxmox VE Clusters
ProxPatch Logo for Proxmox VE Clusters

Think of it as: “apt upgrade for your entire cluster — just safely orchestrated and taking care about Ceph and ProxLB!

The Problem with Cluster Updates

Proxmox VE itself is extremely stable and powerful, but patch orchestration across multiple nodes is still largely manual. Administrators typically rely on SSH sessions, custom scripts, or external automation.

Common pain points include:

  • Repeating the same maintenance workflow on every node
  • No built-in rolling update orchestration
  • Manual VM migration coordination
  • Risk of quorum loss or downtime
  • Difficult to automate safely

While building ProxLB (a DRS-like load balancer for Proxmox), it became obvious that the ecosystem was missing a simple, reliable way to patch entire clusters safely.

ProxPatch was created to fill that gap.

What ProxPatch Does

ProxPatch automates the full maintenance lifecycle of a Proxmox cluster. It performs rolling updates node by node while keeping workloads online.

The design philosophy is simple: Do one thing — and do it safely.

There is no heavy orchestration stack, no agents, and no complex dependencies. It uses native Proxmox tooling and predictable logic.

Rolling Update Workflow

Every ProxPatch run follows a deterministic and auditable workflow:

  1. Cluster discovery – Detect nodes, roles, and workloads
  2. Health validation – Ensure quorum and cluster stability
  3. Update detection – Check for pending package upgrades
  4. Workload evacuation – Live-migrate VMs and CTs
  5. Node patching – Apply updates via APT
  6. Reboot logic – Reboot only if required
  7. Node recovery – Wait until the node is fully healthy
  8. Continue – Move to the next node

At no point are all nodes updated simultaneously. Availability is preserved throughout the process.

Key Features

  • Zero-downtime rolling updates for Proxmox VE clusters
  • Automatic VM & container migration before maintenance
  • Cluster quorum protection
  • Smart reboot detection (kernel/critical updates only)
  • No external dependencies or heavy frameworks
  • Transparent logging and predictable behavior
  • Works with existing clusters without reconfiguration
  • CLI and service mode for automation
  • Homelab to enterprise ready

Designed for Safety

ProxPatch is intentionally conservative. If anything looks unsafe, it stops immediately.

Execution will abort if:

  • Cluster quorum could be lost
  • A node is degraded or offline
  • VM migration cannot be performed safely
  • A previous update step failed

This makes behavior predictable and easy to audit. There is no hidden automation or risky assumptions.

Integration with Proxmox

ProxPatch uses native Proxmox tooling and standard Linux utilities:

  • pvesh for cluster state
  • qm and pct for workload handling
  • ssh for orchestration
  • apt for updates
  • systemd for service execution

This keeps the stack simple and reduces operational risk. No custom agents are required on every node.

Automation & Scheduling

ProxPatch can run:

  • Manually via CLI
  • As a systemd service
  • On a schedule (e.g. nightly or weekly)
  • During maintenance windows

This makes it suitable for both homelabs and production environments.

Installation

ProxPatch can easily be installed via the Debian repository, or by downloading the .deb package.

Important: Install ProxPatch only on one node in the cluster!


# Add repository
curl https://git.gyptazy.com/api/packages/gyptazy/debian/repository.key -o /etc/apt/keyrings/gyptazy.asc
 
echo "deb [signed-by=/etc/apt/keyrings/gyptazy.asc] \
 https://packages.gyptazy.com/api/packages/gyptazy/debian \
 trixie main" | sudo tee -a \
 /etc/apt/sources.list.d/gyptazy.list

# Install
sudo apt update && sudo apt install proxpatch

# Start service
sudo systemctl start proxpatch

Run manually:

proxpatch

From that point on, ProxPatch will orchestrate safe rolling updates across the cluster.

Typical Use Cases

  • Weekly automated cluster patching
  • Enterprise maintenance windows
  • Homelab automation
  • Multi-node Proxmox deployments
  • Zero-downtime infrastructure updates
  • CI/CD for infrastructure

Roadmap

Planned and upcoming improvements:

  • Notification hooks (Slack, Mail, Webhook)
  • Maintenance window configuration
  • Advanced scheduling
  • Integration with Ceph
  • Metrics export (Prometheus)
  • Dry-run simulation mode

Open Source

ProxPatch is open-source and built with reliability and transparency in mind. Contributions, testing, and feedback are always welcome.

Final Thoughts

Cluster patching should not be stressful or manual. It should be predictable, safe, and automated. Howerver, this project is still in an early stage, and there are many improvements planned. It is provided as-is and may contain bugs, incomplete features, or unexpected behavior. Do not use this software in production environments without thorough testing. You are strongly advised to evaluate and validate all functionality in isolated test labs or staging environments before deploying it anywhere else. The authors and contributors accept no responsibility or liability for any data loss, downtime, damage, or other issues that may arise from the use or misuse of this project. By using this software, you acknowledge that you do so entirely at your own risk.

ProxPatch turns cluster maintenance into a single command.

If you run Proxmox VE and want safer updates without downtime, give it a try and share feedback.