Adding a node takes two steps: you create the node in the panel, then you run the install command the panel shows as root on the server. The panel enrols the node as soon as the agent answers, usually within 30 seconds.
Before you start, check that the server meets the node requirements: Debian 12 or 13, amd64 (x86_64) or arm64 (aarch64), virtualisation enabled in the BIOS, and a public address the panel can reach.
Create the node in the panel#
Every node belongs to a location. If you have none yet, the Add node page sends you to Infrastructure › Locations first (see Locations, node groups and capacity).
- Go to Infrastructure › Nodes › Add node.
- Fill in:
- Name: a short name, at most 60 characters, such as the host name (
node1). - Location: where the node is. With a single location it is chosen for you.
- Address: the IP address or host name where the panel reaches the node.
- Port: the port the agent listens on. Leave 8443 unless you have a reason to change it.
- Name: a short name, at most 60 characters, such as the host name (
- Click Add node.
Nothing is installed yet. The node is created as Pending and its page opens with an Install the agent panel.
Note: If the panel's licence does not allow another node, Add node is refused with the reason and a link to Settings › Licence. See Node tiers.
Run the install command#
The Install the agent panel shows a one-line command with a Copy command button and how long it stays valid (Expires in). It looks like this:
curl -fsSL 'https://panel.example.com/downloads/install.sh' | VMSTACK_TOKEN=<token> bash -s -- \
--ca <base64 CA certificate> --agent-url 'https://panel.example.com/downloads/vmstack-agent' \
--port 8443 --sha256 <checksum> --panel-ip 203.0.113.10
<token>is a one-time enrolment token. It is passed as an environment variable so it does not appear in the process list.--cais the panel's certificate authority; the agent trusts only the panel that holds its key.--sha256(and--sha256-arm64when the release has an arm64 build) pins the agent binary the panel offers. On an arm64 node the installer downloads the arm64 binary beside the amd64 one by itself.--panel-ipappears when the panel's address is configured (VMSTACK_PANEL_IP): the installer then allows the agent port only from that address in ufw or firewalld, if one of them is active.--licensing enforceis added when your panel enforces its licence. See Installer options.
To install:
- Log in to the server as root (or use
sudo -i). - Paste the command. Add any installer options you need before running it, for example
--with-containersfor LXC containers,--with-zfsfor ZFS storages or--setup-storageto turn empty disks into the servers' storage. - Wait for
==> Done. The agent is listening on port 8443 and waiting for the panel to enroll it.
The command works for 60 minutes. When it has expired the panel says This command has expired.: click Generate new command and run the new one.
When the panel shows no download command#
If the panel has no download address configured for the agent (VMSTACK_AGENT_URL and VMSTACK_INSTALL_SCRIPT_URL in the panel's environment), the panel shows a command that uses local files instead:
VMSTACK_TOKEN=<token> bash install.sh --ca <base64 CA certificate> --binary ./vmstack-agent --port 8443
Copy install.sh and the vmstack-agent binary to the server, then run the command in the directory that holds them.
If the panel says The install command cannot be shown yet., its certificate authority is not set up: run php artisan vmstack:install on the panel server.
What the installer does#
- Checks that it runs as root on Debian 12 or 13 on amd64 or arm64, and warns when the CPU has no
vmxorsvmflag or/dev/kvmis missing. - Installs QEMU, libvirt and the tools the agent uses: the cloud-init seed builder,
dnsmasq-base(the program only, no DNS service),nftables,conntrack,nfs-common,lvm2,xfsprogs, UEFI firmware (OVMF), the TPM emulator,libguestfs-tools(for images made from servers),wireguard-tools(private networks) andsmartmontools(disk health; its ownsmartdservice is masked, the agent reads SMART itself). - Installs what the options ask for: ZFS, the Ceph client, LXC, the Proxmox Backup client.
- Downloads the agent binary, checks it against
--sha256and checks that it runs. - Writes
/etc/vmstack/agent.yaml, the panel's CA (/etc/vmstack/panel-ca.pem) and the token, and creates/var/lib/vmstack(state, and the default storage in/var/lib/vmstack/images). - Installs and starts the
vmstack-agentservice, plusvmstack-agent-rollback.timer, which rolls back a failed self-update. - Opens the agent port in ufw or firewalld when one of them is active. With no active firewall it adds no rule and says so.
The installer never changes the firewall policy or other services. A node that was enrolled before is refused ("this node is already enrolled") unless you add --force.
What happens in the panel#
The panel tries to enrol a pending node in the background. Once the agent answers:
- The panel signs a certificate for the key the agent made, and the node turns Online. See Enrolment and certificates.
- The first poll reads the hardware, software and storage, and the node starts downloading the enabled images and ISOs of the library (Images and ISOs on this node on the node's page).
- The Overview shows usage, Hardware and software, the Agent panel, the Certificate panel and the Node firewall panel.
Check the node and get it ready#
- On the node's Overview, click Run readiness check. It confirms that the server can host virtual machines and lists anything that fails.
- Add at least one IP block for the node in Infrastructure › IP pools (the node page says Add a block before creating servers on this node.). See IP pools.
- Review the node's Settings tab, in particular capacity. See Node settings.
- Consider turning on the node firewall: the Overview recommends it while it is off.
- If the node has spare disks, add them on the Storage tab. See Storage.
Ports the node uses#
| Port | From | Used for |
|---|---|---|
TCP 8443 (or --port) |
the panel | the agent's API (mutual TLS) |
| TCP 8444 | other nodes | moving servers between nodes |
| UDP 51820 | other nodes | private networks (WireGuard mesh) |
Other node actions#
The node page header has:
- Disable node: stops polling and refuses new tasks. Use it to take a node out of service; its servers cannot be controlled while it is disabled. Enable node undoes it. To stop only new servers, use the Maintenance tab instead (see Maintenance).
- Enroll again: revokes the certificate and puts the node back to pending. See Enrolment and certificates.
- Delete node: removes the node, its certificates and its task history from the panel after you type its name. Nothing is changed on the server itself.
If the install fails, see Troubleshooting nodes and storage.