Skip to content

recipes

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

recipes

README.md

Recipes

Two flavors:

  1. Integration recipes (host-side, no rootfs build) — Python scripts that drive forkd from an agent framework, demonstrating the BRANCH + fanout pattern with that framework's idioms. Start here if you want to plug forkd into CrewAI / AutoGen / Swarm / Claude Desktop in five minutes.
  2. Rootfs recipes (parent images) — build.sh scripts that turn public OCI images into forkd parent snapshots. Start here if you want a custom warmed image to fork from.

Integration recipes (host-side)

Read the script, copy the helper, drop it into your project. Each is ~150-250 lines of Python with a --dry-run mode so you can verify the forkd plumbing without an LLM key.

Recipe Framework Forkd-specific value
mcp-agent/ Claude Desktop / Cursor / Cline (via MCP) End-to-end MCP protocol verification — same JSON-RPC framing a real LLM client uses
crewai-fanout/ CrewAI N agents on N microVMs from one warmed parent — per-agent isolation without Docker cold-start
autogen-branch/ AutoGen Forkd-backed CodeExecutor + mid-conversation BRANCH that fans out N alternatives from the same warmed state
openai-swarm/ OpenAI Swarm / Agents SDK Handoff = BRANCH: agent B inherits agent A's full VM state (filesystem, imports, env) on handoff

Rootfs recipes

Ready-made parent-rootfs recipes for common workbench images. Each recipe takes a public Docker / OCI image and turns it into a forkd parent snapshot, so you can fork N warmed children from it in milliseconds.

The pattern is the same across recipes:

# 1. Build a parent rootfs from an upstream image
sudo bash recipes/<name>/build.sh

# 2. Snapshot the warmed parent (one-time per image version)
sudo forkd snapshot --tag <name> \
    --kernel ./vmlinux-6.1.141 \
    --rootfs recipes/<name>/parent.ext4 \
    --tap forkd-tap0

# 3. Fork N children, fan-out workload
sudo -E forkd fork --tag <name> -n 100 --per-child-netns

Available rootfs recipes

Recipe Parent image Size Audience
python-numpy/ python:3.12-slim + python3-numpy ~1.5 GB The canonical fan-out demo; what the chart on the front README measures
e2b-codeinterpreter/ e2bdev/code-interpreter ~600 MB AI code-execution agents (Anthropic / OpenAI tutorials use this image). Lightest "agent ready" option
jupyter-kernel/ quay.io/jupyter/scipy-notebook ~3 GB Code-interpreter / notebook-style agents — full SciPy stack pre-imported, ~1 ms per fresh kernel instead of ~2 s
coding-agent/ python:3.12 + git + ruff + black + pytest ~1.8 GB SWE-style coding agents that need a real dev toolchain inside the sandbox
nodejs/ node:22-slim ~250 MB JavaScript / TypeScript workloads (Jest, Playwright fan-out)
playwright-browser/ mcr.microsoft.com/playwright (Node + Chromium pre-warmed) ~2.5 GB Browser-driving agents (computer-use, web research, UI test gen). Fork warmed headless Chromium at ~10 ms instead of ~2 s. Alpha
agent-workbench/ agent-infra/sandbox (browser + VSCode + Jupyter + MCP + shell) ~5 GB Kitchen-sink agent workbench when you want every tool already mounted; trades a bigger memory.bin for batteries-included
postgres-fixture/ postgres:16 (initdb done, postmaster pre-launched) ~500 MB Fork-per-test isolated databases; each child gets a ready-to-query postgres in ~10 ms instead of ~2 s for fresh initdb

Choosing a recipe

By framework / driver (integration recipes):

  • Claude Desktop / Cursor / Cline → mcp-agent/
  • CrewAI multi-agent crew → crewai-fanout/
  • AutoGen ConversableAgent / GroupChat → autogen-branch/
  • OpenAI Swarm / Agents SDK → openai-swarm/

By workload (rootfs recipes):

  • You're benchmarking → python-numpy/
  • You're running an AI code interpreter → e2b-codeinterpreter/
  • You need the full SciPy / notebook stack → jupyter-kernel/
  • You're running a coding agent (SWE-bench style) → coding-agent/
  • JS / TS only → nodejs/
  • Browser-driving agent (computer-use, scraping, UI testing) → playwright-browser/
  • You want browser + IDE + everything in one box → agent-workbench/
  • You're running a test suite that needs an isolated DB per test → postgres-fixture/

Notes

  • Recipes are tested on Ubuntu 24.04 / Linux 6.14 / x86_64. Other distros may need adjustments to scripts/build-rootfs.sh.
  • The first-time build.sh of each recipe takes a few minutes (pulling the Docker image + converting to ext4). The snapshot step is ~10 s. After that, forking children is the published benchmark cost.
  • Each recipe is self-contained — pick one, run it; you don't need to understand the others.