The Zygo book

← Previous page: the project README — the book’s first page, and the five-minute version of everything below.

All of Zygo’s documentation, in one place, written to be read from the start.

It begins with Container 101: what the Linux kernel gives you to build a sandbox, and what Docker builds from it. Then it explains Zygo — how it works, where it saves time and memory, and how it compares with everything around it. Then it teaches you to use it, and ends with the full reference: every command, every flag, every field, every file and every exit code. You do not need to know any of it already. If you can use a shell and you know what a process is, you can read every page.

Each section is short on purpose — a few sentences, a picture where one helps, and a link to the detail. Read Parts I and II once; after that, the headings work as a reference. This book is the source of truth: when Zygo changes, the book changes in the same commit (AGENTS.md).

Part I — Container 101


0	The project README	What Zygo is, why it exists, and how to try it — the first page.
1	The kernel and the process	What a process is, how one is born, and who may do what.
2	Namespaces	How a process gets its own view of the machine.
3	Control groups	How a group of processes gets a limit on what it can use.
4	The other locks	Capabilities, seccomp, Landlock, the root filesystem, the network.
5	Docker	What a container is, what an image is, and where Docker’s time goes.

Part II — Zygo, explained


6	How Zygo works	The one-shot sandbox, the warm zygote, and the parts around them.
7	Where the time and memory are saved	Each saving, how big it is, and what it costs.
8	The rules Zygo is built on	Eight principles, and the price of each.
9	FreeBSD jails, and Zygo	The older idea, and whether “jails for Linux” is fair.
10	Similar projects, and Docker side by side	nsjail, bubblewrap, kern, gVisor, Firecracker…; `docker run` against `zygo run`, flag by flag.

Part III — Using Zygo


11	Getting started	Install, check the host, run a sandbox, warm a function.
12	One-shot sandboxes	`zygo run`, step by step.
13	Warm functions	Handlers, warm-exec, runtime pools, and living with them.
14	Limits, networking and secrets	What each limit does, the egress allowlist, secrets as files.
15	Images and dependencies	Registries, venvs, apt layers, bytecode, cleaning up.
16	Deploying and running in production	`zygo up`, watching, upgrading, containers, Kubernetes, capacity.
17	The HTTP API, the SDKs and MCP	Calling Zygo from a program or an AI agent.
18	Writing an agent	A warm path for a language of your own.

Part IV — Reference


19	Every command	Every command and flag, with defaults and exit codes.
20	`sandbox.toml`, field by field	Every section and field, its default and its rules.
21	Environment, files and exit codes	Every variable read, every file written, every way it ends.
22	Troubleshooting	The errors people hit, and the fix for each.

Part V — Security and speed


23	Security: the threat model	Every attack, what stops it, and whether a test tries it.
	Fork safety, question by question	What a forked request shares, what it does not, and where that is weaker than it sounds.
24	Seccomp profiles	The three syscall profiles, and which to choose.
25	What Zygo costs	Every measured number, and the machine it came from.

Part VI — Decisions


26	Why it is built this way	The design decisions in plain words; the full records are in `adr/`.
	Glossary	Every term in the book, in one line each.

Where to start

  first time here? ────────────────▶ the README, then this page
  new to containers? ──────────────▶ Part I, then Part II
  know Docker, new to Zygo? ───────▶ chapters 6, 7, 10, then 11
  want to use it today? ───────────▶ chapter 11, then 13
  looking something up? ───────────▶ Part IV
  deciding whether to trust it? ───▶ chapter 23

Three sentences to hold on to

A container is not a thing in the kernel. It is a normal process with several limits put on it; the kernel has no idea what a “container” is.
The limits are cheap; the tools around them are not. Setting up the limits takes about a millisecond. Docker takes hundreds, and most of that is programs talking to programs.
Zygo removes the tools, then removes the start-up. It sets the limits up itself, in one process, and then keeps a ready copy of your program waiting, so a request costs one fork().

How the numbers are used

Every number about Zygo in this book comes from chapter 25, which names the machines and the commands. Numbers about other projects are their own claims or commonly measured ranges, and they are marked that way. zygo bench all repeats Zygo’s numbers on your own machine.

Keyboard shortcuts

The Zygo book