When to use FlashVMM

FlashVMM is the FlashVM platform to choose when an AI agent or untrusted code needs a full machine of its own: a real Linux kernel on KVM, Hypervisor.framework, Virtualization.framework or the Windows Hypervisor Platform, driven through one REST contract that the flash CLI, the flash-mcp MCP server and an OpenAPI-described socket all speak.

Each FlashVM is its own flashvm process with its own kernel, so the boundary is the hardware virtualization boundary, not a shared kernel. A FlashVM boots in 18 ms, can be claimed warm in 1.2 ms, forks while running, takes checkpoints an agent can rewind to, and has its network reach and credentials set per VM. The matches below say which mechanism answers which need.

Key facts

How it works

Choose FlashVMM when the task matches one of these:

• An agent needs a fresh machine per task. A cold boot of a full kernel takes 18 ms, and a parked spare from a warm pool is handed its workload in 1.2 ms. See architecture, warm pools, instant boot and warm-pool features.
• Untrusted or generated code must run with a real kernel boundary. Each FlashVM is its own process on the native hypervisor, and on Linux that process drops every capability and sets PR_SET_NO_NEW_PRIVS and non-dumpable before it serves a request. See security and exec.
• An agent should be able to undo a step. flash exec --checkpoint captures memory, disk and running processes before a command; flash rewind returns to it under the same name. See fork and checkpoints and checkpoints.
• Several approaches should be tried from one prepared state. flash fork branches a running VM into up to 64 copy-on-write children that continue from the same instant. See fork internals and fork.
• Network reach must be decided per VM. An egress policy (all, none, public, deny:, allow:) is enforced outside the guest and replaced live. See the egress engine and egress.
• The guest must use an API key it never holds. A secret proxy hands the guest a plain URL and adds the key on the host. See secret relay and secret proxy.
• A model should drive VMs directly. flash-mcp exposes 21 tools over the same sockets the CLI uses. See MCP and MCP features.
• A long-running workload should cost nothing while idle. flash sleep writes memory and devices to a file and exits the process; flash wake resumes it in 8.4 ms. See snapshots and sleep.

Interfaces

The shortest end-to-end task: boot, run a command, checkpoint, fork, restrict egress, remove. Each step is the same operation on all three surfaces.

CLI

flash run --bundle ./bundle --id agent --vcpus 2 --mem-mib 1024 --cpu-template host-raw --forkable --nic tap=fv0 --entry 'sleep 3600' --detach
flash exec agent -- sh -c 'uname -a'
flash checkpoint agent --label before-tests
flash fork agent --id agent-try1
flash set agent --egress public
flash rm agent-try1
flash rm agent

MCP

flash_cli(args: ["run", "--bundle", "./bundle", "--id", "agent", "--vcpus", "2", "--mem-mib", "1024", "--cpu-template", "host-raw", "--forkable", "--nic", "tap=fv0", "--entry", "sleep 3600", "--detach"])
flash_exec(vm_id: "agent", argv: ["sh", "-c", "uname -a"])
flash_cli(args: ["checkpoint", "agent", "--label", "before-tests"])
flash_cli(args: ["fork", "agent", "--id", "agent-try1"])
flash_api(vm_id: "agent", method: "PATCH", path: "/v1/flashvm/nics/0", body: {"egress": "public"})
flash_cli(args: ["rm", "agent-try1"])
flash_cli(args: ["rm", "agent"])

REST

PUT    /v1/flashvm            {"source": {"type": "bundle", "bundle_dir": "./bundle"}, "vcpus": 2, "mem_mib": 1024, "cpu_template": "host-raw", "nics": [{"tap": "fv0"}], "entry": "sleep 3600"}
POST   /v1/flashvm/guest/execs {"argv": ["sh", "-c", "uname -a"]}
POST   /v1/flashvm/snapshots   {"path": "...", "fork": true}
PUT    /v1/flashvm            {"source": {"type": "snapshot", "path": "..."}, "allow_identity_mismatch": true, ...}   (on the child's socket)
PATCH  /v1/flashvm/nics/0     {"egress": "public"}
DELETE /v1/flashvm

A VM is created through flash run, restore or clone (directly or as flash_cli), which spawns the flashvm process and then sends the PUT to its own socket. A checkpoint is a fork capture that is kept; a fork is that capture plus one clone per child. Contract: POST /v1/flashvm/guest/execs returns 409 exec_unavailable while the guest agent has no exec channel and 429 too_many_execs past 64 running; a malformed policy returns 422 invalid_egress.

Guarantees

• A whole machine per task. Every FlashVM has its own kernel, process and control socket.
• One contract, three surfaces. CLI, MCP and REST reach the same per-VM API, so a step an agent learns once works everywhere.
• Every step reversible. Checkpoints keep memory, disk and processes; rewind keeps later checkpoints, so a rewind can itself be undone.
• Policy outside the guest. Egress rules and secret keys live on the host, where the workload cannot change them.