How to Configure a Proxmox VE Cluster via the CLI (pvecm, qm, pct)

This knowledge base article walks through building a Proxmox VE 8.x cluster entirely from the command line. Everything here is done as root over SSH on each node. Before you start, make sure every node runs the same Proxmox VE version, has a unique hostname, has correct and synchronized time (NTP/chrony), and that the nodes can reach each other on the network. Important: a node must have no VMs or containers on it when it joins an existing cluster — join nodes while they are still empty.

1. Plan the cluster network

Corosync, the cluster communication layer, is latency-sensitive. For production, give it its own physical network (or VLAN) separate from VM and storage traffic, and configure a second link for redundancy. Confirm each node's IP layout before proceeding:

ip -c addr show
ping -c 3 192.168.10.11   # reachability to the other nodes

2. Create the cluster on the first node

On the node that will start the cluster, create it and give it a name. You can specify the corosync link address explicitly so corosync binds to your dedicated cluster network:

# Simple form
pvecm create CLUSTERNAME

# With an explicit corosync link (recommended)
pvecm create CLUSTERNAME --link0 192.168.10.11

Verify the cluster is alive and that this node is quorate:

pvecm status
pvecm nodes

3. Join the remaining nodes

Run the join command on each new node (not on the existing cluster node), pointing at the IP address of any node already in the cluster. You will be prompted for that cluster node's root@pam password and asked to confirm its certificate fingerprint:

# On node 2, join the cluster reachable at 192.168.10.11
pvecm add 192.168.10.11 --link0 192.168.10.12

# Add a redundant second link if you configured one
pvecm add 192.168.10.11 --link0 192.168.10.12 --link1 10.0.0.12

If you prefer the legacy SSH-based join (which merges the root SSH key), add --use_ssh. After each node joins, re-check status — the node count should grow and the cluster should remain quorate:

pvecm status
pvecm nodes

4. Quorum and the two-node case

A cluster needs more than half its votes online to be "quorate" and allow changes. With three or more nodes this is automatic. For a two-node cluster, losing one node drops you below quorum, so add an external tie-breaker called a QDevice. Install the package on all cluster nodes and on the external QDevice host, then set it up from any cluster node:

# On every cluster node
apt install corosync-qdevice

# On the external QDevice host
apt install corosync-qnetd

# From one cluster node, register the QDevice (external host IP)
pvecm qdevice setup 192.168.10.5

# Confirm the QDevice now contributes a vote
pvecm status

In an emergency where you must operate temporarily without quorum (for example, a single surviving node), you can lower the expected votes — use this with care:

pvecm expected 1

5. Optional: add Ceph shared storage with pveceph

For shared, scale-out storage across the cluster, deploy hyper-converged Ceph. Install the Ceph packages, initialize the configuration on your dedicated storage network, then create monitors, managers and OSDs:

# Install Ceph on each node
pveceph install

# Initialize Ceph on the storage subnet (run once)
pveceph init --network 192.168.20.0/24

# Create a monitor and a manager on each relevant node
pveceph mon create
pveceph mgr create

# Create an OSD from a free, unpartitioned disk (repeat per disk/node)
pveceph osd create /dev/sdb

# Check Ceph health
pveceph status
ceph -s

6. Create VMs and containers, then live-migrate

With the cluster and storage in place, create a VM with qm and an LXC container with pct:

# Create a VM (id 100) with 4 GB RAM, 2 cores, on the vmbr0 bridge
qm create 100 --name web01 --memory 4096 --cores 2 \
  --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-single

# Create an LXC container (id 200) from a template
pct create 200 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname app01 --memory 2048 --cores 2 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

Now move workloads between nodes with zero or minimal downtime. Online (live) migration keeps the VM running during the move; for containers you typically use restart-migration:

# Live-migrate VM 100 to node pve2
qm migrate 100 pve2 --online

# Migrate VM 100 with its local disks to a target storage
qm migrate 100 pve2 --online --with-local-disks --targetstorage local-zfs

# Migrate container 200 to pve2 (brief restart)
pct migrate 200 pve2 --restart

7. Storage replication and removing a node

On ZFS-backed clusters without shared storage, schedule asynchronous replication so a VM's disk exists on the target node before migration, making failover fast:

# Replicate VM 100 to pve2 every 15 minutes
pvesr create-local-job 100-0 pve2 --schedule '*/15'

To permanently remove a node, first migrate everything off it and power it down for good, then from a remaining node delete it — never rejoin a deleted node with the same name without a clean reinstall:

pvecm delnode pve3
pvecm status

Need help?

SKYLINE installs, configures, supports and troubleshoots Proxmox VE clusters across Saudi Arabia. For the full service — design, ZFS/Ceph, VMware migration and AMC — see our Proxmox VE service page, browse the marketplace, or contact us on +966 50 993 9334.