Firecracker on Linux (experimental)

grain can launch sandboxes with Firecracker instead of QEMU.

Status: experimental. This page is the supported operator path for trying Firecracker today. It is not a production-hardened backend: no SLIRP/hostfwd networking, no jailer, limited image story, and several QEMU features are missing. Default remains hypervisor: qemu. The mock backend is unchanged for unit tests.

macOS, hosts without the Firecracker binary, and hosts without a usable /dev/kvm fail with clear errors (grain doctor and create both surface KVM issues).

When to use this path

Use Firecracker (experimental) when…	Prefer QEMU when…
You are on Linux with KVM and want a microVM backend	You need the default product path (macOS or Linux)
You bring your own FC kernel + raw rootfs	You want catalog images (`grain-ubuntu`, `ubuntu-cloud`) with SSH
You accept vsock-only agent access (no hostfwd)	You need publish ports, SSH, overlay, mounts, proxy, GPU

Quick config

yaml

# ~/.grain/config.yaml
hypervisor: firecracker
firecracker_binary: firecracker   # PATH lookup (default)
kernel_path: ""                   # optional; default ~/.grain/kernels/vmlinux

Key	Default	Meaning
`hypervisor`	`qemu`	Set to `firecracker` to select this backend (daemon restart after change)
`firecracker_binary`	`firecracker`	Absolute path or name on `PATH`
`kernel_path`	empty	Guest vmlinux; empty → `~/.grain/kernels/vmlinux` (under `data_dir`)

See Configuration.

Requirements

Dependency	Notes
Linux	Firecracker is Linux-only (`KVM`). On macOS: `firecracker requires linux`.
firecracker binary	On `PATH`, or set `firecracker_binary`
Guest kernel (`vmlinux`)	Uncompressed Linux kernel built for Firecracker (virtio MMIO, no PCI). Default path: `~/.grain/kernels/vmlinux` or `kernel_path`
Raw rootfs	Firecracker root drives are raw block files, not qcow2
qemu-img	Used to convert qcow2 → raw when the VM disk is a qcow2 overlay (`grain doctor` flags if missing)
KVM	`/dev/kvm` accessible to the grain daemon user (required — no TCG fallback)
Nested virt	If grain runs inside a VM, the outer hypervisor must expose `vmx` (Intel) or `svm` (AMD) so `/dev/kvm` exists in the guest

Operator checklist

Linux host with /dev/kvm RDWR for the daemon user (add user to kvm group if needed).
Install Firecracker and put it on PATH (or set firecracker_binary).
Place a Firecracker-capable vmlinux at ~/.grain/kernels/vmlinux or set kernel_path.
Prefer a raw rootfs image (grain image import ./rootfs.ext4 --id my-fc-rootfs), not catalog qcow2 cloud images.
Set hypervisor: firecracker in ~/.grain/config.yaml, then grain up (restart daemon if it was already running).
Run grain doctor and fix every ✗ before grain new.

`grain doctor` (Firecracker)

With hypervisor: firecracker in config:

bash

grain doctor

Check	Severity	What it means
`firecracker` (or `firecracker_binary`)	Hard	Binary missing, or not Linux
`/dev/kvm`	Hard	Missing or not RDWR — Firecracker cannot start
Nested virt CPU flags	Soft (`·`)	Host looks like a VM without `vmx`/`svm`
Firecracker kernel	Soft (`·`)	Missing `kernel_path` / default `vmlinux` — Start will hard-fail later
`qemu-img`	Hard	Needed to convert qcow2 disks to raw at Start
QEMU system binary	Soft	Optional when hypervisor is firecracker
Base image / agent / socket	Same as QEMU path	Image ready, optional agent binary, daemon up

Hard failures print ✗ and exit non-zero. Soft items print · and do not fail doctor.

If grain new fails, prefer the create error and ~/.grain/logs/<name>.log over later agent/vsock messages — Firecracker often exits immediately when KVM is unavailable (firecracker exited immediately + KVM hint).

Image / rootfs notes

grain’s catalog images (ubuntu-cloud, grain-ubuntu) are qcow2 cloud images aimed at QEMU + cloud-init. For Firecracker:

Prefer a raw golden rootfs (ext4/squashfs layout that boots with the FC kernel’s root=/dev/vda).
If the VM disk is still qcow2, Start runs qemu-img convert -O raw into disk.raw under the VM dir (when qemu-img is available). Otherwise Start refuses with a conversion hint.
Standard Ubuntu cloud images need a matching Firecracker-capable kernel; they are not drop-in FC guests without extra work (kernel + init + virtio drivers).

See also Images for the QEMU/golden workflow; FC is a separate experimental path.

Suggested layout

text

~/.grain/
  kernels/
    vmlinux              # Firecracker guest kernel
  config.yaml            # hypervisor: firecracker
  vms/<name>/
    disk.raw             # rootfs (converted or imported)
    firecracker.json     # generated config
    firecracker.sock     # FC API unix socket
    fc-vsock.sock        # host end of virtio-vsock
    firecracker.pid

Networking and agent

This backend is CNI-less / TAP-less: no SLIRP, no hostfwd, no SSH port, no overlay network, no egress-proxy hostfwd path.

Channel	Status
SSH / port forwards (`-P`, `grain fwd`)	Not configured (experimental)
Overlay / shared L2	Not used
grain-agent	Firecracker vsock only

On Start, grain:

Sets SSHPort / AgentPort to 0 (no TCP hostfwd)
Allocates a guest CID (AgentCID, same allocator as QEMU vsock)
Configures Firecracker vsock with uds_path = …/fc-vsock.sock

Firecracker’s host-side vsock is not AF_VSOCK//dev/vhost-vsock. Host clients connect to the UDS and send CONNECT <port>\n (see Firecracker vsock docs). Guest agent listens on AF_VSOCK port 7475.

QEMU’s agent_transport: auto|tcp|vsock path (vhost-vsock / TCP hostfwd) does not apply here. Full CLI grain agent dial over FC UDS may need a small host connector; the guest agent binary is unchanged.

For the QEMU networking model (SLIRP, publish, live forwards), see Networking.

Start / stop / pause

Operation	Behavior
Start	Writes `firecracker.json`, runs jailer-less `firecracker --api-sock … --config-file …`
Stop	`SendCtrlAltDel` via FC API, then SIGTERM/SIGKILL
Pause / Resume	`PATCH /vm` with `Paused` / `Resumed` when the API socket is up
SaveVM / suspend snapshot	Unsupported (`savevm is not supported for firecracker`)

Logs: ~/.grain/logs/<name>.log (Firecracker stdout/stderr). grain logs --qemu <name> shows that hypervisor log (name is historical).

Cloud-init seed

If seed.iso exists in the VM dir, it is attached as a second read-only drive (cidata). NoCloud typically expects a labeled ISO/FAT volume; success depends on the guest image. Prefer baking keys/agent into a FC-oriented rootfs for reliable boots.

Example