Give agents the full FlashVM lifecycle.

The resource contract: limits only when you pass them

A VM's shape is required: --vcpus and --mem-mib (REST: vcpus, mem_mib). Every cap is optional. Omit a cap and that resource runs uncapped; pass it and it is enforced. Neither flash, flash-mcp, the REST API, nor the pool daemon ever picks a limit for you. A value that cannot be enforced is refused with 422, never accepted and dropped, and an out-of-range value is refused, never clamped.

Live changes go through flash set (REST PATCH /v1/flashvm/cpu, /disk, /nics/{i}); a live rate of 0 removes that cap. Guest RAM is fixed at creation — reclaim with the balloon, or resize a region reserved with --mem-region-mib via flash mem. Platform notes an agent should know: the disk cap (disk_mib) is a live quota on what the guest writes on every OS; on macOS a VM can run on the vz engine (flash run --engine vz: Rosetta for x86_64 binaries, virtio-fs shares, NIC caps only — CPU/disk caps, snapshots and pools are refused) instead of the default hvf, which enforces every cap.

1. Create a VM with flash_cli

Creating a VM starts a new flashvmm process, so flash-mcp invokes the real flash CLI through flash_cli. Once that process binds its endpoint, the agent manages the VM directly through the HTTP API. There is no separate create tool to drift out of sync with the CLI.

# tool call
flash_cli(args: ["run", "--bundle", "/opt/flashvmm/bundles/current",
  "--vcpus", "2", "--mem-mib", "1024",
  "--cpu-template", "host-raw", "--entry", "/your/workload", "--id", "myvm"])

# what it runs — no caps passed, so none applied
flash run --bundle /opt/flashvmm/bundles/current --vcpus 2 --mem-mib 1024 \
  --cpu-template host-raw --entry /your/workload --id myvm

# the same VM with every limit enforced
flash run --bundle /opt/flashvmm/bundles/current --vcpus 2 --mem-mib 1024 \
  --cpu-millis 1500 --disk-mib 2048 --disk-bps 104857600 --disk-iops 10000 \
  --cpu-template host-raw --entry /your/workload --id myvm

# with the guest bridge: HTTP into the workload, and messages both ways
flash run --bundle /opt/flashvmm/bundles/current --vcpus 2 --mem-mib 1024 \
  --entry /your/workload --id myvm --http-port 8080 --messaging-topics jobs,events

--vcpus and --mem-mib are required. --http-port (for guest http) and --messaging-topics (for guest send/recv; * = every topic) turn on the guest bridge at creation. --cpu-template is optional to run and required for any VM that will be captured, because it cannot be added later. On macOS the bundle is /opt/flashvmm/bundles/default; on Windows it is C:\Program Files\FlashVMM\guest.

3. Observe the VM in real time

With the process running, control and observation move to HTTP over the VM's endpoint. flash_metrics, flash_inspect, flash_logs, and flash_diagnose are structured views over that same API.

# tool call
flash_metrics(vm_id: "myvm")

# raw HTTP, the same request flash_api makes (Linux / macOS)
curl --unix-socket /run/flashvm/myvm.sock http://localhost/v1/flashvm/metrics

A metrics call returns a live sample of CPU, memory, disk I/O, and per-NIC traffic. flash_watch(vm_id, stream, for_secs) turns the same data into an SSE stream delivered as MCP progress notifications; flash_watch_fleet follows up to 20 VMs at once.

5. Restore or clone with flash_cli

Restore creates a new VMM process from the snapshot, so the workflow returns to flash_cli. The process resumes from the captured execution state instead of repeating a cold boot.

# tool call
flash_cli(args: ["restore", "--bundle", "/opt/flashvmm/bundles/current",
  "--from", "/var/tmp/myvm.snap", "--vcpus", "2", "--mem-mib", "1024",
  "--cpu-template", "host-raw", "--id", "myvm"])

--vcpus and --mem-mib must match the capture. Restore returns the captured VM under its original identity, so --id must match the snapshot; use flash_cli(args: ["clone", ...]) to create a new identity from the same artifact. Caps are optional here too.

Run commands and move files with flash_exec and flash_cp

An agent works inside its VM directly — no network, no SSH, no shared folder needed. Both tools ride a dedicated virtio-console port into the guest agent, on every platform.

# tool calls
flash_cp(src: "/Users/me/sales.csv", dst: "agent-exec:/data/sales.csv")
flash_exec(vm_id: "agent-exec", argv: ["sh", "-c", "awk -F, 'NR>1 {s+=$3} END {print s}' /data/sales.csv"],
  timeout_s: 30)
# -> {"exit_code": 0, "state": "exited", "stdout": "48210\n", "stderr": "", "duration_ms": 41, "truncated": false}
flash_cp(src: "agent-exec:/data/report.txt", dst: "/Users/me/report.txt")
flash_cli(args: ["del", "agent-exec:/data", "--recursive"])

# kill or remove an exec record (resource CRUD on the VM's endpoint)
flash_api(vm_id: "agent-exec", method: "PATCH", path: "/v1/flashvm/guest/execs/7", body: {"state": "killed"})
flash_api(vm_id: "agent-exec", method: "DELETE", path: "/v1/flashvm/guest/execs/7")

Caps: 64 concurrent execs per VM (the 65th is 429 too_many_execs), 16 MiB of output kept per stream (truncated says when retention cut it), 1 GiB per file. A non-empty directory without --recursive is 409 not_empty; / is never deleted.

Use an API without holding its key: --secret-proxy

The agent in the VM calls its model (or any HTTP API) through a URL on the host; FlashVMM adds the key outside the VM. The key is never in the guest's environment, files or memory, and an upstream that echoes it comes back masked.

# tool calls
flash_cli(args: ["run", "--bundle", "/opt/flashvmm/bundles/current", "--id", "agent", "--vcpus", "1",
  "--mem-mib", "1024", "--nic", "{NIC}", "--egress", "none",
  "--secret-proxy", "model=/home/me/model.key,upstream=https://api.example.com,header=x-api-key,max-calls=200",
  "--entry", "/work/agent", "--detach"])
# inside the VM: POST $FLASH_PROXY_MODEL_URL/v1/messages  (plain HTTP; no key, no TLS)
flash_secret_proxy_calls(vm_id: "agent", name: "model")
# -> {"calls": [{"seq": 1, "method": "POST", "path": "/v1/messages", "status": 200, "bytes": 2438, "duration_ms": 1895}, ...], "next": 3}

--egress none plus a proxy is an agent that can reach its model and nothing else. Streaming replies pass straight through. Past max-calls or max-bytes the guest gets 429; flash proxies ID NAME --max-calls N|none changes a cap while the VM runs. A fork child gets the parent's proxies with its own counters, a pool spare takes them with its claim, and a restore must be given the key again (a snapshot never holds one).

Warm pools with flash_pool

flashpoold keeps pools of parked spares ready to claim. flash_pool sends one resource-CRUD request to its socket (Linux/macOS) or pipe (Windows). Only the shape is required; caps are optional and apply to every member when given.

# tool call: a pool of 3 spares, 1 vCPU / 512 MiB each, uncapped
flash_pool(method: "POST", path: "/v1/pools?wait=idle&timeout_s=120",
  body: {"shape": {"vcpus": 1, "mem_mib": 512}, "count": 3})

# list, resize, drain, delete — no verbs in paths
flash_pool(method: "GET", path: "/v1/pools")
flash_pool(method: "PATCH", path: "/v1/pools/pool-ab12cd34", body: {"target_count": 5})
flash_pool(method: "DELETE", path: "/v1/pools/pool-ab12cd34")

# claim an idle member on its own endpoint
flash_cli(args: ["claim", "pool-ab12cd34-0001", "--entry", "/your/workload", "--cpu-millis", "1000"])

A claim's --cpu-millis and --disk-mib are optional (omitted = uncapped). shape.nics holds at most one {"kind":"nat","mbps_up"?,"mbps_down"?,"pps"?}.

Restore-via-claim: skip the cold boot on a warm spare

A VM booted with --pool parks at Ready instead of running a workload. claim --from hands that spare a snapshot to become instead of a program to run — the spare's own process is reused, so the restore pays no spawn or privilege-drop cost. arm64 hosts only.

# tool call
flash_cli(args: ["claim", "spare1", "--from", "/var/tmp/myvm.snap",
  "--bundle", "/opt/flashvmm/bundles/current", "--identity", "myvm", "--tenant", "acme"])

# raw HTTP, the same request flash_api makes
curl --unix-socket /run/flashvm/spare1.sock -X POST http://localhost/v1/flashvm/claim \
  -H 'content-type: application/json' \
  -d '{"snapshot_path":"/var/tmp/myvm.snap","bundle_dir":"/opt/flashvmm/bundles/current",
       "identity":"myvm","tenant":"acme"}'

--identity must match the identity the snapshot was captured under; --tenant is the restored VM's own. Add --cpu-millis / --disk-mib (cpu_millis / disk_cap_mib) only to cap the claimed workload. Like every claim, this returns once the request is accepted — poll flash_inspect for entry_started / state.

Operational guidance

FlashVMM returns specific errors with a direct corrective action. These are the responses an agent should recognize and handle.

Get started