すべてのコマンドは --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

1 コマンドで使い捨てマシン

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 は重要です。マシンを作成するエージェントは、作成したマシンを放置すべきではなく、これがクリーンアップ用の動詞です。