Commands · reference
vmlab status
vmlab status reports what every machine in the current lab is doing, its IP address, the state of each segment, and any download in flight. It reads the lab daemon's status projection and never starts anything.
| Option | Meaning |
|---|---|
| -v, --verbose | Add the raw power state, readiness, and each machine's kind-specific detail (template/hardware, image/health/last exit). |
| -h, --help | Print help. |
What it prints
With no lab daemon running the verb prints lab "<name>": not running and exits 0. A full vmlab down reaps the daemon, so a lab that is down reports this. When the lab's name is registered from another directory, the lab running under it is that directory's, not this one's, and status refuses with the same conflict as up, naming the other directory (see The lab name is already registered). Otherwise it prints up to four sections, each omitted when empty.
Machines
One row per machine with the columns NAME, KIND (vm or container), STATUS, IP and TEMPLATE/IMAGE. STATUS is a label the daemon derives from the power state, readiness and health, so every surface words a machine the same way:
| Label | Meaning |
|---|---|
| starting | The process is being launched, or a container is up but its entrypoint has not signalled ready. |
| booting | A VM is running but not ready yet: its guest agent has not answered, or a first-boot script or agent refresh is still running. |
| running | Running and ready. |
| unhealthy | A container is ready but its declared healthcheck is failing. |
| stopping | The stop ladder is in progress. |
| suspended | A VM's guest put itself to sleep (ACPI S3). QEMU is alive and holds its memory, but nothing in the guest answers, so agent commands are refused with conflict. vmlab vm start wakes it; prevent_sleep = true on the VM keeps it from staying asleep. |
| stopped | Powered off. |
| exited (N) | A container's entrypoint exited with a non-zero code. |
IP is the first NIC with a lease, as reported by the guest agent, or - before the guest is ready. With --verbose a second line under each machine carries state=, ready= and cached=, plus diverged=yes on a machine whose agent was replaced by vmlab machine repair-agent or by the agent refresh in vmlab up. A VM then adds arch, cpus, memory and agent: the version of the agent running in the guest, as its last handshake reported it, or the version the template sealed before an agent has answered or while the VM is stopped. A container adds health, exit and digest.
Dev machines
Labs with @dev machines get a second table: DEV, DEFAULT (whether it is the lab's default dev machine), WORKSPACE (the host directory) and GUEST WORKSPACE. A halted workspace syncer prints its halt sentence under the machine's row, followed by vmlab dev sync status <machine> as the place to read more. See Dev machines and the workspace syncer and vmlab dev.
Segments
One row per lab segment: SEGMENT, SUBNET, GATEWAY, NAT/DHCP as on/off pairs, DROPPED (frames the switch shed on this segment; anything other than 0 means the fabric is losing frames under load) and PEER (the cross-host trunk target and whether it is up or down).
Downloads
While a template or image is downloading, a table of MACHINE, PULLING (template or container), PERCENT and REFERENCE shows what an up that looks stuck is waiting on. See vmlab pull.
Examples
Show the raw state behind each label:
Exit status
Exit status is 0, including when the lab is not running. A lab directory that cannot be found, or a daemon whose status reply this binary cannot read (a version mismatch between CLI and daemon), exits 1 (failed). A lab name registered from another directory exits 5 (conflict). A usage error exits 2.