firecracker-containerd: running containerd containers inside Firecracker microVMs
firecracker-containerd enables containerd to manage containers as Firecracker microVMs
At a glance
- What is it?
- The project wires containerd to Firecracker so a container can run in its own KVM-backed microVM. It is a build-it-yourself integration, not a drop-in runtime, and the README says multi-tenant use is at the user's own risk.
- Who is it for?
- Adopt it if you are already committed to containerd, need a KVM boundary around a container, and can maintain a specialized containerd binary, a kernel, and a root filesystem image. Do not adopt it if you want a packaged runtime or a Kubernetes CRI today; the README lists CRI conformance as a longer-term roadmap item.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- No. The owners have archived the repository on GitHub, so it is read-only and no longer receives changes.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- firecracker-microvm/firecracker-containerd2,983 ★ · +39
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| firecracker-microvm/firecracker-containerd | 2.9k | 3k |
39 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What firecracker-containerd adds on top of plain containerd
A normal container shares the host kernel. Namespaces, cgroups and seccomp narrow what the process can reach, but a kernel bug or a bad capability grant can cross that line. firecracker-containerd puts a KVM hypervisor boundary between the container and the host instead. The README frames the motivation plainly: Firecracker microVMs start and stop quickly and add minimal overhead, and unlike traditional containers they provide "an additional layer of isolation via the KVM hypervisor".
The intended audience is narrow. The README names two cases: sandboxing a partially or fully untrusted third party container so it is less likely to leak secrets, and bin-packing disparate workloads on one host while keeping isolation between them. Multi-tenant hosts are called out as a beneficiary, immediately followed by a warning that multi-tenant use cases are at the user's own risk. That sentence matters more than the marketing around it. The project gives you a stronger boundary, not a certified multi-tenant platform.
Compatibility is deliberate where it is cheap. The README states that the project uses container standards such as the OCI image format so it stays compatible with the container ecosystem. You keep OCI images; what changes is where the container process actually runs.
The four moving parts and how a container ends up inside a microVM
The README lists four components, and the split explains most of the project's operational cost.
The control plugin manages the lifecycle of the runtime and implements the control API in proto/firecracker.proto, which manages microVM lifecycle. It is compiled into the containerd binary rather than loaded as a Go plugin, because, as the README puts it, building a Go plugin out-of-tree is hard. The consequence is direct: you must build a specialized containerd binary for firecracker-containerd. You cannot drop this into a stock containerd install.
The runtime links containerd outside the microVM to the Firecracker virtual machine monitor. It is implemented as an out-of-process shim runtime communicating over ttrpc, the same protocol family containerd already uses for shims.
The agent runs inside the microVM. It invokes runC through containerd's containerd-shim-runc-v1 to create standard Linux containers inside the VM. So the nesting is real: containerd on the host talks to a shim, the shim talks to Firecracker, and the agent inside the guest creates ordinary runC containers.
The fourth piece is the root filesystem image builder in tools/image-builder, which constructs a microVM root filesystem containing runc and the firecracker-containerd agent. Every container you launch depends on that image being built correctly.
Networking is configured at the microVM level with CNI plugins. The project provides a chaining plugin named tc-redirect-tap. The roadmap notes that the project currently allows launching a few containers colocated in the same microVM and that raising that number is under exploration. If your design assumes dozens of containers per VM, that assumption is ahead of the documented state.
Building firecracker-containerd from source and running your first example
There are no published releases in the repository, so the path is a source build. The README points to docs/getting-started.md and docs/quickstart.md for detailed instructions, and the top-level Makefile drives the build. The Makefile sets INSTALLROOT to /usr/local by default and builds subdirectories including agent, runtime, examples, firecracker-control/cmd/containerd, snapshotter, docker-credential-mmds and volume. It also pins a builder image:
makeThe Makefile exports FIRECRACKER_CONTAINERD_BUILDER_IMAGE as golang:1.25-bookworm and uses Firecracker's prebuilt Linux kernels, checking a SHA-256 per architecture. It supports x86_64 and aarch64 only; any other host architecture stops the build with an error. That is a hard gate, not a warning.
The examples directory is where to look for a first real use. It contains examples/taskworkflow.go and examples/taskworkflow.md, and examples is one of the SUBDIRS the Makefile builds and tests. The task workflow is the natural starting point because it exercises the control API and the shim without requiring you to write your own client first. Read examples/taskworkflow.md alongside the code before running anything.
Because the control plugin is compiled into containerd, the binary you run is the one built from firecracker-control/cmd/containerd. Pointing a stock containerd at the runtime will not work. The README says to see docs/architecture.md for how the components fit together; that document is the right companion to the getting started guide, because the failure modes here are usually wiring mistakes between the four components rather than container-level errors.
Where firecracker-containerd is the wrong tool
The clearest limitation is stated by the project itself: multi-tenant use cases are at the user's own risk. If you are selling isolation to strangers, the README does not claim to have solved that for you.
The roadmap is candid about the rest. Constraining or jailing the Firecracker VMM process to improve host security posture is a short-term item, which means it is not done. Until the VMM process is jailed, the isolation story has a host-side gap that the hypervisor boundary alone does not close.
CRI conformance and Kubernetes compatibility sit in the longer-term roadmap, alongside polishing and packaging. So the project is not a Kubernetes runtime you can select today. The README describes the goal of working with orchestration frameworks such as Kubernetes and Amazon ECS, and says the project will work to ensure conformance or compatibility where necessary. That is a statement of intent, not a supported integration.
Density is another boundary. The README says the project currently allows launching a few containers colocated in the same microVM. The bin-packing use case is described as an aspiration backed by Firecracker's low overhead, not as a measured property of this repository. And the build requirement is a real tax: a specialized containerd binary plus a root filesystem image plus a pinned kernel means every upgrade touches several artifacts at once.
firecracker-containerd compared with Kata Containers
Kata Containers is the closest alternative in kind: both run container workloads behind a virtual machine boundary. The difference is in what the project hands you.
firecracker-containerd is an integration into containerd's own plugin and shim machinery. It speaks ttrpc, implements a control API defined in proto/firecracker.proto, and deliberately reuses containerd's containerd-shim-runc-v1 inside the guest. That design keeps the host-side model close to containerd's, but it also means the control plugin lives inside a containerd binary you build yourself, and the runtime targets one VMM: Firecracker.
Kata Containers is a runtime project in its own right, with its own VMM support matrix and its own packaging path, and it is the more common choice when the requirement is a Kubernetes runtime rather than an embedded containerd integration. If your workload is a Kubernetes pod and you want a runtime class, Kata is the shape you are looking for; firecracker-containerd's CRI conformance is a roadmap item, not a shipped feature.
There is also the simpler comparison the search data keeps asking about: Firecracker versus a plain VM. A conventional VM boots a full guest and pays for it. Firecracker's pitch, echoed in this README, is fast start-up and shut-down with minimal overhead, which is what makes per-container VMs plausible at all. And Firecracker versus containerd alone is the isolation trade: containerd alone is lighter and simpler, and it is the right answer when the workload is trusted.
Maintenance, upgrades and the Apache-2.0 licence
The repository is not archived and the last push was on 2026-09-10, so the code is being touched. That is a statement about the repository, not a promise about release cadence; the repository has no published releases, which fits a project whose README sends you to a source build.
The upgrade surface is wide. go.mod pins github.com/containerd/containerd v1.7.33 and github.com/containerd/containerd/api v1.8.0, and it also pins the Firecracker Go SDK, Open Containers runc, runtime-spec, image-spec, CNI and the CNI plugins, plus ttrpc and grpc. A containerd minor upgrade can move the plugin and shim interfaces underneath you. Because the control plugin is compiled into containerd, an upgrade is not a binary swap; it is a rebuild of the specialized containerd binary, and often of the agent and the root filesystem image too.
The Makefile adds another upgrade obligation: it pins a kernel SHA-256 per architecture and uses Firecracker's prebuilt kernels. Bumping Firecracker or the kernel means updating those checksums, and the agent and runc inside the guest image must stay compatible with whatever the host side expects.
On licensing: the repository is Apache-2.0, and the source files carry the Apache 2.0 header. Apache-2.0 is permissive and includes an express patent grant. That is the extent of what the repository documents; dependency licences and the terms of any bundled kernel or Firecracker binary are separate questions for your own review.
Editorial conclusion
Adopt it if you are already committed to containerd, need a KVM boundary around a container, and can maintain a specialized containerd binary, a kernel, and a root filesystem image. Do not adopt it if you want a packaged runtime or a Kubernetes CRI today; the README lists CRI conformance as a longer-term roadmap item. Verify first that your host is x86_64 or aarch64 (the Makefile errors out on anything else) and that your kernel can run Firecracker, then read docs/architecture.md before writing any integration code.
Frequently asked questions
Is a Firecracker microVM safe?
The README says microVMs provide an additional layer of isolation via the KVM hypervisor, which is the whole reason to run a container inside one. It does not claim that isolation is complete: jailing the Firecracker VMM process to improve host security posture is listed as a short-term roadmap item, and multi-tenant use is stated to be at the user's own risk.
What are the key differences between Docker and Firecracker?
In this project they are not competitors but layers. Docker-style OCI images are still used, and inside the microVM the agent invokes runC through containerd's containerd-shim-runc-v1 to create standard Linux containers. Firecracker adds the microVM boundary around them, so the container no longer shares the host kernel.
Does firecracker-containerd work with Kubernetes?
Not as a supported runtime today. The README lists CRI conformance and compatibility with Kubernetes as longer-term roadmap items and says the project will work to ensure conformance or compatibility where necessary, which is a statement of intent rather than a shipped integration.
Why do I need a special containerd binary for firecracker-containerd?
The control plugin is compiled into the containerd binary because, as the README states, building a Go plugin out-of-tree is hard. That requires building a specialized containerd binary from firecracker-control/cmd/containerd rather than using a stock containerd install.
How many containers can run in one Firecracker microVM with firecracker-containerd?
The README says the project currently allows launching a few containers colocated in the same microVM and that raising that number is being explored. No figure is given, so treat per-VM density as something to measure on your own workload.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/firecracker-microvm-firecracker-containerd)Star history chart for your README
[](https://hysenlabs.com/projects/firecracker-microvm-firecracker-containerd)Was this useful?