Architecture

The process model

One process, one VM. Every FlashVM has its own address space, device model, vCPU threads, and crash boundary. There is no shared VMM process connecting otherwise independent guests.

One socket, one API. Each process serves its control API over a Unix socket rather than a network port. Standard Linux file permissions govern access, without adding a separate application credential or authentication service.

A standalone deployment. FlashVMM ships as a self-contained binary. It does not depend on another product's repository, CDN, signing infrastructure, or update service to run.

flowchart TB
  subgraph Host
    CLI["flash CLI"]
    MCP["flash-mcp
(MCP server, stdio JSON-RPC)"]
    NET["flashnet
(privileged network helper)"]
    subgraph VM_A["flashvmm process — VM A"]
      SockA["unix socket
/run/flashvm/A.sock"]
      VcpuA["vCPU threads"]
      DevA["virtio-blk · virtio-net · virtio-console
virtio-balloon · virtio-mem · virtio-rng
virtio-9p"]
    end
    subgraph VM_B["flashvmm process — VM B"]
      SockB["unix socket
/run/flashvm/B.sock"]
      VcpuB["vCPU threads"]
      DevB["virtio devices"]
    end
  end
  CLI -->|spawn + exec, once at creation| VM_A
  CLI -->|spawn + exec, once at creation| VM_B
  CLI -->|HTTP, every command| SockA
  CLI -->|HTTP, every command| SockB
  MCP -->|HTTP + SSE| SockA
  MCP -->|HTTP + SSE| SockB
  NET -->|creates TAP, drops caps, execs| CLI
        

Cross-host live migration

FlashVMM moves a running VM through three ordinary operations: capture, transfer, and restore. Capture freezes the guest and writes its vCPU registers, memory maps, and device state to a snapshot. That snapshot can then be moved to another physical host and resumed there.

CPU templates make compatibility explicit. A template masks host-specific CPU differences and defines the feature set presented to the guest. Before restore, FlashVMM checks the destination against that contract and refuses to proceed if a promised feature is unavailable.

sequenceDiagram
  participant HA as Host A
  participant File
  participant HB as Host B
  HA->>HA: POST /v1/flashvm/snapshots (running VM)
  HA->>File: write snapshot
  File->>HB: move
  HB->>HB: PUT /v1/flashvm (source: Snapshot)
  HB->>HB: CPU template checked, fail-closed
  Note over HB: refused if a promised
CPU feature is missing
        

One control surface for operators and agents

flash-mcp exposes the FlashVMM lifecycle through ten operational tools. Any MCP-compatible model can create and manage VMs, follow live telemetry, adjust resource limits, and run diagnostics through the same API used by the CLI. There is no separate automation layer to configure or keep in sync.

flowchart LR
  subgraph Agent["Any MCP-speaking LLM"]
    C["Claude"]
    G["ChatGPT"]
    M["Gemini"]
    O["..."]
  end
  Agent -->|stdio JSON-RPC| MCP["flash-mcp"]
  MCP -->|HTTP + SSE| SockA["unix socket
/run/flashvm/A.sock"]
  MCP -->|HTTP + SSE| SockB["unix socket
/run/flashvm/B.sock"]
  SockA --> VMA["FlashVM A"]
  SockB --> VMB["FlashVM B"]
        

Control surface

FlashVMM uses HTTP/1.1 over AF_UNIX, with one socket per VM: /run/flashvm/<id>.sock for root, or $XDG_RUNTIME_DIR/flashvm/<id>.sock for an unprivileged user. The API, CLI, and MCP server are three ways into the same control surface.