Learn Firecracker - Setup & Installation

#Introduction

In episode 2 we understood Firecracker's architecture: one process per microVM, virtio devices, a Unix socket API, and the jailer. Now it's time to prove that the theory actually works. Episode 3 is the first real stage: installing Firecracker from scratch, verifying the environment, and running firecracker --api-sock for the first time.

Why is this episode important? Because most failures in the episodes that follow are rooted here: mismatched binary versions, KVM not enabled, a wrongly formatted rootfs, or incorrect paths. A correct, verified installation will save you dozens of hours of debugging down the road.

#Installing the Firecracker Binaries

#Downloading the v1.16.x Release

Every practice in this series uses v1.16.x (the latest stable release; v1.16.1 was released on July 2, 2026). Download the archive that matches your host architecture:

ARCH="x86_64" # change to aarch64 for Arm hosts
VERSION="v1.16.1"
wget "https://github.com/firecracker-microvm/firecracker/releases/download/${VERSION}/firecracker-${VERSION}-${ARCH}.tgz"
tar -xzf "firecracker-${VERSION}-${ARCH}.tgz"
sudo cp "release-${VERSION}-${ARCH}/firecracker-${VERSION}" /usr/local/bin/firecracker
sudo cp "release-${VERSION}-${ARCH}/jailer-${VERSION}" /usr/local/bin/jailer

The release archive contains two binaries: firecracker and jailer. Both are statically linked — no runtime dependencies — so you can simply copy them and use them on any host. Verify:

firecracker --version
jailer --version

The output must mention Firecracker v1.16.1 — note this version number because the CVE fixed in this release will be discussed in episodes 14 and 17.

#Verifying KVM and cgroup

Firecracker refuses to run without KVM. Double-check it, because this is the number one cause of failure:

ls -l /dev/kvm
sudo kvm-ok
stat -fc %T /sys/fs/cgroup/

Make sure /dev/kvm exists, kvm-ok prints KVM acceleration can be used, and cgroup uses cgroup2fs. If you have cgroup v1, the jailer and rate limiter still work, but episode 19 about scaling will be far more comfortable on cgroup v2.

#Preparing the Kernel and Rootfs

Firecracker doesn't boot from an ISO or firmware; it loads a kernel binary directly into memory. For our first experiment we need a kernel configured lightly (no VGA console, no unnecessary devices) and a minimal ext4 rootfs.

Download a ready-made kernel from Firecracker's official asset repository, then create an empty rootfs:

mkdir -p ~/fc-demo && cd ~/fc-demo
wget https://s3.amazonaws.com/spec.ccfc.min/img/quickstart_guide/x86_64/kernels/vmlinux.bin
dd if=/dev/zero of=rootfs.ext4 bs=1M count=512
mkfs.ext4 rootfs.ext4

A rootfs that can actually boot (containing an init and minimal tooling) is built in episode 8. For this episode, it's enough to make sure both files exist — vmlinux.bin is the kernel, rootfs.ext4 is an empty ext4 filesystem.

#Running Firecracker for the First Time

#API Mode

Firecracker's default mode exposes an API on a Unix socket and waits for configuration to be sent via curl:

firecracker --api-sock /tmp/firecracker.sock

This process runs in the foreground and waits for API requests. In another terminal, check that the socket exists and the API responds:

curl --unix-socket /tmp/firecracker.sock http://localhost/  -i

A 200 OK response with the body Firecracker API means the control plane is alive. At this point the microVM hasn't booted yet — the API is still waiting for PUT /boot-source, PUT /machine-config, and so on. We'll do that in episode 4.

#--no-api Mode

Firecracker also has a far simpler mode without an API. With --no-api, all configuration is passed as command-line options and the VM boots immediately when the process starts:

firecracker --no-api \
  --kernel ~/fc-demo/vmlinux.bin \
  --root-drive ~/fc-demo/rootfs.ext4 \
  --vcpu-count 1 \
  --mem-size-mib 256 \
  --boot-args "console=ttyS0 reboot=k panic=1 pci=off"

Notice the difference: no socket, no JSON, no InstanceStart — Firecracker executes right away. This mode suits quick experiments or automatic boot at startup, but it's not right for production, which needs control and auditing over configuration. In episode 4 we'll use API mode in full, because that's where all of Firecracker's power lives.

#Comparing Modes: API vs --no-api

The --no-api mode is essentially the API "compressed" into process arguments. To understand Firecracker fully — including snapshot, MMDS, and observability — API mode is the main path.

#Common Installation Pitfalls

Some of the most frequent mistakes:

• Compressed kernel: using vmlinuz instead of vmlinux → Firecracker fails to load the kernel.
• Wrongly formatted rootfs: the image file isn't ext4 or has no init → the guest hangs at boot.
• Relative paths: the API PUT /boot-source uses paths on the host. In non-jailer mode, use absolute paths (/home/user/fc-demo/vmlinux.bin), because Firecracker's working directory determines path resolution.
• KVM not enabled: running in a VM without nested virtualization → Error: KVM not available.
• Socket conflict: running two Firecracker processes with the same --api-sock → the socket is already in use. Each microVM needs a unique socket.

If you see a KVM error, debug in this order: ls -l /dev/kvm → kvm-ok → grep -cE 'vmx|svm' /proc/cpuinfo. One of these three is the problem.

#Closing

The key takeaways:

• Static firecracker + jailer v1.16.x binaries; just copy them, no dependencies.
• KVM must be enabled; verify with /dev/kvm and kvm-ok.
• The kernel must be uncompressed (vmlinux.bin), and the rootfs ext4 with an init.
• API mode (--api-sock) gives full control; --no-api mode is for fast boot.
• curl --unix-socket /tmp/firecracker.sock is the gateway to all microVM control.

In the next episode 4 we'll use API mode seriously for the first time: API Management — Boot & Machine Config — sending PUT /boot-source for the kernel, PUT /machine-config for vCPUs and memory, PUT /drives for block devices, then InstanceStart and watching your first microVM boot through the serial console. This is where you start feeling Firecracker's power for real.