Nodes

The Nodes page shows one card per node and, below them, how to add another.

The node card

Item	Meaning
Primary / Secondary, version	The node's role, and the staxmax version it runs. this node marks the node serving the page.
Online / Offline / Maintenance	Whether the node serving the page hears it, or that it is in maintenance.
Router	Whether the node reaches the router (its default gateway): Reachable, Unreachable, or Unknown while the node is offline.
Running VMs, CPU threads, model and CPU	What it runs, the machine's manufacturer and model (when its firmware reports one) and its processor. Live moves need the same CPU model on both nodes.
Smart plug	The plug that can cut its power, or None. Shown once there are two or more nodes.
Heartbeat paths	On the other nodes' cards: each address the node serving the page uses to reach that node, with its latency or No response. A Direct cable is a cable between spare ports, found automatically.
CPU, Memory, Storage	How busy the node's processor is across all its threads, and use of its memory and its VM storage pool. CPU appears a few seconds after the node comes online.

The buttons at the bottom are Settings, Maintenance and Retire. Maintenance and Retire appear once there are two or more nodes, and Maintenance only while the node is online and not already in maintenance.

How the cluster decides who keeps running depends on its size; the text at the top of the page says which applies. With two nodes, the router breaks a tie. With three or more, a majority decides. See Failover.

Node settings

Click Settings on a node's card.

Name

Starts with a letter and ends with a letter or digit; letters, digits and dashes, up to 63 characters. Renaming this node reaches the others within a second. Renaming another node needs it online, since it renames itself.

Heartbeat paths

Shown for the other nodes only. These are the addresses (like 10.99.0.2:7443) this node uses to reach that node, checked every second. They are stored on this node only.

• Two paths, such as a second network plus your LAN, keep one unplugged cable from causing a failover.
• Addresses the other node announces are added on their own. Remove one it can't be reached on and it stays removed; it then appears under Not used, with Use again to bring it back.
• A direct cable between spare ports is found on its own and needs no address.

At least one address is needed. See Networking.

Smart plug

Optional, and recommended. Tick node is powered by a smart plug, choose the Plug type (Shelly) and give the Address of the plug, like http://192.168.1.60. Before taking over that node's VMs, another node switches its power off with the plug, so two nodes can never run the same VM. The plug must be reachable from the other nodes.

Click Save.

Add a node

The card at the bottom is Add a second node on a single node, or Add a node once there are two or more.

1. Click Show the join command.
2. On the new machine (Ubuntu 24.04/26.04 or Debian 12/13, on the same network), run the command in a terminal. It installs staxmax from this node and joins it to the cluster.
3. The command works until the time shown. Create a new token makes a fresh one.

Add --disk /dev/nvme1n1 to the command to give the VMs a whole disk (it is wiped; otherwise they get a file on the system disk), or --name mini-3 to name the node something other than its hostname.

To install staxmax yourself instead, open Install it yourself instead, copy the token, run the staxmax .run installer on the new machine, open its web page, choose Join an existing cluster and paste the token.

Every node must be online while a node joins. A new node starts empty; new VMs, moves and failovers can use it. Going from two nodes to three switches the cluster from the router tiebreaker to a majority. See Adding nodes.

Retire a node

Retire is for a machine leaving the cluster for good. It is offered once there are two or more nodes, but a cluster needs at least two nodes, so a node can only be removed from a cluster of three or more. To replace a node in a two-node cluster, add the new machine first, then retire the old one.

The dialog walks through three steps:

1. Move its VMs off: click Start maintenance. Each VM moves to the node holding its copy, one at a time, with about 20 seconds of downtime each. If the node is already offline but still owns VMs, wait for failover or force start them from Virtual machines (see Force start after a failure).
2. Shut it down: run sudo poweroff on the node, or switch it off. The step turns green when the other nodes stop hearing it.
3. Remove it from the cluster: click Remove node. The button works once the node is offline and owns no VMs, and every other node must be online. Do this from another node's page, since the retired node's page goes away when it shuts down.

Every VM whose copy the retired node held gets a new copy elsewhere. If the machine is switched on again later, it keeps its VMs stopped and has to be set up again.