Architecture and process model

The FlashVMM architecture is a one-process-per-VM design: each FlashVM is a separate flashvm process on the platform's native hypervisor (KVM, Hypervisor.framework, Virtualization.framework or the Windows Hypervisor Platform) that serves its own REST API over its own Unix socket or named pipe, with single-purpose daemons around it for pools, hosts, networking and GPUs.

No daemon sits between flash and a VM: every command is an HTTP request to that VM's own address. The flashvm process owns the VM's address space, vCPU threads and virtio devices, so one VM's crash, limits and permissions are its own. Services that span VMs each have one job and one socket: flashpoold for warm pools and the host view, flashhostd for the host as a whole, flashnetd for NIC pools, flashgpud for GPU pools, and flash controller for placement across hosts.

Key facts

How it works

Creating a VM

1. flash run (or restore, clone) validates the request and spawns a flashvm process for the VM, named by its id.
2. The process binds its API socket, then hardens itself. On Linux it drops every capability with capset, sets PR_SET_NO_NEW_PRIVS and PR_SET_DUMPABLE=0, and sets RLIMIT_CORE=0 and a file-descriptor ceiling; the userfaultfd used for restore is opened before the drop.
3. flash sends PUT /v1/flashvm to that socket with a tagged source: bundle (cold boot from a kernel and root filesystem), snapshot (a file on this host) or snapshot_url (a demand-paged remote object).
4. The VMM maps guest RAM, loads the kernel, attaches virtio devices and starts the vCPUs. The guest agent runs as PID 1 and reports Ready over its control channel; the VMM then hands it the workload.

Running it

Every later command (exec, checkpoint, set, snapshot, stop) is a REST call to the same socket. flash ls lists the sockets in the registry; flash rm stops the process, and the socket disappearing is the signal the VM is gone. Access is governed by the operating system's own permissions on the socket or pipe.

Around it

Each daemon serves one job over one socket. flashpoold keeps warm pools of parked spares at /v1/vm-pools and serves the host view behind flash host. flashhostd serves the host API, including sleeping VMs at /v1/host/sleep-images. flashnetd serves NIC pools on Linux, flashgpud serves GPU pools, and flash controller serve places VMs across many hosts using the same binary in another role. See pools, host and controller.

Engines

Each OS uses its native hypervisor: Linux uses KVM; macOS uses Hypervisor.framework (engine hvf, the default) or Virtualization.framework (engine vz); Windows uses the Windows Hypervisor Platform (engine whp). All of them serve the same contract from the shared flash-contract crate. See platforms and the API contract.

Interfaces

CLI

flash run --bundle ./bundle --id web --vcpus 1 --mem-mib 256 --entry 'sleep 3600' --detach
flash ls
flash inspect web
flash version web
flash rm web

MCP

flash_cli(args: ["run", "--bundle", "./bundle", "--id", "web", "--vcpus", "1", "--mem-mib", "256", "--entry", "sleep 3600", "--detach"])
flash_ls()
flash_inspect(vm_id: "web")
flash_resource(vm_id: "web", resource: "version")

REST

PUT    /v1/flashvm          {"source": {"type": "bundle", "bundle_dir": "./bundle"}, "vcpus": 1, "mem_mib": 256, "entry": "sleep 3600"}
GET    /v1/flashvm
GET    /v1/flashvm/version
DELETE /v1/flashvm

Contract: a second create on a socket returns 409 already_exists; an engine the host lacks returns 422 unsupported_engine; a call to a VM that has exited returns 409 vm_gone.

Guarantees

• One crash boundary per VM. Address space, vCPU threads and devices belong to that VM's process alone.
• Direct control. Every command reaches the VM's own socket; nothing shared sits on the path.
• OS-native access control. Socket and pipe permissions decide who may drive a VM.
• One job per daemon. Pools, hosts, NICs, GPUs and placement each have their own service and API.