{
  "generator": {
    "name": "Symvanta",
    "url": "https://symvanta.com"
  },
  "page": {
    "url": "https://symvanta.com/architecture/firecracker",
    "title": "Firecracker Architecture: How It Actually Works",
    "description": "How the Firecracker codebase is structured: module map, load-bearing symbols, and dependency structure, generated by Symvanta.",
    "datePublished": "2026-08-11",
    "dateModified": "2026-08-11"
  },
  "repository": {
    "name": "firecracker-microvm/firecracker",
    "url": "https://github.com/firecracker-microvm/firecracker",
    "commit": "48f1b9f",
    "license": "Apache-2.0"
  },
  "graph": {
    "modules": 48,
    "dependencyCycles": 0,
    "modularityQ": 0.79,
    "largestCycleFiles": null,
    "mutuallyRecursiveGroups": 2
  },
  "summaryMarkdown": "Firecracker is the virtual machine monitor behind AWS Lambda and Fargate: one\nRust binary that boots stripped-down microVMs on KVM, driven by a REST API\nover a unix socket, with its own virtio devices, seccomp filters, and a\njailer. Symvanta's graph at `48f1b9f` detects 48 functional modules at\nmodularity Q=0.79, and the two biggest clusters are the virtio device layer\naround `GuestMemoryMmap` (1002 symbols) and the API control plane around\n`ParsedRequest` (675).\n\nThe map is unusually clean for a systems repo. The hubs are real domain types\n(`GuestMemoryMmap`, `ParsedRequest`, `VsockError`, `RateLimiter`), the\nheaviest edge runs from the API control plane into the device layer (192\ncalls), and the whole graph carries just 2 pairs of mutually recursive\nsymbols. The devices sit in a ring around guest memory, which is what a VMM\nlooks like when every device's job is moving bytes in and out of the guest.",
  "subsystems": [
    {
      "name": "Virtio devices and guest memory",
      "descriptionMarkdown": "`GuestMemoryMmap` is the handle to guest physical memory, and the virtio\nplumbing that moves bytes through it (`VirtioDevice`, `Queue`,\n`VirtioInterrupt`, the net device) clusters around it: 1002 symbols, the\nlargest module in the repo. Its heaviest inbound edge is the 192 calls from\nthe API control plane."
    },
    {
      "name": "API server and VmmAction",
      "descriptionMarkdown": "The control plane. `ParsedRequest.try_from`\n(`src/firecracker/src/api_server/parsed_request.rs:69`) turns each request on\nthe API socket into a `VmmAction`, and `VmResources` accumulates the machine\nconfig before boot. 675 symbols."
    },
    {
      "name": "Dumbo MMDS network stack",
      "descriptionMarkdown": "`InnerBytes`, `MacAddr`, and `Connection` from `vmm/src/dumbo`: a hand-written\nTCP stack that serves the metadata service (MMDS) to guests directly from the\nVMM process. 557 symbols."
    },
    {
      "name": "io_uring engine and bindings",
      "descriptionMarkdown": "The async block-IO engine: `IoUringError`, `WrappedRequest`, `PendingRequest`,\nplus the `__u32`-style kernel ABI types the ring shares with Linux. 534\nsymbols."
    },
    {
      "name": "Vsock device and muxer",
      "descriptionMarkdown": "The virtio-vsock device and its unix-socket muxer: `VsockPacketTx`,\n`VsockPacketRx`, `VsockConnection`, `MuxerRx`. 507 symbols."
    },
    {
      "name": "Balloon and block devices",
      "descriptionMarkdown": "`Balloon`, `VirtioBlock`, and `DescriptorChain` share one 504-symbol cluster.\nIts hub is `VirtQueue` from `devices/virtio/test_utils.rs`, which is what a\nhub looks like when the device tests drive every queue path in the cluster."
    },
    {
      "name": "Shared infrastructure",
      "descriptionMarkdown": "The rest of the top 10: Seccomp BPF and device bus (457 symbols, hub\n`BpfInstruction`), Metrics counters (438, hub `SharedIncMetric`), KvmVm and\nmemory regions (438, hub `GuestRegionMmapExt`), and CPU templates and CPUID\n(423, hub `CustomCpuTemplate`)."
    }
  ],
  "startReading": {
    "symbols": [
      {
        "name": "build_microvm_for_boot"
      },
      {
        "name": "GuestMemoryMmap"
      },
      {
        "name": "ParsedRequest"
      },
      {
        "name": "VmmAction"
      },
      {
        "name": "KvmVm"
      },
      {
        "name": "VirtioDevice"
      },
      {
        "name": "CustomCpuTemplate"
      },
      {
        "name": "RateLimiter"
      },
      {
        "name": "MicrovmState"
      }
    ],
    "endpoints": []
  },
  "requestFlow": [
    {
      "position": 1,
      "symbol": "build_microvm_for_boot (src/vmm/src/builder.rs:143)",
      "sourceUrl": null,
      "markdown": "`build_microvm_for_boot (src/vmm/src/builder.rs:143)`"
    },
    {
      "position": 2,
      "symbol": "VmResources.allocate_guest_memory",
      "sourceUrl": null,
      "markdown": "`VmResources.allocate_guest_memory`"
    },
    {
      "position": 3,
      "symbol": "KvmVm.new",
      "sourceUrl": null,
      "markdown": "`KvmVm.new`"
    },
    {
      "position": 4,
      "symbol": "KvmVm.create_vcpus",
      "sourceUrl": null,
      "markdown": "`KvmVm.create_vcpus`"
    },
    {
      "position": 5,
      "symbol": "DeviceManager.new",
      "sourceUrl": null,
      "markdown": "`DeviceManager.new`"
    },
    {
      "position": 6,
      "symbol": "load_kernel",
      "sourceUrl": null,
      "markdown": "`load_kernel`"
    },
    {
      "position": 7,
      "symbol": "attach_block_devices",
      "sourceUrl": null,
      "markdown": "`attach_block_devices`"
    },
    {
      "position": 8,
      "symbol": "attach_net_devices",
      "sourceUrl": null,
      "markdown": "`attach_net_devices`"
    },
    {
      "position": 9,
      "symbol": "configure_system_for_boot",
      "sourceUrl": null,
      "markdown": "`configure_system_for_boot`"
    },
    {
      "position": 10,
      "symbol": "KvmVm.start_vcpus",
      "sourceUrl": null,
      "markdown": "`KvmVm.start_vcpus`"
    }
  ],
  "diagrams": [
    {
      "url": "https://symvanta.com/architecture/firecracker/module-map.svg",
      "encodingFormat": "image/svg+xml"
    }
  ]
}