Firecracker Open-Source Contributor Curriculum

Welcome to the Firecracker Open-Source Contributor Curriculum — a complete, implementation-heavy roadmap for engineers who want to become serious Firecracker contributors and eventually operate at the level of a core contributor or maintainer. By the end you will be able to boot a microVM by hand, read the vCPU run loop without a guide, trace an HTTP request from a Unix socket to a KVM_RUN exit, write a virtio device, and prepare a pull request the maintainers will take seriously.

What This Curriculum Is

This is not a tutorial and it is not a "deploy Firecracker in 10 minutes" blog post. It is a structured engineering apprenticeship built around how Firecracker is actually developed, tested, reviewed, and maintained by the AWS team that owns it.

Every level is tied to real Firecracker source code (the firecracker-microvm/firecracker Rust workspace), the real tools/devtool build/test flow, the real REST API, the real seccomp and jailer security model, and the real GitHub contribution workflow. The labs mirror the work a Firecracker maintainer actually does — reading the threading model, tracing a virtio-block I/O down to a Lucene… no, down to a KVM_EXIT_MMIO and a host pread, debugging a failed boot, reproducing a reported issue, and preparing pull requests for review by people who will reject sloppy work.

This curriculum will not hold your hand. It points you at the right parts of the codebase, gives you the right questions to ask, and makes you run everything you read. Where this book names a struct or a function, it also gives you the grep/rg/find command to locate it on your own checkout — because code moves between branches, and a contributor who depends on memorized line numbers is already lost.

What a VMM Is, and What Firecracker Does

A Virtual Machine Monitor (VMM) — also called a hypervisor's userspace, or a "monitor" — is the program that creates a virtual machine, gives it memory and virtual CPUs, emulates the handful of devices the guest needs, loads a kernel into it, and then runs it. On Linux, the heavy lifting of actually running guest code on the physical CPU is done by KVM (the Kernel-based Virtual Machine), a kernel module that exposes /dev/kvm. The VMM is the userspace process that drives KVM through ioctl() calls. KVM runs the guest; the VMM decides what the guest is.

Firecracker is a VMM with an unusual design goal: do almost nothing. Where QEMU emulates hundreds of devices, a BIOS, PCI, USB, and a dozen CPU architectures, Firecracker emulates a network device, a block device, a vsock device, a serial console, a partial keyboard controller (only enough to catch a reboot), and almost nothing else. It boots an uncompressed Linux kernel directly — no BIOS, no bootloader — straight into 64-bit mode. The result is a microVM: a virtual machine that boots to application code in under 125 milliseconds, adds less than 5 MiB of memory overhead, and exposes a tiny enough attack surface that AWS runs thousands of mutually-untrusting customer workloads per physical host on it. Firecracker is what runs your AWS Lambda functions and your AWS Fargate tasks.

The "do almost nothing" philosophy is not minimalism for its own sake — it is a security argument. Every emulated device is host code that a malicious guest can attack. Fewer devices, a memory-safe implementation language (Rust), and defense in depth (the KVM boundary, plus a jailer that chroots and drops privileges, plus a seccomp-BPF filter that whitelists the ~40 syscalls Firecracker is allowed to make) together make a microVM a credible isolation boundary for hostile, multi-tenant code. You will internalize this argument deeply, because it explains nearly every design decision in the codebase.

Here is the whole stack you will come to know:

┌─────────────────────────────────────────────────────────────────────┐
│  Orchestrator (firecracker-containerd / Kata / your own controller)  │  ← starts & manages microVMs
└─────────────────────────────────────────────────────────────────────┘
                    │  HTTP over a Unix domain socket (REST API)
                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  jailer  ── chroot + cgroups + namespaces + drop privileges ──►       │  ← the security barrier
│  firecracker (the VMM, Rust)                                          │
│    • API thread  (HTTP server on the socket; control plane)          │
│    • VMM thread  (device emulation, event loop, MMDS, rate limiting) │
│    • vCPU thread × N  (each runs the KVM_RUN loop)                    │
│    seccomp-BPF filter applied to every thread                        │
└─────────────────────────────────────────────────────────────────────┘
                    │  ioctl() on /dev/kvm  (KVM_CREATE_VM, KVM_RUN, …)
                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  KVM (Linux kernel module)  ── runs guest code on VT-x / AMD-V / ARM │  ← hardware virtualization
└─────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  The guest: an unmodified Linux kernel + your rootfs, in a microVM   │
└─────────────────────────────────────────────────────────────────────┘

You will learn every box in this diagram, top to bottom, and you will build a tiny version of the KVM box yourself in Lab 1.4 before you ever read Firecracker's Vcpu.

Booting a microVM in 30 Seconds (so the rest makes sense)

You will do this for real, with explanation, in Lab 1.3. Here it is in miniature so the architecture above has something concrete underneath it. Firecracker has no command-line "run this VM" mode in the usual sense — you start it with an API socket and configure the machine by sending it JSON over that socket, then tell it to start:

# 1. Start the VMM. It does nothing yet but listen on the socket.
sudo ./firecracker --api-sock /tmp/fc.sock &

# 2. Tell it which kernel to boot and what to pass on the kernel command line.
curl -X PUT --unix-socket /tmp/fc.sock \
  --data '{"kernel_image_path":"./vmlinux","boot_args":"console=ttyS0 reboot=k panic=1"}' \
  http://localhost/boot-source

# 3. Give it a root filesystem (a flat ext4 image, exposed as a virtio-block device).
curl -X PUT --unix-socket /tmp/fc.sock \
  --data '{"drive_id":"rootfs","path_on_host":"./rootfs.ext4","is_root_device":true,"is_read_only":false}' \
  http://localhost/drives/rootfs

# 4. Start the microVM. The kernel boots; you get a login prompt on the serial console.
curl -X PUT --unix-socket /tmp/fc.sock \
  --data '{"action_type":"InstanceStart"}' \
  http://localhost/actions

That is the entire user-facing surface of Firecracker: a Unix socket, a few PUT requests, an InstanceStart. Everything else in this curriculum is what happens underneath those four calls — how PUT /boot-source becomes a VmmAction on a channel, how the kernel image is parsed and copied into guest memory, how the rootfs becomes a virtio-block device sitting at a fixed MMIO address, and how InstanceStart spins up vCPU threads that each enter KVM_RUN and never look back.

Who This Is For

This curriculum is designed for strong systems engineers who:

• Have 3+ years of systems programming experience; Rust is a strong plus but you can learn it here if you are fluent in C/C++/Go and willing to work.
• Are comfortable on Linux at the systems level: processes, threads, file descriptors, mmap, signals, epoll, Unix sockets, ioctl.
• Understand, or want to understand, what happens when a computer boots and how an OS talks to hardware.
• Want to contribute to open source at a serious level — not just fix typos.

You should be comfortable with:

• Reading large, unfamiliar Rust codebases without a guide (or pushing through the discomfort).
• git workflows, reading diffs, working with GitHub pull requests.
• The idea of privilege boundaries and why isolation is hard.

You do not need prior virtualization, KVM, or kernel experience. You will build it here, starting from a ~70-line KVM "VMM" you write by hand.

What You Will Be Able to Do

How to Use This Curriculum

Work through the 9 levels sequentially. Do not skip levels — each builds directly on the previous, and the labs depend on foundations laid earlier.

Beyond the 9 levels, the curriculum includes several supporting tracks:

The curriculum closes with a Capstone Project — a full contribution cycle from issue reproduction to merged pull request and engineering write-up — and a Capstone Project Portfolio of larger, self-directed builds.

The deep dives and the rust-vmm section are not optional reading — they are where the real depth lives. A level says "trace a virtio-block I/O"; the virtio-block deep dive and the virtqueues deep dive are where you learn how the descriptor chain actually works. Treat the levels as the spine and the deep dives as the muscle.

Required Tools

Before starting Level 1, you need a Linux machine with hardware virtualization and a working /dev/kvm. This is the one hard requirement: Firecracker runs on Linux only, on x86_64 or aarch64, and needs KVM.

A Linux host (bare metal, or a VM/cloud instance with nested virtualization enabled)
  └─ /dev/kvm present and accessible  ── ls -l /dev/kvm ; check you are in the `kvm` group
Docker            (tools/devtool runs the build/test inside a container)
Git 2.x
Rust toolchain    (rustup; the repo pins an exact channel in rust-toolchain.toml)
curl              (drive the API socket)
A code editor with rust-analyzer (VS Code or your editor of choice)

# The single most important pre-flight check. If this fails, nothing else works.
ls -l /dev/kvm
# crw-rw---- 1 root kvm ... /dev/kvm     ← you must be able to read+write it

# On a cloud VM you may need nested virtualization. On AWS, use a *.metal instance
# (bare metal) — Firecracker does not run on ordinary nested EC2 instances.

Note on the build: Firecracker builds inside a Docker dev container driven by tools/devtool — you do not install a specific Rust version system-wide; the container pins it. You only need Docker, Git, and a checkout. The container also has the cross-compilers, the test kernels, and the Python test harness. This is covered step by step in Lab 1.1.

You will also need a clone of the Firecracker repository and a free GitHub account with your local git configured for DCO sign-off (git commit -s — covered in Level 2).

Firecracker at a Glance

Firecracker is a userspace VMM written in Rust that uses KVM to run microVMs. It was open-sourced by AWS in 2018, is licensed Apache 2.0, and is maintained by a dedicated AWS team with contributions from a broad community (and a close relationship with the rust-vmm project, which shares low-level crates between Firecracker and other VMMs like Cloud Hypervisor).

Why Firecracker Exists

AWS Lambda originally ran each customer's functions in dedicated EC2 instances, which stranded capacity and scaled poorly for short-lived, bursty, multi-tenant function workloads. The team needed something with VM-grade isolation (a real hardware-virtualization boundary, because the guest — including the guest kernel — is untrusted) but with container-grade density and startup (thousands per host, booting in tens of milliseconds, with minimal memory overhead). No existing VMM hit all of those at once. Firecracker is the answer: a minimal, fast, secure VMM purpose-built for serverless. The design is documented in the NSDI 2020 paper "Firecracker: Lightweight Virtualization for Serverless Applications."

What Firecracker Does

• Opens /dev/kvm and creates a VM with guest memory (host mmap registered with KVM) and one vCPU per configured CPU.
• Loads an uncompressed Linux kernel directly into guest memory and sets up boot parameters — no BIOS, no bootloader.
• Emulates a minimal device model: virtio-block, virtio-net (over a host TAP device), virtio-vsock, virtio-rng, virtio-balloon, a serial console, and a partial i8042 — all over the virtio-MMIO transport (no PCI by default).
• Exposes a REST API over a Unix domain socket for configuration and control.
• Runs each vCPU in its own thread in a KVM_RUN loop, handling VM exits (I/O, MMIO, halt) as they occur.
• Confines itself with a jailer (chroot/cgroups/namespaces/privilege drop) and seccomp-BPF filters.
• Can snapshot a running microVM's full state and restore it elsewhere, including lazy memory loading via userfaultfd.

How It Compares

The key insight you will carry throughout: a VM gives strong isolation because the guest is confined behind CPU virtualization extensions — but the VMM itself is privileged host code and part of the attack surface. A guest that compromises the VMM escapes. That is exactly why a minimal VMM in a memory-safe language matters. Firecracker bets that you can have most of QEMU's isolation with a fraction of the exploitable code. The full comparison lives in Firecracker vs. Other VMMs.

Key Crates and Types (High-Level Preview)

You will spend most of your time in the vmm crate. Do not memorize this — by Level 4 you will read these without a guide.

If most of these are unfamiliar, that is expected. Run the rg commands the labs give you and they will become real.

The Firecracker Community and Project

Firecracker is open source but single-vendor governed: a dedicated AWS team maintains it, with no separate foundation or steering committee. Contributions come by GitHub pull request against main, require a DCO sign-off on every commit (git commit -s; there is no CLA), and need two maintainer approvals to merge. New functionality requires integration tests. Security vulnerabilities are reported privately to AWS Security, never as public issues.

What the maintainers value:

• PRs that include tests and pass tools/devtool checkstyle and checkbuild --all.
• Issues with clear, minimal reproductions.
• Comments that demonstrate you have read the existing code.
• Respect for the minimal-device-model philosophy — proposals that add surface area face a high bar, and "QEMU has it" is not an argument.
• Sustained, high-quality contribution over time.

The path from contributor to maintainer is measured in months to years, not weeks. That is intentional. This curriculum builds the habits and depth of understanding that make that path realistic.

Begin with the Overview & Prerequisites, then read The Hitchhiker's Guide to Virtualization, KVM & microVMs before starting Level 1.