모든 명령은 --json을 받아들이고 stdout에 기계가 읽을 수 있는 출력을, stderr에 오류를, 의미 있는 종료 코드와 함께 내보냅니다. 형태는 고정되어 있습니다. 모든 객체는 apiVersion: 1을 포함하고, 필드는 추가만 되며, 호환성을 깨는 변경은 버전을 올립니다. 테스트 스위트로 고정되어 있습니다.

출력은 키가 정렬되고 날짜는 ISO-8601 형식으로 예쁘게 출력됩니다.

형태

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에는 name, id, guest, state, cpuCount, memoryBytes, diskBytes, network, path, address, snapshotCount, isTemplate, waitingForDHCP 및 networkStatistics가 포함됩니다. list --json에는 state: "archived"인 아카이브된 머신도 포함됩니다.

OperationJSON에는 ok, operation, vm, detail 및 durationMilliseconds가 포함됩니다. 이를 통해 누군가의 말을 믿는 대신 측정된 스냅샷 타이밍을 얻을 수 있습니다.

종료 코드

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

파괴적인 명령은 프롬프트 대신 종료 코드 4로 거부합니다. 대화형 프롬프트가 없으므로 스크립트가 사람을 기다리며 멈추지 않습니다. 정말 실행하려면 --force 또는 --yes를 전달하세요.

신뢰할 수 있는 스크립트

흔한 실수는 "running"을 "ready"로 취급하는 것입니다. wait-ready는 게스트가 실제로 도달 가능할 때까지 블록합니다:

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

한 명령으로 일회용 머신

task run은 clone-wait-exec-dispose 루프 전체를 처리합니다:

1vm task run -- ./build.sh

고정된 golden 이미지를 복제하고, 준비 상태를 기다린 뒤, 명령을 실행하고 머신을 폐기합니다. golden 이미지는 template pin, template list, golden capture로 관리합니다.

MCP

1VMTool은 Model Context Protocol을 지원하므로 AI 에이전트가 머신을 직접 소유하고 제어할 수 있습니다:

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는 중요합니다. 머신을 만드는 에이전트는 그것들을 방치하면 안 되며, 이것이 정리 동사입니다.