Feature Catalog

This section is for the people building Devboxes, not using it. The code is the reference for how it works — read it. Each entry here records the three things code cannot tell you:

1. What a feature is — its behavior contract, stated so that a refactor with identical behavior never falsifies it.
2. How to test it — the suites that prove the contract and the manual smoke path, so a change to the feature starts from its proof.
3. Decisions — choices someone might re-litigate or accidentally undo, each with the why that made it win over the obvious alternative.

Read it in run-lifecycle order

The entries follow a run's life — each leans only on what came before:

1. Working on Devboxes — run the stack, test it, pass the gate.
2. Organizations, roles & access — who can act; everything below gates on it.
3. Transactional email — the mail that carries invitations, verifications, and confirmations out.
4. Repository connections — how code gets in and how a project binds to it.
5. Runner images — the container a run needs before it can be claimed.
6. Blueprints — the step plan a run snapshots at dispatch.
7. Environment entries — the frozen environment a run carries.
8. Runners & provider credentials — how a claimed run gets its model provider credential, and why claiming filters by provider.
9. Dispatch lifecycle — the queue machinery tying all of the above together: claims, leases, budget, reaper.
10. Agent session events — what streams back out while the run executes.
11. Security audit log — the append-only trail of who did what across all of the above.

Every backend suite runs against real boundaries: an embedded Postgres with the real migrations applied, real HTTP handling, real auth rows — no database or auth mocks. The complete suite graph is available through pnpm vp run validate:full; default signoff is checks-only.

Next: Working on Devboxes — run the stack first.