Crate cellos_host_firecracker 

Firecracker-backed host backend (L2-06).

Architecture

FirecrackerCellBackend implements the CellBackend trait by managing one Firecracker VMM process per cell:

1. create — spawns firecracker --api-sock <socket>, waits for the socket to appear, then calls the Firecracker Management API to configure the machine (vCPUs, memory, kernel, rootfs) and boot it.
2. destroy — sends a graceful SendCtrlAltDel action, waits for the process to exit, and cleans up the socket file.

Cell command execution

The Firecracker path now runs spec.run.argv inside the guest via the cellos-init PID-1 binary and a vsock exit-code bridge:

1. The host encodes spec.run.argv into the kernel boot args as cellos.argv=<base64-json>.
2. The VM is configured with a vsock device and the host starts a matching Unix-socket listener.
3. cellos-init reads /proc/cmdline, forks and execs the workload inside the guest, then writes the 4-byte little-endian exit code back to the host over vsock before powering off the VM.
4. The supervisor calls CellBackend::wait_for_in_vm_exit() and skips the host-side subprocess path when this backend reports an in-VM exit code.

The host-side subprocess fallback still exists for backends that do not override wait_for_in_vm_exit(), but it is no longer the execution path for FirecrackerCellBackend.

Modules

api_client

Minimal Firecracker Management API client (HTTP/1.1 over Unix domain socket).

pool

Pre-booted Firecracker VM pool — L2-06-2.

Structs

FirecrackerCellBackend

Firecracker-backed CellBackend (L2-06).

FirecrackerConfig

Constants

VSOCK_EXIT_PORT

vsock port that cellos-init inside the VM connects to after the cell command exits. Must match the constant in cellos-init/src/main.rs.

Functions

drain_pending_manifest_failed_events

Drain pending manifest-failed events (consume-on-drain).

push_manifest_failed_pending_for_test

Emit a manifest-failed CloudEvent onto the pending buffer. Public for supervisor drain + FC-51 emission tests; the digest-mismatch branch in verify_artifacts calls this with the live verification context.