If you've been running Proxmox VE on a single box for a while, you've probably hit the point where one server just isn't enough. Maybe you bought a second machine off eBay, or you want to move VMs between hosts without shutting them down first. That's where clustering comes in, and it's one of those features that sounds a lot scarier in the documentation than it actually is to set up.
This guide walks through building an actual Proxmox VE cluster from scratch: creating it on your first node, joining additional nodes, and confirming everything is actually talking to each other correctly. No Ceph, no shared storage requirement, no assumptions that you already know what quorum means.
What You Will Learn
By the end of this article you'll know how to turn two or more separate Proxmox VE installs into a single managed cluster. Specifically:
- What a Proxmox cluster actually is, and what it isn't
- The network and version requirements you need to sort out before you start
- How to create a cluster on your first node, using both the web GUI and the command line
- How to join additional nodes to that cluster
- What the important
pvecmcommands do - The errors people run into most often, and how to fix them
What Is This Feature?
A Proxmox VE cluster is a group of Proxmox nodes that share one configuration and one management view. Instead of logging into three separate web interfaces for three separate servers, you log into one, and you can see (and manage) all of them from the same screen.
Under the hood, two things make this work. The first is Corosync, a cluster communication engine that keeps every node talking to every other node over the network, constantly checking who's alive and who isn't. The second is pmxcfs, the Proxmox cluster filesystem, which replicates your configuration (VM definitions, storage config, users, permissions — everything under /etc/pve) to every node in real time. Change a firewall rule on node A, and it shows up on node B a second later.
Then there's quorum, which trips people up the most. Quorum is just a majority vote. If you have three nodes and one drops offline, the remaining two still form a majority (2 out of 3), so the cluster stays "quorate" and keeps functioning normally. Lose two out of three, and the one node left can't reach a majority — it assumes something has gone badly wrong on the network and locks down management operations as a safety measure. This is why two-node clusters are a bit awkward: lose either node, and the survivor has exactly 50%, not a majority, so it goes non-quorate. There's a workaround for that (a QDevice, which acts as a lightweight tiebreaker), but that's a topic for its own article — for now just know that odd numbers of nodes are the easy path.
Why Would You Use It?
The honest answer: because managing three separate Proxmox hosts individually gets old fast. Once you're clustered, you get a single pane of glass for VM and container management across every node, plus a few things that only work inside a cluster:
- Live migration — move a running VM from one node to another with no downtime, useful when you need to patch and reboot a host without kicking anyone off it.
- Centralized permissions and storage definitions — set up a user or an NFS share once, and it's available on every node.
- High Availability — if a node dies unexpectedly, HA can automatically restart its VMs on a surviving node (this needs to be configured separately, but it only exists as an option once you're clustered).
If you've got a single homelab box and no plans to buy a second one, none of this matters much to you yet, and that's fine — a cluster isn't a requirement to run Proxmox well. But the moment you have two or more physical machines, clustering them usually beats managing them separately.
Prerequisites
Before you touch pvecm, get these sorted. Most cluster-join failures trace back to one of these being skipped.
| Requirement | Why it matters |
|---|---|
| Same major Proxmox VE version on every node | Mixing, say, PVE 8.2 and 9.0 in one cluster isn't supported and can corrupt the shared config |
| Static IP address on every node | Corosync needs a stable address to talk to — a DHCP lease that changes will break cluster communication |
| Unique hostname per node | Two nodes named "pve" will conflict the instant you try to join them |
| Nodes can ping each other by IP and resolve each other's hostname | Add entries to /etc/hosts on every node if you don't have working DNS |
| Clocks in sync | Corosync is picky about time drift between nodes — check with timedatectl status |
| Low-latency network between nodes | Corosync wants well under 5 ms round-trip; running it over a flaky Wi-Fi bridge will cause random quorum loss |
One thing that catches people out: joining a cluster wipes the node's own /etc/pve configuration and replaces it with the cluster's. If that second node already has VMs configured on it that you care about, back up their configs first. The VMs themselves (the actual disk images) are untouched, but the node's local config database is not.
You'll also want root SSH access working between the nodes, since the join process needs to authenticate against the first node.
Step-by-Step Tutorial
We'll create the cluster on your first node (call it pve1), then join a second node (pve2). The process is identical for a third, fourth, and so on.
Step 1: Create the cluster on the first node
Log into the Proxmox web interface on pve1. In the left-hand tree, click Datacenter, then open the Cluster tab in the main panel. You'll see it's empty — no cluster exists yet.
Click Create Cluster. You'll be asked for:
- A Cluster Name — pick something short and simple, like
homelab. You can't change this later without rebuilding the cluster, so don't overthink it, but do pick something sane. - A Link 0 network — this is which network interface Corosync will use for cluster traffic. On a single-NIC box just leave the default. If you have a spare NIC, dedicating it to cluster traffic is a nice-to-have, not a requirement for a homelab.
Click Create. It takes a few seconds. If you'd rather do this from the shell, it's one command:
pvecm create homelabRun pvecm status right after, and you should see your one node listed with "Quorate: Yes" — a single-node cluster is always quorate, since one out of one is a majority.
Step 2: Grab the join information
Still on pve1, go back to Datacenter > Cluster and click Join Information. This opens a dialog with a big block of encoded text and a fingerprint. Click Copy Information — you'll paste this whole blob on the next node. It contains the cluster name, the node's address, and a certificate fingerprint so the joining node can verify it's actually talking to the right cluster.
Step 3: Join the second node
Log into pve2's own web interface (a separate login, since it isn't part of anything yet). Go to Datacenter > Cluster and click Join Cluster.
Paste the join information you copied. The dialog will auto-fill the peer address and fingerprint from it. You'll then be prompted for:
- The root password of pve1 (not pve2) — the joining node needs to authenticate against the cluster it's joining
- Which local network interface this node should use for cluster traffic
Click Join. This is the point where pve2's own cluster config gets torn down and replaced with pve1's. The pve-cluster service restarts, and for maybe 10 to 30 seconds the web interface on pve2 will be unresponsive — that's expected, not a crash. Give it a minute.
The CLI equivalent, run from pve2's shell:
pvecm add 192.168.1.10where 192.168.1.10 is pve1's IP address. You'll be prompted to confirm the fingerprint and enter pve1's root password.
Step 4: Confirm both nodes see each other
From either node, run:
pvecm statusYou should see "Nodes: 2" and "Quorate: Yes." Then run:
pvecm nodeswhich lists both nodes by name with their corosync node ID. If you log into pve1's web interface now, you should see pve2 appear automatically in the left-hand tree, and vice versa — one login, both nodes visible.
Step 5: Add more nodes (optional)
Repeat Step 3 on any additional node. There's no need to repeat Step 1 or 2 — the join information from pve1 still works, or you can pull fresh join information from any existing cluster member.
Commands Explained
A quick reference for the commands used above, since it helps to know what each one is actually doing rather than just copy-pasting:
| Command | What it does |
|---|---|
pvecm create <name> | Initializes a brand-new cluster on the current node, using the given name |
pvecm add <ip> | Joins the current node to the cluster that the node at the given IP already belongs to |
pvecm status | Shows cluster name, node count, and whether the cluster currently has quorum |
pvecm nodes | Lists every node in the cluster along with its internal Corosync node ID |
pveversion | Prints the installed Proxmox VE version — run this on every node before joining, to confirm they match |
timedatectl status | Shows whether the system clock is synchronized — check this on every node before creating or joining a cluster |
Common Errors
A few messages come up constantly when people try this for the first time.
"Cluster config already exists" — you're trying to run pvecm create or pvecm add on a node that's already part of a cluster (even a single-node one it created itself). If this node needs to join a different cluster, you'll need to remove it from its current one first.
Join hangs, then times out — almost always a network path issue. Confirm pve2 can actually reach pve1 on the address you gave it: ping 192.168.1.10. Also check that nothing between them (a VLAN misconfiguration, a firewall on either host) is blocking traffic.
"Certificate does not match" or fingerprint mismatch — the join information you copied is stale. Certificates and fingerprints get regenerated in some situations; just go back to Datacenter > Cluster > Join Information on the target cluster and copy a fresh block.
Web interface unreachable on the joining node right after clicking Join — this is normal for a short window while pve-cluster restarts and pmxcfs re-syncs. Give it a minute or two before assuming it's broken.
Node joins but VMs that existed on it beforehand have vanished from the GUI — this is the "joining wipes local config" behavior mentioned earlier. The VM disks are still sitting on storage, but their configuration files were removed along with the rest of the pre-join /etc/pve. This is recoverable if you kept a backup of the old config, but it's much easier to avoid it in the first place by not joining a node that already has VMs you care about.
Troubleshooting
If something's off after joining, start with pvecm status on every node — don't just check one. It's possible for node A to think it's in a healthy 3-node cluster while node B thinks it's isolated, which tells you the split is one-directional (usually a routing or firewall issue in one direction only).
Check the actual service logs next:
journalctl -u corosync -n 50
journalctl -u pve-cluster -n 50Corosync logs will tell you if it can't reach a peer at all, which usually points back to the network requirements from the Prerequisites section — wrong IP, blocked port, or a NIC that isn't actually on the same broadcast domain as the other node.
If cluster networking uses a firewall between nodes (a separate router, pfSense, whatever), make sure UDP traffic on Corosync's default port range is allowed between all cluster members. This is easy to miss if your nodes sit on different VLANs with a firewall in between them — a lot of homelabs don't need this rule at all because everything's on one flat LAN, but it's worth checking if you've segmented your network.
If a node is stuck refusing to restart pve-cluster after a failed join attempt, restarting the relevant services in order often clears it:
systemctl restart corosync
systemctl restart pve-cluster
systemctl restart pvedaemon pveproxyAnd if quorum is lost because too many nodes are down and you're in an emergency and genuinely need to force operations through on the surviving node — don't do this casually, it can cause split-brain if the "dead" nodes actually come back online mid-operation. It's meant for genuine disaster recovery, not a routine fix, so treat it as a last resort rather than a first troubleshooting step.
Best Practices
A handful of habits will save you a bad afternoon later:
- Stick to an odd number of nodes (3, 5, 7) if you can. It makes quorum math simple and tolerant of a single failure without needing a QDevice.
- Keep every node on the same PVE minor version before you add it, and try to stay in sync afterward too. Update one node, test it, then move to the next — don't leave nodes on wildly different patch levels for long stretches.
- Use static IPs, not DHCP reservations that could theoretically change. Corosync doesn't handle an address change gracefully.
- If you have a spare NIC, put Corosync traffic on its own link rather than sharing it with VM traffic. It's not required for a small homelab, but it means a saturated network from a big file transfer won't cause quorum flapping.
- Take a backup of any existing VM configs before joining a node that already had standalone VMs on it. I'd rather have an unnecessary backup sitting around than lose a working config to a join gone wrong.
Frequently Asked Questions
Can I create a cluster with only two nodes?
Yes, technically, but losing either node drops you below quorum. Most people either add a third node later or set up a QDevice as a tiebreaker.
Do I need shared storage to build a cluster?
No. A cluster is about shared management and configuration, not shared storage. You can live-migrate VMs without shared storage too, using storage replication or migration-with-local-disk, though both come with their own trade-offs.
Will joining a cluster affect my existing VMs?
The VM disk images themselves are untouched. What gets wiped is the node's separate /etc/pve configuration database, which includes the VM config files that describe them. Back those up first if the node isn't brand new.
Can I mix Proxmox VE 8 and 9 nodes in one cluster?
Don't. Match major versions across the whole cluster before joining anything.
How do I remove a node later if I change my mind?
That's a different process using pvecm delnode, with a specific order of operations to avoid breaking quorum for the nodes that remain — worth its own dedicated read rather than a quick aside here.
Conclusion
Building your first Proxmox cluster is one of those tasks that takes longer to explain than to actually do. Once your nodes have static IPs, matching versions, and synced clocks, the actual create-and-join process is a couple of clicks and one password prompt per node. The part worth taking seriously is everything in the Prerequisites section — skip those and you'll spend your evening reading Corosync logs instead of migrating your first VM between hosts.
From here, the natural next steps are setting up storage replication or shared storage so live migration actually has something to move disks onto, and if you're running exactly two nodes, looking into a QDevice so a single node going down doesn't take your whole management layer with it.