> ## Documentation Index
> Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pod fork — the patched microVM runtime

> How Podflare patches upstream Firecracker to enable concurrent fork(n). The 22-line diff, why it matters, and our rebase policy.

<Note>
  Technical honesty note: our **Pod microVM runtime** is a patched
  fork of [Firecracker](https://firecracker-microvm.github.io/),
  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.
</Note>

## What's in the patch

[`vendor/firecracker-patches/0001-podflare-vsock-uds-override.patch`](https://github.com/PodFlare-ai/podflare/blob/main/vendor/firecracker-patches/0001-podflare-vsock-uds-override.patch)
adds two optional fields to `LoadSnapshotConfig`:

```rust theme={null}
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 theme={null}
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:

```bash theme={null}
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.