Add Firecracker backend for Linux VM isolation #342

New Issue

2026-07-11T09:50:03-04:00

didericis-claude commented

2026-07-11 09:50:03 -04:00

Summary

Replace the smolmachines backend on Linux with a Firecracker-based backend. smolmachines/libkrun has fundamental issues on Linux (see #332) that make it unsuitable:

TSI networking dies under sustained use — all loopback connections hang permanently after a period of activity
Exec channel contention — smolvm machine exec -i -t serializes all exec callers
No native SIGWINCH forwarding — requires a custom resize bridge

Firecracker provides mature, KVM-based microVM isolation on Linux. Combined with macOS Containers on macOS, this gives VM-level isolation on both platforms using well-maintained VMMs.

Design

Guest communication: SSH over TAP

Per-bottle SSH key pair generated at launch time
Public key injected into the ext4 rootfs
All exec/cp_in operations go through SSH over the TAP network
Interactive sessions use ssh -t for PTY allocation

Networking: TAP + bridge per bottle

Per-bottle Linux bridge (bb-<slug>) with a /30 subnet
TAP device (tap-<slug>) attached to the bridge
VM gets a static IP, gateway is the bridge IP
Sidecar bundle publishes ports on the bridge IP
iptables rules restrict VM to only reach the bridge IP (sidecar services)

Rootfs: Docker image → ext4

docker create + docker export to get the filesystem tarball
Create ext4 image, mount, extract
Inject init script + SSH config + authorized_keys
Cache by Docker image digest

Kernel

Configurable path, default ~/.cache/bot-bottle/firecracker/vmlinux
Preflight downloads from Firecracker releases if not present

Sidecar

Reuse the existing Docker-based sidecar bundle (egress, git-gate, supervise)
Publish ports on the bridge IP instead of loopback alias

Scope

Linux-only (Firecracker requires KVM)
macOS continues to use macOS Containers
Backend selection: --backend=firecracker or auto-selected on Linux when available

Acceptance criteria

BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent> launches a Firecracker VM
Agent can reach sidecar services (egress proxy, git-gate, supervise)
Agent is isolated from host network
Cleanup tears down VM, TAP, bridge, and sidecar
Unit tests for plan resolution, argv construction, cleanup enumeration

## Summary Replace the smolmachines backend on Linux with a Firecracker-based backend. smolmachines/libkrun has fundamental issues on Linux (see #332) that make it unsuitable: 1. **TSI networking dies under sustained use** — all loopback connections hang permanently after a period of activity 2. **Exec channel contention** — `smolvm machine exec -i -t` serializes all exec callers 3. **No native SIGWINCH forwarding** — requires a custom resize bridge Firecracker provides mature, KVM-based microVM isolation on Linux. Combined with macOS Containers on macOS, this gives VM-level isolation on both platforms using well-maintained VMMs. ## Design ### Guest communication: SSH over TAP - Per-bottle SSH key pair generated at launch time - Public key injected into the ext4 rootfs - All exec/cp_in operations go through SSH over the TAP network - Interactive sessions use `ssh -t` for PTY allocation ### Networking: TAP + bridge per bottle - Per-bottle Linux bridge (`bb-<slug>`) with a /30 subnet - TAP device (`tap-<slug>`) attached to the bridge - VM gets a static IP, gateway is the bridge IP - Sidecar bundle publishes ports on the bridge IP - iptables rules restrict VM to only reach the bridge IP (sidecar services) ### Rootfs: Docker image → ext4 - `docker create` + `docker export` to get the filesystem tarball - Create ext4 image, mount, extract - Inject init script + SSH config + authorized_keys - Cache by Docker image digest ### Kernel - Configurable path, default `~/.cache/bot-bottle/firecracker/vmlinux` - Preflight downloads from Firecracker releases if not present ### Sidecar - Reuse the existing Docker-based sidecar bundle (egress, git-gate, supervise) - Publish ports on the bridge IP instead of loopback alias ## Scope - Linux-only (Firecracker requires KVM) - macOS continues to use macOS Containers - Backend selection: `--backend=firecracker` or auto-selected on Linux when available ## Acceptance criteria - `BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>` launches a Firecracker VM - Agent can reach sidecar services (egress proxy, git-gate, supervise) - Agent is isolated from host network - Cleanup tears down VM, TAP, bridge, and sidecar - Unit tests for plan resolution, argv construction, cleanup enumeration

didericis referenced this issue from a commit

2026-07-11 10:33:01 -04:00

feat(firecracker): add Linux microVM backend to replace smolmachines

didericis-claude referenced a pull request that will close this issue

2026-07-11 10:33:21 -04:00

feat(firecracker): Linux microVM backend to replace smolmachines #343

didericis referenced this issue from a commit

2026-07-11 13:24:56 -04:00

feat(backend): remove smolmachines; firecracker is the Linux default

Sign in to join this conversation.