Sooner or later, if you stick with Proxmox long enough, you'll pick up a second machine — maybe an old desktop, maybe a dedicated mini PC — and the word "cluster" starts showing up everywhere in the docs and forums. It sounds like something only big data centers need. It isn't, but it also isn't something you should turn on just because the button exists.
Let's actually define what a Proxmox cluster is, what it buys you, and — just as important — when you genuinely don't need one. Plenty of forum threads treat clustering as a rite of passage, something every "serious" homelab eventually does. It's not. It's a tool for a specific problem, and it comes with its own maintenance overhead once it's running.
What You Will Learn
You'll come away understanding what a Proxmox cluster actually does under the hood, what Corosync and quorum mean and why they matter more than people expect, and the real network and hardware requirements before you commit to building one. We'll also walk through creating a basic cluster so the concept isn't just theory, and cover what tends to go wrong for people setting one up for the first time.
What Is This Feature?
A Proxmox cluster is a group of Proxmox VE nodes — separate physical or virtual machines each running their own copy of Proxmox — joined together so they can be managed as a single unit instead of as separate islands. Once joined, every node shares the same configuration database and shows up in the same web interface, so you can manage VMs on any node from a single login.
The mechanism that makes this work is called Corosync. It's the communication layer running constantly in the background on every node, keeping each one's copy of the cluster configuration in sync and handling something called quorum.
Quorum is the voting system that decides whether the cluster is allowed to make changes. Every node gets one vote, and the cluster needs more than half of all votes present and reachable to stay "quorate" — able to safely accept configuration changes. This exists to prevent a nasty scenario called split-brain, where a network hiccup splits your cluster into two halves that both think they're in charge and start making conflicting changes at the same time.
Here's the part that surprises people: in a 2-node cluster, losing either node means you've lost quorum, because one node is exactly 50%, not a majority. The cluster doesn't fail catastrophically, but it drops into a read-only-ish state where you can't make configuration changes until quorum is restored. This is exactly why Proxmox recommends at least three nodes, or a QDevice (a lightweight external vote-only participant) if you're stuck at two.
Why Would You Use It?
Clustering unlocks a few specific things that don't exist on a standalone node:
- Centralized management. One web UI, one login, every node and every VM visible in the same place instead of juggling multiple browser tabs.
- Live migration. Move a running VM from one physical machine to another with essentially no downtime — useful for hardware maintenance, or just rebalancing load.
- High Availability (HA). If a node dies unexpectedly, HA-enabled VMs can automatically restart on a surviving node. This requires both a cluster and shared storage that every node can reach — local-only disks won't cut it.
Here's a quick comparison of what changes:
| Capability | Standalone node | Clustered nodes |
|---|---|---|
| VM backups and snapshots | Fully supported | Fully supported |
| Single web UI for all machines | Not applicable | Yes |
| Live migration between hosts | Not possible | Yes |
| Automatic VM failover (HA) | Not possible | Yes, with shared storage |
Now the honest part: if you're running a single Proxmox box in a closet, none of this applies to you. Backups, snapshots, and VM management all work perfectly fine on a lone node — you don't need a cluster to get any of that. Clustering only starts paying off once you actually have two or more physical machines and want to manage or protect workloads across them. I'd genuinely discourage setting one up on a single node "just in case" — there's no benefit, and un-clustering later is more of a hassle than clustering in the first place.
Prerequisites
- Two or more machines already running Proxmox VE, on the same reliable local network — Proxmox recommends latency under 5 milliseconds between nodes, which basically means "same LAN," not "over the internet."
- Each node with a unique hostname and static IP address.
- Time synchronized across all nodes (Proxmox handles this automatically via
chronyin most modern installs, but it's worth confirming). - Root access to each node, and network connectivity between them on TCP port 22 (SSH) and the Corosync UDP ports 5405 through 5412.
Step-by-Step Tutorial
Step 1: Create the cluster on your first node
Pick one node to be the starting point — it doesn't become a permanent "master" of any kind, this is just where you initialize things. From its shell:
pvecm create homelab-clusterReplace homelab-cluster with whatever name you want — it's just a label, pick something meaningful to you.
Step 2: Check that it initialized correctly
pvecm statusYou should see your single node listed with 1 vote out of 1 expected, and "Quorate: Yes." That's your one-node cluster, technically complete but not useful yet on its own.
Step 3: Join additional nodes
On your second (and any further) node, run:
pvecm add 192.168.1.10Replace the IP with the address of the first node you created the cluster on. You'll be prompted for that node's root password to authenticate the join. This process copies the cluster configuration onto the new node and restarts the relevant services automatically.
Step 4: Confirm every node sees the same cluster
From any node, run:
pvecm nodesEvery node you've joined should be listed here, and this list should look identical no matter which node you run the command from. If one node shows different results than the others, something didn't sync properly.
Log into the web UI on any node and you should now see every node listed in the left panel, with all of their VMs and containers visible from that single session. Repeat Step 3 for any remaining nodes you want in the cluster — each one only needs to point at the original node's IP once to join.
Commands Explained
| Command | What it does |
|---|---|
pvecm create <name> | Initializes a brand new cluster on the current node, using the given name as the cluster's identifier. |
pvecm add <ip> | Joins the current node to an existing cluster, using the IP address of an already-clustered node as the entry point. |
pvecm status | Shows the current node's view of cluster health — quorum status, vote counts, and which nodes are currently reachable. |
pvecm nodes | Lists every node that's a member of the cluster, regardless of whether it's currently online. |
Common Errors
- "Cluster not ready - no quorum?" — appears when you try to make a configuration change but not enough nodes are currently reachable. Check that all expected nodes are powered on and network-reachable.
- Node join hangs or times out — almost always a network problem: a firewall blocking the Corosync UDP ports, or the nodes simply can't reach each other on the LAN.
- "Authentication failure" during pvecm add — double-check you're using the target node's actual root password, not your own node's, and that the IP address you're joining to is correct.
- Cluster works fine until one node reboots, then locks up — a classic 2-node symptom. With only two votes total, losing one node during a reboot temporarily drops you below quorum. This resolves itself once the node comes back, but it's a strong signal you should add a third node or a QDevice.
Troubleshooting
If quorum keeps flapping in and out even though all your nodes appear to be up, check the network link between them first — Corosync is sensitive to latency and packet loss in a way normal VM traffic isn't. A network switch that's fine for everyday use can still cause quorum instability if it's dropping the small, frequent Corosync packets.
Run pvecm status on each node individually rather than trusting the web UI alone — if the nodes disagree with each other about who's quorate, that's a genuine split in communication, not a display glitch.
It's also worth checking basic connectivity directly before blaming Corosync itself. A simple ping between nodes rules out a dead network cable or a misconfigured VLAN, both of which look identical to a Corosync problem from inside the Proxmox UI but have nothing to do with clustering at all.
If you're stuck at exactly two nodes and don't have a third machine available, look into setting up a QDevice on a small, separate machine — even a Raspberry Pi can run one. It only casts a tie-breaking vote; it doesn't need to run any VMs itself.
Best Practices
- Don't cluster a single node "for the future." There's no benefit until you actually have a second machine, and it adds complexity for nothing.
- Stick to an odd number of nodes where practical (3, 5, and so on) — it makes quorum math cleaner and avoids the exact tie scenarios that cause the most confusion.
- Keep cluster nodes on the same reliable local network. Stretching a cluster across sites over a VPN is possible but fights against the latency requirements constantly, and I wouldn't recommend it for a first attempt.
- If you're planning to use High Availability, set up shared storage — NFS, Ceph, or similar — before you need it. HA can't fail a VM over to another node if that VM's disk only exists on the original node's local drive.
- Give each node a little headroom in CPU and RAM rather than running everything at 95% capacity. If a node fails and HA moves its VMs elsewhere, the surviving nodes need enough spare capacity to actually absorb that load.
- Test what happens when you power off one node on purpose, before you actually need the cluster to survive a real failure. It's much better to learn quorum behavior on a Tuesday afternoon than during an actual outage.
Frequently Asked Questions
Do I need a cluster to take backups or snapshots?
No. Both work perfectly fine on a single standalone Proxmox node. Clustering is about managing and protecting workloads across multiple physical machines, not a requirement for basic VM management.
Can I run a cluster with just two nodes?
Yes, but be aware that losing either node drops you out of quorum. Adding a QDevice on a third, lightweight machine fixes this without needing a full third Proxmox node.
Does clustering slow down my VMs?
No. Corosync traffic is small and separate from your VM traffic. The cluster layer itself has no meaningful performance impact on running workloads.
Can I add a node running a different Proxmox version to my cluster?
It's best avoided. Mixing major versions across a cluster can cause compatibility issues — keep all nodes on the same Proxmox VE version, especially during the join process.
Is it hard to remove a node from a cluster later?
It's more involved than joining one — you need to properly remove it with pvecm delnode and clean up its local cluster configuration afterward. It's not risky if done correctly, but it's not a single command either, so it's worth planning your cluster layout before you build it rather than after.
Conclusion
A Proxmox cluster is really just several nodes agreeing to share one configuration and one management view, held together by Corosync's voting system. The value is real once you have multiple machines — centralized management, live migration, and the option of High Availability — but none of it matters on a single box.
If you're down to one Proxmox node right now, there's no rush. Get comfortable with VMs, containers, and backups first, and revisit clustering the day you actually bring home that second machine. It'll make a lot more sense once you've got a second box sitting right next to the first one, and the whole idea of "one login, two machines" stops being abstract.