Every command takes --json and emits machine-readable output on stdout, with errors on stderr and a meaningful exit code. The shapes are frozen: every object carries apiVersion: 1, fields are only ever added, and a breaking change bumps the version. They are locked by the test suite.

Output is pretty-printed with sorted keys and ISO-8601 dates.

Shapes

Shape	Commands
`VMSummaryJSON`	`list`, `info`, `create`
`SnapshotJSON`	`snapshot list`
`OperationJSON`	mutating commands — `snapshot`, `reset`, `clone`, `archive`, `rm`, …
`LogLineJSON`	`logs`
`AddressJSON`	`ip`
`DiskUsageReportJSON`	`du`
`GuideJSON`	`guide <guest>`

VMSummaryJSON carries name, id, guest, state, cpuCount, memoryBytes, diskBytes, network, path, address, snapshotCount, isTemplate, waitingForDHCP and networkStatistics. list --json includes archived machines with state: "archived".

OperationJSON carries ok, operation, vm, detail and durationMilliseconds — which is how you get the measured snapshot timings rather than taking anyone's word for them.

Exit codes

Code	Meaning
0	ok
1	failed
2	usage
3	not found
4	wrong state
5	unsupported

Destructive commands refuse with exit 4 instead of prompting. There are no interactive prompts, so a script never hangs waiting for a human. Pass --force or --yes when you mean it.

A reliable script

The mistake is treating "running" as "ready". wait-ready blocks until the guest is actually reachable:

set -e
1vm create ci --from ubuntu-golden
1vm start ci --detach
1vm wait-ready ci
1vm exec ci -- ./run-tests.sh
1vm discard-session ci --force

Disposable machines in one command

task run does the whole clone-wait-exec-dispose loop for you:

1vm task run -- ./build.sh

It clones a pinned golden image, waits for readiness, runs the command and disposes of the machine. Golden images are managed with template pin, template list and golden capture.

MCP

1VMTool speaks the Model Context Protocol, so an AI agent can own and drive machines directly:

1vm mcp serve                      # JSON-RPC on stdio
1vm mcp install-snippet claude     # config JSON for a host
1vm agent gc                       # delete stopped agent-created machines

agent gc matters: an agent that creates machines should not leave them lying around, and this is the cleanup verb.