forkd Files

v0.5.0 ships v0.5 (diff-snapshot chains) and folds in v0.4 (live-fork BRANCH) — the first formal release since v0.3.4.

v0.5: diff-snapshot chains

Stack snapshots into a chain — base → +numpy → +pandas → +sklearn — instead of one flat snapshot per dependency set. The daemon walks the chain at spawn time and assembles memory in one pass.

:::bash
forkd snapshot-diff --from py-base   --tag py-numpy   --exec "pip install numpy==2.0.2"
forkd snapshot-diff --from py-numpy  --tag py-pandas  --exec "pip install pandas==2.2.3"
forkd fork --tag py-pandas -n 1               # daemon walks the chain transparently

forkd snapshot-info py-pandas                 # depth, parent, ancestors, dependents
forkd rmi py-numpy                            # 409 + actionable msg if children
forkd rmi py-numpy --cascade                  # subtree delete
forkd snapshot-compact --from py-pandas --to py-pandas-flat
forkd pack --tag py-pandas --out chain.tar.zst # v2 manifest, bundles every ancestor
forkd unpack chain.tar.zst                    # one snapshot dir per chain link

Phase 5 bench (RESULTS-v0.5.md)

Correctness: 90/90 (100%) probe passes across L1/L2/L3 + flat-equivalent. The design's vmstate-drift question is empirically closed.

The ~460 ms per-link tax tracks SHA-256 of the base (1.1 GiB/s) — the mmap-once incremental verify optimization is queued for v0.6.

v0.4: live-fork BRANCH (also captured here)

Sub-50 ms source-pause BRANCH via UFFD_WP + memfd_create. 56 ms p50 / 64 ms p90 on a 1.5 GiB python-numpy source — 3.6× faster than v0.3 Diff at p50 and disk-independent. With wait: false the caller returns in ~70 ms while the background memory copy completes asynchronously (200× RT improvement for fire-and-forget BRANCH).

Reachable via mode: "live" / wait: false on REST, --live / --no-wait on CLI, and the Python / TypeScript / MCP SDKs. forkd doctor probes the kernel and FC prerequisites.

Requires Linux ≥ 5.7, vm.unprivileged_userfaultfd=1 (or CAP_SYS_PTRACE), and the vendored Firecracker fork (33-line mem_backend.shared patch, upstream proposal at #5912).

Real bugs caught during ship-out

Two bugs the test suite hadn't caught — both surfaced by the Phase 5 bench / Phase 6 E2E fixture:

• #217: Phase 2a chain-assembled memory.bin was unlinked by restore_many_with's startup sweep before FC's /snapshot/load could open it. Symptom: every spawn from a chained snapshot returned HTTP 500. Fixed; regression test work_dir_sweep_preserves_chainstage_subdirectory added.
• #219: Pre-Phase-4 forkd rmi silently orphaned chained children. Now 409 with actionable message + --cascade / --force carve-outs.

What's in this tag

• forkd snapshot-diff (v0.5 Phase 2b) — build chain layers
• forkd snapshot-info (v0.5 Phase 4) — inspect chain shape + dependents
• forkd snapshot-compact (v0.5 Phase 4) — flatten a chain head
• forkd rmi --cascade | --force (v0.5 Phase 4) — chain-aware delete
• forkd pack / unpack manifest v2 (v0.5 Phase 3) — chain-aware bundles
• forkd doctor v0.4 checks (uffd_wp + memfd_create)
• mode: "live" BRANCH (v0.4) via REST / CLI / SDKs
• scripts/dev/v05-e2e.sh — 15-assertion smoke test for the whole v0.5 surface

Reproduce

End-to-end on a Linux + KVM host:

:::bash
git checkout v0.5.0
cargo build --release -p forkd-cli -p forkd-controller
sudo target/release/forkd-controller serve --bind 127.0.0.1:8889 ...
FORKD_BIN=target/release/forkd FORKD_BASE_TAG=demo-pyt ./scripts/dev/v05-e2e.sh

Full v0.5 phase-by-phase notes: see CHANGELOG.md (github.com) and the v0.5 tracking issue #216.

What's Changed

• chore: post-#146 cleanup — remove stale warnings + mark probes resolved by @WaylandYang in https://github.com/deeplethe/forkd/pull/154
• fix(cli): forkd doctor no longer warns on idle TAP (admin-UP + no peer) by @WaylandYang in https://github.com/deeplethe/forkd/pull/155
• RFC: v0.4 live-fork via userfaultfd write-protect by @WaylandYang in https://github.com/deeplethe/forkd/pull/156
• v0.4 foundation: WpBranch primitive + 3 PoCs + wp-bench CLI by @WaylandYang in https://github.com/deeplethe/forkd/pull/157
• experiment: v0.4 Phase 4 PoC — WpBranch snapshot round-trip + restore by @WaylandYang in https://github.com/deeplethe/forkd/pull/160
• fix: address external issues [#158] + [#159] by @WaylandYang in https://github.com/deeplethe/forkd/pull/161
• security: fix bearer-token length oracle in constant_time_eq (#162) by @WaylandYang in https://github.com/deeplethe/forkd/pull/164
• docs: lead Quick start with forkd pull, plus v0.3.4 / doctor-screenshot polish by @WaylandYang in https://github.com/deeplethe/forkd/pull/165
• hub: add deeplethe/python-numpy v1 by @WaylandYang in https://github.com/deeplethe/forkd/pull/166
• hub: add deeplethe/playwright-browser v1 (M1.1 headliner) by @WaylandYang in https://github.com/deeplethe/forkd/pull/167
• hub: add deeplethe/postgres-fixture v1 (fork-per-test DB) by @WaylandYang in https://github.com/deeplethe/forkd/pull/168
• hub: add deeplethe/coding-agent v1 (SWE-bench) by @WaylandYang in https://github.com/deeplethe/forkd/pull/169
• hub: add deeplethe/nodejs v1 (generic JS base) by @WaylandYang in https://github.com/deeplethe/forkd/pull/170
• hub: add deeplethe/e2b-codeinterpreter v1 (E2B drop-in) by @WaylandYang in https://github.com/deeplethe/forkd/pull/171
• hub: add deeplethe/jupyter-kernel v1 by @WaylandYang in https://github.com/deeplethe/forkd/pull/172
• docs: close M1.2 — 9 recipes in Hub, hosting decision, README done by @WaylandYang in https://github.com/deeplethe/forkd/pull/173
• RFC: v0.4 user-facing API surface (CLI / REST / SDK) by @WaylandYang in https://github.com/deeplethe/forkd/pull/174
• fix(vmm): cap volume_device_name at MAX_VOLUMES (closes [#175]) by @WaylandYang in https://github.com/deeplethe/forkd/pull/176
• feat(controller): expose branch_concurrency via CLI + env var (closes [#177]) by @WaylandYang in https://github.com/deeplethe/forkd/pull/179
• fix(vmm): apply_diff rejects diff/base size mismatch (closes [#180]) by @WaylandYang in https://github.com/deeplethe/forkd/pull/182
• feat(metrics): expose forkd_branches_in_flight + cap (follow-up to [#177]) by @WaylandYang in https://github.com/deeplethe/forkd/pull/183
• packaging(systemd): add cgroup to RestrictNamespaces (closes [#163]) by @WaylandYang in https://github.com/deeplethe/forkd/pull/184
• docs(v0.4): vendor firecracker, document fork strategy by @WaylandYang in https://github.com/deeplethe/forkd/pull/185
• feat(vmm): v0.4 Phase 5a — memfd_create() helper for live-fork backing by @WaylandYang in https://github.com/deeplethe/forkd/pull/186
• feat(vmm): v0.4 Phase 5b — MemoryBackend::MemfdShared via restore_many_with by @WaylandYang in https://github.com/deeplethe/forkd/pull/187
• chore(vendor): refresh FC patch to v1.12 with full build-clean diff by @WaylandYang in https://github.com/deeplethe/forkd/pull/188
• docs(v0.4): add Phase 6 implementation blueprint by @WaylandYang in https://github.com/deeplethe/forkd/pull/189
• feat(vmm): Phase 6.1 — Vm::snapshot_vmstate_only + VmstateOnly FC patch by @WaylandYang in https://github.com/deeplethe/forkd/pull/190
• fix(docs): clear all rustdoc errors under -D warnings by @WaylandYang in https://github.com/deeplethe/forkd/pull/191
• docs(v0.4): Phase 6.1.5 — FC POST /uffd/wp endpoint shipped by @WaylandYang in https://github.com/deeplethe/forkd/pull/194
• feat(vmm): Phase 6.2 — Vm::memfd_handle + Vm::request_wp_uffd by @WaylandYang in https://github.com/deeplethe/forkd/pull/195
• fix(controller): /healthz auth bypass accepts trailing slash too by @WaylandYang in https://github.com/deeplethe/forkd/pull/197
• feat(uffd,vmm): Phase 6.3a — WpBranch::begin_with_external_uffd + PauseGuard by @WaylandYang in https://github.com/deeplethe/forkd/pull/198
• feat(controller): Phase 6.3b — mode="live" path in branch_sandbox by @WaylandYang in https://github.com/deeplethe/forkd/pull/199
• feat(controller): Phase 6.4 — wait=false live BRANCH + InFlightBranches by @WaylandYang in https://github.com/deeplethe/forkd/pull/200
• feat(controller): expose live_fork on CreateSandboxRequest by @WaylandYang in https://github.com/deeplethe/forkd/pull/201
• fix(v0.4): wire cross-process WP correctly + 2 latent bugs caught by E2E by @WaylandYang in https://github.com/deeplethe/forkd/pull/202
• feat(controller): Phase 7.1 — canonical mode field on BRANCH by @WaylandYang in https://github.com/deeplethe/forkd/pull/204
• feat(cli): Phase 7.2 — --live and --no-wait flags on forkd snapshot by @WaylandYang in https://github.com/deeplethe/forkd/pull/205
• feat(sdk): Phase 7.3 — mode/wait/live_fork across Python, TS, MCP by @WaylandYang in https://github.com/deeplethe/forkd/pull/206
• feat(doctor,uffd): Phase 7.4 — uffd_wp + memfd_create capability checks by @WaylandYang in https://github.com/deeplethe/forkd/pull/207
• docs: align README + API.md + CHANGELOG with shipped v0.4 live-fork surface by @WaylandYang in https://github.com/deeplethe/forkd/pull/208
• bench(v0.4): Phase 7.5 — live BRANCH pause-window data on a clean source by @WaylandYang in https://github.com/deeplethe/forkd/pull/210
• feat(cli): forkd fork --live-fork — memfd-backed children for local v0.4 path by @WaylandYang in https://github.com/deeplethe/forkd/pull/211
• feat(vmm): v0.5 Phase 1 — diff snapshot chain resolver + schema by @WaylandYang in https://github.com/deeplethe/forkd/pull/213
• feat(controller): v0.5 Phase 2a — chain-aware spawn by @WaylandYang in https://github.com/deeplethe/forkd/pull/214
• feat(cli,controller): v0.5 Phase 2b — forkd snapshot-diff build verb by @WaylandYang in https://github.com/deeplethe/forkd/pull/215
• v0.5 Phase 5 — chain-spawn bench + Phase 2a chainstage path fix by @WaylandYang in https://github.com/deeplethe/forkd/pull/217
• v0.5 Phase 4 — snapshot-info, chain-aware rmi, snapshot-compact by @WaylandYang in https://github.com/deeplethe/forkd/pull/219
• v0.5 Phase 3 — chain-aware pack/unpack (Hub manifest v2) by @WaylandYang in https://github.com/deeplethe/forkd/pull/220
• v0.5 Phase 6 — README + API.md + HUB.md + CHANGELOG docs by @WaylandYang in https://github.com/deeplethe/forkd/pull/221
• test(e2e): v0.5 chain end-to-end fixture by @WaylandYang in https://github.com/deeplethe/forkd/pull/222
• release: v0.5.0 — workspace version bump + CHANGELOG header by @WaylandYang in https://github.com/deeplethe/forkd/pull/223

Full Changelog: https://github.com/deeplethe/forkd/compare/v0.3.4...v0.5.0