Command line

Everything day-to-day happens in the web UI. On a node's shell you have a few commands for recovery and local setup.

staxmax

The admin command. It never starts a daemon.

Command	What it does
sudo staxmax reset-password	Set a new admin password when nobody knows the current one.
staxmax decrypt-backup <in> <out>	Decrypt an offsite backup downloaded from the bucket or SFTP server, for incus import.
staxmax version	Print the installed version.
staxmax help	List the commands (also shown by staxmax on its own).

Resetting the admin password

sudo staxmax reset-password

It asks for the new password twice (or reads it from the first line of standard input, for scripts). It must be at least 8 characters. The running staxmaxd applies it within seconds, and it spreads to the other nodes like a change made on the Password tab of Settings. A node that is offline picks it up when it comes back. Every browser is signed out.

If staxmaxd does not apply it within 10 seconds (it is not running), the command says so; the password is saved and applied when staxmaxd starts. Use --data DIR only if staxmaxd runs with a non-default state directory. On a machine that is not set up as a node yet, it stops with no staxmaxd node is set up in /var/lib/staxmax.

Decrypting an offsite backup

You normally restore offsite backups from Settings (see Backups). To restore one by hand, without a cluster, download the .tar.gz.enc file from the bucket or SFTP server, then:

staxmax decrypt-backup web_20261009-020000.tar.gz.enc web.tar.gz
incus import web.tar.gz web-restored

It asks for the passphrase (or reads it from the STAXMAX_PASSPHRASE environment variable). It refuses to overwrite an existing output file, and stops with an error if the passphrase is wrong or the file is damaged or cut short.

staxmaxd

The node daemon, run by systemd as staxmaxd.service. You don't start it by hand; its options go in STAXMAXD_OPTS in /etc/staxmax/staxmaxd.env, which updates leave alone:

# /etc/staxmax/staxmaxd.env
STAXMAXD_OPTS="--listen :7443 --watchdog /dev/watchdog"

then sudo systemctl restart staxmaxd. Restarting staxmaxd does not stop your VMs; Incus keeps running them. The installer creates the file with --listen :7443. If you change the port, change it here with --listen: the update health check reads the port from this file.

Option	Default	Meaning
--listen ADDR	:7443	HTTPS address for the web UI, the API and node-to-node traffic.
--advertise host:port,…	auto-detect	The addresses other nodes should use to reach this one.
--watchdog DEVICE	none	Hardware watchdog device, e.g. /dev/watchdog. The node is reset if staxmaxd hangs, or if it is cut off and cannot confirm its VMs stopped. If the device cannot be used, staxmaxd runs without it and raises an alarm.
--pool NAME	the default profile's pool	Incus storage pool for VM disks and ISOs. Must be the same on every node.
--incus-socket PATH	auto-detect	The Incus unix socket (/var/lib/incus/unix.socket or /run/incus/unix.socket).
--data DIR	/var/lib/staxmax	State directory (set by the unit; don't put it in STAXMAXD_OPTS).
--version		Print the version and exit.

Service and logs

systemctl status staxmaxd        # is it running, which release
journalctl -u staxmaxd -f        # follow the log
sudo systemctl restart staxmaxd  # after changing staxmaxd.env (VMs keep running)

Updates

Updates are normally run from Settings in the web UI — see Updates. On a node:

Command	What it does
sudo staxmax-update status	Show the installed release and the last update run.
sudo staxmax-update rollback	Go back to the previous release on this node.
staxmax-update verify FILE.run	Check that a release (with its .run.sig beside it) is signed by a key this node trusts.
sudo staxmax-update apply FILE.run	Install a release on this node only (its .run.sig must be beside it). Prefer Install from a file in Settings → Updates, which updates every node in turn.

The logs of each install, update and rollback are in /var/log/staxmax/.

Uninstalling

sudo staxmax-uninstall

Stops and removes staxmaxd, its unit, its releases in /opt/staxmax and the commands (staxmax, staxmaxd, staxmax-update, staxmax-uninstall). Incus, the VMs, the ZFS pool, the state in /var/lib/staxmax, /etc/staxmax and /var/log/staxmax are left in place; it prints the commands to remove them if you want to. If the installer turned sleep off, uninstalling turns it back on. To remove a node from a cluster, retire it from the Nodes page first — see Nodes.