# firecracker-microvm/firecracker architecture

> Architecture diagram of the GitHub repository firecracker-microvm/firecracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firecracker-microvm/firecracker
- Repository: https://github.com/firecracker-microvm/firecracker

## Overview

Firecracker is a host-side virtual machine monitor for creating and running isolated microVMs, with KVM as its primary backend and a Nitro Sandbox option. The main workflow is a host operator or runtime configuring a VM through the API, then Firecracker building it and driving its event loop. The graph also preserves device, guest-memory, snapshot, and isolation capabilities documented in the README. Some subsystem paths come from the tree rather than inspected implementations; those relationships are omitted where evidence does not establish the call direction.

Main entry points: [`src/firecracker/src/main.rs`](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/main.rs) (Firecracker Process), [`src/vmm/src/devices/virtio/device.rs`](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/device.rs) (Virtio Framework), [`src/vmm/src/vstate/vm.rs`](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/vm.rs) (VM State), [`src/firecracker/src/api_server/mod.rs`](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/api_server/mod.rs) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Host Control"]
  node_api["HTTP API<br/>[mod.rs]"]
  node_api_adapter["API Adapter"]
  node_firecracker["Firecracker Process<br/>[main.rs]"]
  node_configuration["VM Configuration"]
end

subgraph group_vm["VM Runtime"]
  node_builder["MicroVM Builder<br/>[builder.rs]"]
  node_vm_state["VM State<br/>[vm.rs]"]
  node_guest_memory["Guest Memory<br/>[memory.rs]"]
  node_kvm["KVM Backend<br/>[kvm.rs]"]
  node_nitro["Nitro Sandbox"]
end

subgraph group_devices["Guest Devices"]
  node_virtio["Virtio Framework<br/>[device.rs]"]
  node_block["Block Device<br/>[worker.rs]"]
  node_network["Network Device<br/>[device.rs]"]
  node_vsock["Vsock Device<br/>[event_handler.rs]"]
end

subgraph group_state["State and Metadata"]
  node_metadata["Guest Metadata"]
  node_snapshots["Snapshots"]
  node_metrics["Metrics<br/>[metrics.rs]"]
end

subgraph group_security["Isolation"]
  node_jailer["Jailer<br/>[main.rs]"]
  node_seccomp["Seccomp Filters<br/>[seccomp.rs]"]
end

node_operator(("Host Operator"))

node_operator -->|"configures VM"| node_api
node_api -->|"sets resources"| node_configuration
node_firecracker -->|"starts API"| node_api
node_firecracker -->|"uses adapter"| node_api_adapter
node_firecracker -->|"builds microVM"| node_builder
node_firecracker -->|"starts metrics"| node_metrics
node_firecracker -->|"applies filters"| node_seccomp
node_configuration -.->|"configures"| node_builder
node_builder -.->|"creates VM"| node_vm_state
node_vm_state -.->|"uses backend"| node_kvm
node_vm_state -.->|"selects backend"| node_nitro
node_virtio -.->|"hosts device"| node_block
node_virtio -.->|"hosts device"| node_network
node_virtio -.->|"hosts device"| node_vsock

click node_api "https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/api_server/mod.rs"
click node_api_adapter "https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/api_server_adapter.rs"
click node_firecracker "https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/main.rs"
click node_configuration "https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/vmm_config"
click node_builder "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/builder.rs"
click node_vm_state "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/vm.rs"
click node_guest_memory "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/memory.rs"
click node_kvm "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/kvm.rs"
click node_nitro "https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/nitro_enclave"
click node_virtio "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/device.rs"
click node_block "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/block/virtio/worker.rs"
click node_network "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/net/device.rs"
click node_vsock "https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/vsock/event_handler.rs"
click node_metadata "https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/mmds"
click node_snapshots "https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/snapshot"
click node_metrics "https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/metrics.rs"
click node_jailer "https://github.com/firecracker-microvm/firecracker/blob/main/src/jailer/src/main.rs"
click node_seccomp "https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/seccomp.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_api_adapter,node_firecracker,node_configuration toneBlue
class node_builder,node_vm_state,node_guest_memory,node_kvm,node_nitro toneAmber
class node_virtio,node_block,node_network,node_vsock toneMint
class node_metadata,node_snapshots,node_metrics toneRose
class node_jailer,node_seccomp,node_operator toneIndigo
```

## Components

### Host Control

- [HTTP API](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/api_server/mod.rs): `src/firecracker/src/api_server/mod.rs`
- [API Adapter](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/api_server_adapter.rs): `src/firecracker/src/api_server_adapter.rs`
- [Firecracker Process](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/main.rs): `src/firecracker/src/main.rs`
- [VM Configuration](https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/vmm_config): `src/vmm/src/vmm_config`

### VM Runtime

- [MicroVM Builder](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/builder.rs): `src/vmm/src/builder.rs`
- [VM State](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/vm.rs): `src/vmm/src/vstate/vm.rs`
- [Guest Memory](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/memory.rs): `src/vmm/src/vstate/memory.rs`
- [KVM Backend](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/vstate/kvm.rs): `src/vmm/src/vstate/kvm.rs`
- [Nitro Sandbox](https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/nitro_enclave): `src/vmm/src/nitro_enclave`

### Guest Devices

- [Virtio Framework](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/device.rs): `src/vmm/src/devices/virtio/device.rs`
- [Block Device](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/block/virtio/worker.rs): `src/vmm/src/devices/virtio/block/virtio/worker.rs`
- [Network Device](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/net/device.rs): `src/vmm/src/devices/virtio/net/device.rs`
- [Vsock Device](https://github.com/firecracker-microvm/firecracker/blob/main/src/vmm/src/devices/virtio/vsock/event_handler.rs): `src/vmm/src/devices/virtio/vsock/event_handler.rs`

### State and Metadata

- [Guest Metadata](https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/mmds): `src/vmm/src/mmds`
- [Snapshots](https://github.com/firecracker-microvm/firecracker/tree/main/src/vmm/src/snapshot): `src/vmm/src/snapshot`
- [Metrics](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/metrics.rs): `src/firecracker/src/metrics.rs`

### Isolation

- [Jailer](https://github.com/firecracker-microvm/firecracker/blob/main/src/jailer/src/main.rs): `src/jailer/src/main.rs`
- [Seccomp Filters](https://github.com/firecracker-microvm/firecracker/blob/main/src/firecracker/src/seccomp.rs): `src/firecracker/src/seccomp.rs`

### Other components

- **Host Operator**

## Connections

- Host Operator → HTTP API: configures VM (evidence: `README.md`)
- HTTP API → VM Configuration: sets resources (evidence: `README.md`)
- Firecracker Process → HTTP API: starts API (evidence: `src/firecracker/src/main.rs`)
- Firecracker Process → API Adapter: uses adapter (evidence: `src/firecracker/src/main.rs`)
- Firecracker Process → MicroVM Builder: builds microVM (evidence: `src/firecracker/src/main.rs`)
- Firecracker Process → Metrics: starts metrics (evidence: `src/firecracker/src/main.rs`)
- Firecracker Process → Seccomp Filters: applies filters (evidence: `src/firecracker/src/main.rs`)
- VM Configuration → MicroVM Builder: configures
- MicroVM Builder → VM State: creates VM
- VM State → KVM Backend: uses backend
- VM State → Nitro Sandbox: selects backend
- Virtio Framework → Block Device: hosts device (evidence: `src/vmm/src/devices/virtio/block/virtio/worker.rs`)
- Virtio Framework → Network Device: hosts device
- Virtio Framework → Vsock Device: hosts device (evidence: `src/vmm/src/devices/virtio/vsock/event_handler.rs`)
