[fctl-sh]

Summary

Linux hosts can now run each session in a Firecracker microVM with a kernel of its own (fctl host install --driver firecracker), from the same images as Docker and with nothing running as root: the host's user needs /dev/kvm (the kvm group), passt and e2fsprogs, and the host downloads the rest itself. ADR 0070 records the design and docs/architecture.md#firecracker the details:

• Images: the host pulls them from their registries (digests checked; anonymous or with docker login's credentials) and unpacks the layers in a short-lived VM, as root there, so owners and setuid bits survive and no image file touches the host's filesystem. Sandboxes share their image's filesystem read only, each with its own sparse ext4 disk laid over it; stopping keeps the disk, resuming boots from it.
• fctl-agent is the VM's init (crates/fctl-agent/src/vm): it switches to that root, sets the system up, reaps, and runs what the host asks over the vsock as docker exec would (fctl_proto::vm).
• Network: a TAP device inside the VM whose frames fctl-agent carries over the vsock to a passt per VM on the host, with no bridge, TAP or firewall rule on the host.
• Assets: Firecracker 1.17.0 (pinned SHA-256) from its GitHub release, and the kernel image ghcr.io/hyperstructure/sandbox-kernel:6.18.59 from the linked sandbox pull request. Firecracker and passt run in their own process groups, so restarting or updating the host leaves sessions running.

Driver::spawn now returns pipes and an exit code (Running) rather than a child process, since a VM's programs aren't the host's children; Claude sign-in works as before. What the driver leaves for later (package caches, builds, the jailer, snapshots, CI with KVM) is in #345.

Unit tests cover the protocol, the init (whiteouts, users, netlink), the registry client, the image store and the VM configuration. CI has no KVM, so I verified on Firecracker nested in an aarch64 VM under QEMU here: the opt-in cargo test -p fctl-host boots_a_sandbox -- --ignored (boot, user and hostname, DNS and HTTP out, piped programs, fctl-agent, stop and restart from disk), and sessions end to end from cargo xtask dev on a Firecracker runner: start, follow-ups, stop, resume from the disk, and a host restart with the VM running, which it recovered. I pulled images from Docker Hub, ghcr.io and a local registry, and booted the real default image (ghcr.io/hyperstructure/sandbox:latest): Claude Code, gh and Node run as agent, and nproc and free show the VM's size. I booted both Firecracker CI's kernel and the sandbox pull request's 6.18.59, whose Kernel workflow also booted the x86_64 build on a GitHub runner with KVM. Not tried: the driver on an x86_64 host, an Ubuntu host (its AppArmor profile for passt allows these socket paths, by reading it), and Claude sign-in.

Merge order

Merge the sandbox pull request first: its Kernel workflow publishes the kernel this driver pulls by default. The fctl-site pull request shows the driver on fctl.sh's landing and sandboxes pages; merge it with or after this one.

• feat: build and publish the kernel of fctl's Firecracker sandboxes sandbox#12
• feat(landing): show Firecracker microVMs as a sandbox for Linux runners fctl-site#95

Worth confirming

• Decision: --driver auto never picks Firecracker: a host's owner chooses it, so updating fctl changes no host's driver.
• Decision: Firecracker runs as the host's user, without its jailer (which needs root), so a VM escape would land as that user, as a container escape can with Docker. The security page says so.
• Decision: no package caches and no image builds (allowed_builds) with this driver for now; projects' own images run.
• Decision: each sandbox gets a sparse 64 GiB disk ([firecracker] disk_gb in host.toml), which takes what the session writes and gives back what it deletes.
• Decision: VMs reach the internet and the host's network as Docker containers do, but not each other or the host's loopback.
• Assumption: joining kvm and installing passt and e2fsprogs is setup enough for "seamless"; the host downloads Firecracker and the kernel itself.

fctl session

---

Note

Medium risk. It adds a whole new sandbox driver that downloads and runs binaries and a kernel, unpacks images as root inside VMs, and changes the shared Driver::spawn interface the Docker driver also uses; it is opt-in, so existing hosts keep working.

What it does. Adds an opt-in Firecracker driver so Linux hosts can run each session in its own microVM instead of a Docker container, from the same images. fctl-agent doubles as the VM's init and runs programs over a vsock, with networking carried through passt and nothing running as root on the host. Driver::spawn now returns pipes and an exit code rather than a child process, and the docs, an ADR and the fctl host commands are updated to match.

Merge order and untested paths. The host pulls the kernel image ghcr.io/hyperstructure/sandbox-kernel:6.18.59, which hyperstructure/sandbox#12 publishes, so that pull request must merge first. CI has no KVM, so the VM paths were only tried by hand on aarch64.

_{fctl review's first look at 32be81c · 37 files, +6005 −82 · Review agent settings}

[fctl-review]

Partly addressed as of 4a7fed9. Later commits fixed 6 of the 7 issues this review found.

---

fctl reviewed 501c1b6 and found 7 issues.

Large, well-documented change. The findings below are from reading the code; the VM paths can't be exercised in CI. Also worth knowing before merge: the default kernel image ghcr.io/hyperstructure/sandbox-kernel:6.18.59 is published only once hyperstructure/sandbox#12 is merged, and it is pinned by a mutable tag while Firecracker itself is pinned by SHA-256.

On lines the diff doesn't show:

• host status reports builds as allowed on a Firecracker host · Low severity · crates/fctl/src/cmd/host.rs line 418: uses_images() is now true for Firecracker, so cfg.images(d.uses_images()) here shows builds as permitted, while the daemon uses builds_images() (session.rs:89) and allows none. The same mixup lets session.rs:658 (ImageWant::Build(_) if ctx.driver.uses_images()) take the build path, which ends in a bail. Use builds_images() where the meaning is builds.

_{Reviewed by fctl · Review agent settings}

[fctl-sh]

On the review's 7th finding (host status and the session path using uses_images() where builds are meant): fixed in 4a7fed9. Status, install's summary, doctor's allowed_builds note and the session's build path now ask builds_images(), which only Docker and Apple's container answer yes to.