Skip to main content

​
The stack

┌──────────────────────────────────────────────────────────────┐
│  Your code / agent framework (Python, TS, MCP client)        │
└──────────────────────────────────────────────────────────────┘
                              │ HTTPS
┌──────────────────────────────────────────────────────────────┐
│  hostd (Rust, axum) — REST+NDJSON on the Hetzner host        │
│  · POST /v1/sandboxes      → FirecrackerExecutor::create     │
│  · POST /.../exec          → vsock UDS round-trip to agent   │
│  · POST /.../fork          → diff-snapshot + rebase + spawn  │
│  · POST /.../merge_into    → VmHandle swap                   │
│  · DELETE /.../            → SIGKILL + rm -rf vm_dir         │
└──────────────────────────────────────────────────────────────┘
                              │ spawns + vsock UDS
┌──────────────────────────────────────────────────────────────┐
│  podflare-firecracker (patched Firecracker v1.15.1)          │
│  · vsock_uds_path_override, drive_overrides (our patch)      │
└──────────────────────────────────────────────────────────────┘
                              │ KVM
┌──────────────────────────────────────────────────────────────┐
│  Guest microVM (Ubuntu 24.04 minimal, Linux 6.1)             │
│  ┌───────────────────────────────────────────────────────┐   │
│  │ podflare-agent (Rust)                                 │   │
│  │  · AF_VSOCK listener on port 5555                     │   │
│  │  · Spawns persistent Python REPL at boot              │   │
│  │  · Mutex-serializes run_code calls                    │   │
│  ├───────────────────────────────────────────────────────┤   │
│  │ Python 3.12 REPL (runner embedded in agent)           │   │
│  │  · globals() dict — your variables + imports live     │   │
│  │  · Streaming JSON event protocol to the agent         │   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

​
Data plane

  • Rootfs: per-VM xfs reflink of /var/lib/podflare/base.ext4. CoW isolated at the xfs block level.
  • Memory: all VMs MAP_PRIVATE the same seed.mem → pages are shared across VMs until first write; dirtied pages are COW to per-VM anonymous memory.
  • Vsock: one UDS per VM (our patch lets each restored snapshot bind a fresh path). hostd → CONNECT 5555 → guest agent.

​
Control plane

  • Warm pool — pool_manager keeps N VMs pre-booted via snapshot restore (~12 ms per VM).
  • Fork — Diff snapshot of parent + reflink seed.mem + rebase-snap merge + spawn N children in parallel.
  • Merge — VmHandle swap under the parent’s id.

​
Substrate

ComponentChoiceWhy
VMMFirecracker 1.15.1 (patched)KVM hardware isolation, fast snapshot restore
GuestUbuntu 24.04 minimalbroad userspace, pre-built stdlib, small enough
Guest kernelLinux 6.1.155matches Firecracker CI, UFFD available for Phase 4
Host FSxfs with reflink=1metadata-only CoW for rootfs clones
Host OSUbuntu 24.04 on Hetzner bare metalreal KVM, no nested-virt tax

​
See also

Firecracker fork

The 187-line patch that unlocks concurrent fork

Performance

Every latency number, measured