LLM-native operations
Give agents the full FlashVM lifecycle.
flash-mcp gives any MCP-compatible agent direct access to FlashVMM creation, control, telemetry, snapshots, restore, and teardown. Each tool call maps to either the flash CLI or HTTP over the VM's own Unix socket, so automation uses the same control path as a human operator. The examples below show both layers side by side. See Developer for installation.
1. Create a VM with flash_cli
VM creation starts a new flashvmm process, so flash-mcp invokes the real flash CLI through flash_cli. Once that process binds its per-VM socket, the agent can manage it directly through the HTTP API. There is no separate flash_create abstraction to keep in sync.
# tool call
flash_cli(args: ["run", "--bundle", "/opt/flashvmm/bundles/current",
"--disk-bps", "104857600", "--disk-iops", "10000",
"--cpu-template", "host-raw", "--entry", "/your/workload", "--id", "myvm"])
# what it runs
flash run --bundle /opt/flashvmm/bundles/current \
--disk-bps 104857600 --disk-iops 10000 --cpu-template host-raw \
--entry /your/workload --id myvm--disk-bps and --disk-iops are explicit creation requirements; 0 is rejected rather than interpreted as unlimited. --cpu-template is optional for execution and required for any VM that will be captured.
2. Attach networking with flashnet
Host networking is established before the VM's control socket exists. flash_cli runs flashnet, the privileged helper that creates the tap, removes its capabilities, and hands execution to an unprivileged flash run. The VMM receives the network device without inheriting network-administration privileges.
# tool call
flash_cli(args: ["run", "--bundle", "/opt/flashvmm/bundles/current", "--id", "myvm",
"--disk-bps", "104857600", "--disk-iops", "10000", "--cpu-template", "host-raw",
"--nic", "tap=tap1,ip=10.110.0.11/24,gateway=10.110.0.1,mbps=1000,pps=100000,ingress-mbps=1000",
"--entry", "/your/workload"])
# what actually sets up the tap, underneath flash_cli
flashnet --mode nat --uplink eth0 --vm-id myvm -- flash run ...After startup, NIC state becomes a standard socket read: flash_resource(resource: "nics") maps to GET /v1/flashvm/nics.
3. Observe the VM in real time
With the process running, control and observation move to HTTP over the per-VM socket. flash_metrics and flash_inspect provide structured views over that same API.
# tool call
flash_metrics(id: "myvm")
# raw HTTP, same call flash_api makes
curl --unix-socket /run/flashvm/myvm.sock http://localhost/v1/flashvm/metricsA metrics call returns a live sample of CPU, memory, disk I/O, and per-NIC traffic. flash_watch turns the same data into an SSE stream and sends progress notifications to the calling agent.
4. Capture the running state
# tool call
flash_api(method: "POST", path: "/v1/flashvm/snapshots", id: "myvm",
body: {"path": "/var/tmp/myvm.snap"})
# raw HTTP
curl --unix-socket /run/flashvm/myvm.sock -X POST http://localhost/v1/flashvm/snapshots \
-H 'content-type: application/json' -d '{"path":"/var/tmp/myvm.snap"}'Snapshots require the VM to have started with --cpu-template. Because a template cannot be added later, select it during creation for any workload that may need capture, restore, or cloning.
5. Restore or clone with flash_cli
Restore creates a new VMM process from the snapshot artifact, so the workflow returns to flash_cli. The process starts with its 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", "--disk-bps", "104857600", "--disk-iops", "10000",
"--cpu-template", "host-raw", "--id", "myvm"])Restore returns the captured VM under its original identity, so --id must match the snapshot. Use flash_cli(args: ["clone", ...]) to create a new VM identity from the same artifact.
6. Stop and remove the VM
# tool call
flash_api(method: "DELETE", path: "/v1/flashvm", id: "myvm")
# raw HTTP
curl --unix-socket /run/flashvm/myvm.sock -X DELETE http://localhost/v1/flashvmThe DELETE request stops the guest, exits its process, and removes the registry entry. Because the socket belongs to that process, the VM no longer appears in flash_ls or flash ls.
flash-mcp tools
Ten tools cover the complete lifecycle and make every FlashVMM API route available to an MCP client.
| Tool | What it does |
|---|---|
flash_ls | Inventory every VM on the host and report its current state |
flash_inspect | Read boot, CPU, memory, disk, NIC, share, and source configuration in one view |
flash_metrics | Return the complete live metrics sample in one call |
flash_diagnose | Produce a structured health report for operational diagnosis |
flash_watch | Stream metrics, logs, lifecycle events, or guest messages with progress notifications |
flash_watch_fleet | Follow multiple VMs concurrently within a bounded connection budget |
flash_resource | Read any of 14 named resources, including CPU, boot, memory, balloon, mem (virtio-mem region), disk, NICs, snapshots, and version |
flash_logs | Read the workload log and guest console together |
flash_api | Send raw HTTP to the socket of an existing VM |
flash_cli | Run any flash subcommand, including workflows that create a new VMM process |
Operational guidance
FlashVMM returns specific errors with a direct corrective action. These are the responses an agent should recognize and handle.
| Error string | Meaning | Action |
|---|---|---|
no kernel in bundle '…' (looked for […]) | The selected bundle does not contain vmlinux, bzImage, Image, or kernel | Point --bundle to a directory containing one of the supported kernel filenames |
restore refused [identity]: snapshot identity mismatch | The requested --id differs from the identity recorded in the snapshot | Restore with the captured --id, or use the explicit identity-mismatch option for an intentional clone |
422 memory_immutable on PATCH /memory | The VM's memory ceiling is fixed at creation | Use PATCH /memory/balloon to reclaim pages within the existing ceiling, or PATCH /memory/mem to resize a region reserved at creation with mem_region_mib |
409 on NIC add/remove after creation | NIC topology is defined when the VM is created | Declare every required NIC during flash run |
no VM at /run/flashvm/ID.sock — is it running? try flash ls | The VM process has exited and its socket is no longer present | Run flash ls to refresh the host inventory before issuing another request |
503 not_ready on a CPU-cap patch | The boot-grace window is still active and the live-update channel is not ready | Retry after boot, or use --boot-grace-ms 0 when the VM is created |
Live context for long-running operations
Metrics, logs, lifecycle events, and guest messages stream over Server-Sent Events on the same per-VM socket used for control. Long-running tools report progress to the calling agent, and an explicit lagged event identifies any gap when a consumer falls behind.