Firecracker Runtime

The repository builds deterministic Firecracker configuration and can launch a real Firecracker process on Linux/KVM. macOS development still uses dry-run artifact planning without touching KVM.

Model

The DevCell config model covers:

• machine id, vCPU, memory, and workspace disk size;
• kernel image and boot args;
• rootfs and workspace block devices;
• vsock path and guest CID (allocator bumps on collision);
• TAP network identity (tap-<short-id>), created on start and deleted on destroy;
• jailer uid, gid, chroot base, and staged jail root (…/jailer/firecracker/<id>/root);
• socket, log, and metrics paths;
• workload metadata derived from WorkspacePlan;
• runtime descriptor paths for config, metadata, vsock, API socket, TAP name, block devices, logs, metrics, and jailer dir.

BuildLaunchPlan converts that model into an official Firecracker --config-file JSON (vmconfig.json) plus argv. With jailer launch enabled (root / DEVCELL_FC_JAILER_LAUNCH=1), argv is wrapped as jailer … -- --api-sock /firecracker.sock --config-file /vmconfig.json.

machineMachineSpec

workspaceWorkspacePlan

applianceHost paths

buildConfig builderdeterministic model

→

artifactsRuntime descriptorconfig · vmconfig · paths

→

consumerLinux backendTAP · vsock · jailer/FC

What It Proves

Golden tests make generated config, runtime descriptors, and host vmconfig.json stable and reviewable. Dry-run tests create the per-cell runtime layout without touching KVM. On Linux with /dev/kvm and CAP_NET_ADMIN, celld --backend=firecracker creates TAP devices, opens vsock UDS, stages a jail chroot (kernel + per-cell rootfs copy), and starts a microVM. Destroy removes the TAP, vsock sockets, and cell directory.

Orphan reconcile

On celld startup, the Firecracker backend reconciles persisted runtime dirs against live host state:

1. Load per-cell runtime.json descriptors from <data>/firecracker-runtime/cells/.
2. Scan /proc for firecracker / jailer processes whose cmdline references the runtime dir.
3. Kill orphan processes (cells not desired running, or unknown runtime paths).
4. Delete DevCell TAP devices (tap-* / dc<hex>) not owned by a desired running cell.
5. Remove vsock UDS files for stopped / non-running cells.
6. Mark cells failed when the store expects running but no live process is found; emit firecracker.* audit events.

Unit tests inject fake process and TAP lists; integration tests that create real TAPs still require root / CAP_NET_ADMIN.

Artifact resolution

celld resolves guest media from flags, DEVCELL_FC_* env vars, then the appliance images/ directory:

1. CellOS names: vmlinux, cellos.ext4, optional initrd
2. Fallback pin names: rootfs.ext4 (from firecracker-ci-rootfs-ext4)

Binary: --fc-bin, DEVCELL_FC_BIN, or firecracker on PATH (appliance packages include Firecracker). Jailer: DEVCELL_FC_JAILER_BIN or jailer on PATH.

Concurrent cells

Each cell gets its own writable drives/rootfs.ext4 copy (and a second copy inside the jail root when jailer staging is on). Two cells must not share one RW overlay. Unit coverage: TestPrepareRuntimeConcurrentCellsDistinctRootfs. Integration (root + KVM): TestIntegrationTwoCellSmokeSkipsWithoutKVM.

Jailer launch policy

• Always (when EnableJailer): stage <cell>/jailer/firecracker/<id>/root/{vmlinux,rootfs.ext4,vmconfig.json} with jail-relative paths.
• Launch via jailer: only when geteuid()==0 or DEVCELL_FC_JAILER_LAUNCH=1 (jailer needs privileged chroot/cgroup setup). Otherwise Firecracker starts directly with host-path vmconfig.json under the cell dir; TAP + vsock still apply.
• Netns / fine-grained cgroups: optional hooks exist (NetNSPath, --cgroup-version 2); full netns-per-cell remains a follow-up.

Remaining gaps

• Workspace drive in Firecracker config until a real ext4 image exists
• Guest cell-agent vertical slice over vsock (host dial wired; needs rebuilt CellOS rootfs for green exec)
• Bridge/NAT beyond isolated TAP