maand worker

worker manages SSH operations against hosts listed in workspace/workers.json: pin host keys, probe capacity, and print uptime.

CLI

maand worker trust [flags]
maand worker facts [flags]
maand worker uptime [flags]

Examples:

maand worker trust
maand worker trust -w 10.0.0.1 --force
maand worker facts
maand worker facts --generate-workers > workspace/workers.json
maand worker facts --generate-workers -w 10.0.0.1,10.0.0.2 -c 2
maand worker uptime -w 10.0.0.1,10.0.0.2 -c 2
maand worker uptime --ignore-failure

Subcommands

maand worker trust

Captures each worker's SSH host key with ssh-keyscan and stores hashed entries in bucket/.ssh/known_hosts. All subsequent maand SSH connections (deploy, rsync, job control, worker facts, etc.) verify host keys against this file.

Run from a trusted network when adding workers to workers.json. Re-run with --force after a legitimate worker reinstall or host key rotation.

# after editing workspace/workers.json
maand worker trust
maand build
maand deploy

If a host key is missing, other commands fail with:

worker 10.0.0.1: host key not trusted. Run: maand worker trust -w 10.0.0.1

maand worker facts

Prints discovered memory, cpu, and attached block disk usage for each worker:

10.0.0.1 memory="8192 mb" cpu="2400 mhz" volume="/dev/sda size=100 gb usage=45 gb usage_pct=45%" volume="/dev/nvme0n1 size=500 gb usage=120 gb usage_pct=24%"

Memory comes from /proc/meminfo (MemTotal). CPU is logical cores × per-core MHz from /proc/cpuinfo or lscpu.

Disk volumes list top-level block devices (TYPE=disk from lsblk), excluding virtual devices (zram, loop, ram, fd). For each disk, size is the device capacity; usage sums filesystem used space across mounted partitions on that disk; usage_pct is usage ÷ size. Volume data is print-only — it is not stored in workers.json, the catalog, or KV.

With --generate-workers, stdout is valid workers.json: the current file with probed memory / cpu merged in (other fields preserved). Disk volume data is not included in generated JSON. Redirect to update the workspace file:

maand worker facts --generate-workers > workspace/workers.json
maand build

With -w / -l, only matching workers are probed; the printed JSON still includes all workers from the current file (unprobed entries unchanged).

With --generate-workers and --ignore-failure, successful probes are merged into the printed JSON; failures go to stderr and the exit code is 1.

maand worker uptime

Prints host uptime for each worker as each probe completes (completion order, not workers.json order):

10.0.0.1 uptime="up 3 days, 4 hours, 12 minutes"

Prerequisites

• Initialized bucket with worker host entries in workspace/workers.json.
• maand worker trust run for each worker (pins host keys in bucket/.ssh/known_hosts).
• SSH key at secrets/<ssh_key> (from maand.conf) authorized on workers.
• Host tools: bash, ssh, ssh-keyscan (checked before SSH).
• Target workers: Linux with /proc/meminfo (facts), bash, and timeout (sudo when use_sudo = true). Disk volume data additionally requires lsblk and df on the worker.

Unlike maand run_command, maand worker facts / uptime do not require a prior maand build.

Failure behavior

By default, if any worker probe fails, no output is printed and the command exits with code 1.

With --ignore-failure:

• Successful workers are printed to stdout as each probe finishes.
• Failures are summarized on stderr after all probes complete.
• Exit code is 0 only when all workers succeed; otherwise 1.

Example:

maand worker uptime --ignore-failure
# stdout:
10.0.0.1 uptime="up 3 days, 4 hours, 12 minutes"
# stderr:
worker uptime failures (1):
worker 10.0.0.2: ssh: connect to host 10.0.0.2 port 22: Connection refused
# exit code: 1

If every worker fails, there is no stdout output; stderr lists all failures and the exit code is 1.