How to Connect Two Proxmox Servers Into One Cluster

What connecting two Proxmox servers means

Connecting two Proxmox servers creates a cluster — a group of machines that share the same control panel and can move virtual machines between them without shutting them down. Instead of managing each server separately through its own web interface, you log into one cluster dashboard and see all your resources in one place.

The practical result: if one server needs maintenance or fails, you can shift the virtual machines running on it to the other server with minimal downtime. You also get a shared storage pool, so a virtual machine can live on either server without being tied to one physical box.

This is different from straightforward networking two servers together. Clustering requires specific setup steps, shared authentication, and a quorum system that prevents both servers from making conflicting decisions if the connection between them breaks.

Key Takeaways

Both servers must run the same major version of Proxmox VE and have static IP addresses that can reach each other reliably.
The first server becomes the cluster node that other servers join; you create a join token on the first server and use it on the second.
Clustering requires at least three nodes for a stable quorum, though two nodes can cluster together if you accept that either one failing will lock the cluster.
After joining, both servers share the same Proxmox cluster filesystem (pmgfs) and you manage them from a single web interface at the cluster IP address.
Network connectivity between the two servers must be stable and low-latency; a dropped connection can cause virtual machines to behave unpredictably.

Prerequisites before you start

Both servers need to be freshly installed Proxmox VE systems with no virtual machines or containers yet running on them. If you already have workloads on either server, you will need to back them up, remove them, and restore them after clustering is complete.

Each server must have a static IP address on your network — not one assigned by DHCP that might change. You also need to know the hostname of the first server (the one you will join to) and be able to reach it by that hostname from the second server. Test this by logging into the second server and running ping hostname-of-first-server from the command line.

Both servers must run the same major version of Proxmox VE. If one is running version 7 and the other version 8, they cannot cluster together. Check the version on each server by logging into its web interface and looking at the bottom left corner of the dashboard.

You will also need root access to both servers and the ability to log into their web interfaces. Have the root password for the first server ready before you start the join process on the second.

Creating a join token on the first server

Log into the web interface of the first server using its IP address and root credentials. In the left sidebar, navigate to Datacenter, then Cluster.

Click the Create Cluster button. A dialog will appear asking for a cluster name — this can be any name you choose, like "production-cluster" or "lab-cluster". The cluster name is only for your own reference. Click Create.

Once the cluster is created, you will see a Cluster section in the left sidebar. Click on it, then click the Nodes tab. You should see the first server listed as a node. Now click the Join Information button — this generates a token that the second server will use to join.

A window will display a long string of text starting with "PVE". Copy this entire string. This is your join token, and it is valid for one hour. If you do not use it within that time, you will need to generate a new one.

Joining the second server to the cluster

Log into the web interface of the second server using its own IP address and root credentials. Navigate to Datacenter, then Cluster.

Click the Join Cluster button. A dialog will appear with two fields: Cluster Name and Cluster Join Token. Paste the join token you copied from the first server into the token field. The cluster name should auto-fill, but if it does not, type the same cluster name you created on the first server.

Click Join. The second server will now contact the first server, verify the token, and begin the clustering process. This can take a few minutes. Do not close the browser window or refresh the page during this time.

When the process completes, the second server will reboot automatically. This is normal. After it comes back online, log in again and navigate to Datacenter > Cluster > Nodes. You should now see both servers listed as nodes in the cluster.

What happens to storage and networking after clustering

Both servers now share a cluster filesystem called pmgfs, which stores cluster configuration and metadata. This filesystem is automatically replicated between the two nodes, so if one server fails, the cluster configuration survives on the other.

However, the local storage on each server remains local. A virtual machine stored on the first server's local disk cannot automatically move to the second server if the first one fails — it will straightforward be unavailable. To enable automatic failover, you need to set up shared storage (like NFS, iSCSI, or Ceph) that both servers can access. This is a separate step beyond clustering.

The network connection between the two servers is critical. Proxmox uses this connection to heartbeat — each server periodically checks that the other is still alive. If the connection drops for more than a few seconds, the cluster may fence (forcibly shut down) virtual machines to prevent data corruption. For this reason, use a dedicated network cable or a reliable, low-latency network path between the two servers if possible.

Quorum and what happens if one server fails

A two-node cluster has a quorum problem: if the connection between them breaks, neither server can know whether the other has actually failed or just lost network contact. Proxmox solves this by requiring at least three nodes for a stable quorum.

With only two nodes, if one fails or the network between them breaks, the cluster will lock itself to prevent both servers from making conflicting decisions about virtual machines. The surviving server will not be able to start new virtual machines or modify cluster settings until the failed server comes back online or you manually override the quorum.

If you need true high availability with only two servers, you can add a third node later (even a low-power machine) to act as a quorum tie-breaker. Alternatively, you can accept the quorum limitation and manually intervene if a failure occurs.

Troubleshooting common connection problems

If the second server fails to join, the most common cause is that it cannot reach the first server by hostname. Log into the second server via SSH and run ping hostname-of-first-server. If this fails, check that both servers are on the same network and that your DNS or local hostname resolution is working. You can also try using the IP address of the first server instead of its hostname.

If the join appears to succeed but the second server does not show up in the cluster after rebooting, check that both servers are running the same major version of Proxmox. Log into each server's web interface and verify the version number in the bottom left corner.

If the cluster shows both nodes but they frequently show as "offline" in the cluster status, the network connection between them is likely unstable or has high latency. Check the physical network cable, switch, and firewall rules. Proxmox cluster traffic uses port 5405 (UDP) and port 5406 (TCP) — make sure these ports are not blocked between the two servers.

Frequently Asked Questions

Can I cluster two servers that already have virtual machines on them?

Not directly. You will need to back up all virtual machines, remove them from both servers, complete the clustering process, and then restore the backups. Proxmox provides backup and restore tools in the web interface under Backup for each virtual machine.

What if I lose the join token before using it?

Generate a new one. Log into the first server's web interface, go to Datacenter > Cluster > Join Information, and click the button again. The old token becomes invalid when ready.

Can I remove a server from the cluster later?

Yes. Log into the cluster web interface, go to Datacenter > Cluster > Nodes, select the node you want to remove, and click Remove. The server will leave the cluster but remain installed with Proxmox. You can then use it as a standalone server or join it to a different cluster.

Do both servers need to be in the same physical location?

No, but network latency matters. If the servers are far apart and the network connection between them is slow or unreliable, the cluster will be unstable and virtual machines may behave unpredictably. For geographically distant servers, consider replication instead of clustering.

What is the difference between clustering and replication?

Clustering creates a single management interface and shared configuration. Replication copies virtual machine data from one server to another but keeps them as separate systems. Replication works better for distant servers; clustering works better for servers on the same local network.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.