Skip to main content
Technical honesty note: our Pod microVM runtime is a patched fork of Firecracker, the open-source VMM originally developed by AWS. This page is the deep technical doc for engineers wanting to understand exactly what we change against upstream. Everywhere else on Podflare we refer to our own runtime as “Podflare Pod” — this is the one place it matters to be specific about the substrate.

​
What’s in the patch

vendor/firecracker-patches/0001-podflare-vsock-uds-override.patch adds two optional fields to LoadSnapshotConfig: 
pub struct LoadSnapshotConfig {
    // ... existing fields ...

    /// [podflare] Override the vsock UDS path from the snapshot.
    pub vsock_uds_path_override: Option<String>,
    /// [podflare] Override block device paths on restore.
    pub drive_overrides: Vec<DriveOverride>,
}
At restore time, before the VMM builds from the snapshot state, we patch microvm_state.device_states.mmio_state:
  • vsock_device.device_state.backend.uds_path ← vsock_uds_path_override
  • block_devices[i].disk_path ← matching drive_overrides[*].path_on_host
Patch size: 22 lines of additions across 5 files (+ 2 lines of pub on formerly-private VirtioBlockState fields). We also use the existing snapshot_type: "Diff" flow with no modifications.

​
Why we need this

Every fork(n=5) restores 5 Podflare Pod microVMs from a single snapshot. Each child must bind its own host-side vsock UDS (because they’re all concurrent) and use its own rootfs file (because writes must be CoW-isolated). Upstream hardcodes those paths from the snapshot state; there’s no post-load-pre-resume API to patch them. Without this patch, multiple concurrent restores would collide — the second child errors because the UDS already exists, or worse, overlaps on the rootfs file and corrupts it.

​
Build

bash scripts/build-firecracker.sh
# produces /usr/local/bin/podflare-firecracker
# and    /usr/local/bin/podflare-rebase-snap
The script clones upstream at a pinned tag (v1.15.1), applies every patch in vendor/firecracker-patches/ in lexical order, builds, and installs. The resulting podflare-firecracker binary is what runs on the host as the Pod VMM — named podflare-firecracker on disk so the filesystem path stays self-documenting for the operators who have to debug it.

​
Rebase policy

Upstream releases every ~6 weeks. When we bump the pin: 
cd vendor/firecracker
git fetch --depth 1 origin refs/tags/vX.Y.Z:refs/tags/vX.Y.Z
git checkout -f vX.Y.Z

# apply existing patches, resolve conflicts
for p in /root/podflare/vendor/firecracker-patches/*.patch; do
  git apply --3way "$p"
done

# regenerate the .patch file(s)
git diff > /root/podflare/vendor/firecracker-patches/0001-podflare-vsock-uds-override.patch
A 50-LoC patch against a stable subsystem rebases in about 15 minutes.

​
Upstreaming

The vsock override is a small, reasonable feature. We may submit it upstream. If accepted, the patch file disappears and build-firecracker.sh stops applying it — no Podflare-side changes needed.