box/docs/box-recipe.md

The .box/ convention

box mints trust-less, creds-free, isolated VMs with a coding agent already installed (box new/shell/snapshot/restore/exec/down/start/rm/status) — the claude-box, codex-box, grok-box, and kimi-box templates each ship a CLI agent. The tool knows nothing about your project. There is no install step and no host-run setup script.

A project makes itself easy to stand up inside a box by shipping an optional .box/ folder. This folder is agent-facing documentation — read and acted on by the box's coding agent (the reasoning agent) running inside the box, whichever template you minted. It is not shell that the host executes.

The folder was named .claudebox/ before the 0.5.0 rename. Repos that still ship .claudebox/ keep working — the agent is told to read either — but new projects should use .box/.

What it is / what it is not

• Optional. No .box/ is a perfectly valid state.
• Agent-facing. You are writing instructions to a reasoning agent, not a machine. Prose is fine; the agent adapts.
• Not a host contract. The host never parses, sources, or runs anything in here. There is no enforced schema and no required filenames.
• Old model: a host-executed .devbox/setup.sh. New model: a runbook the agent reads and decides how to act on.

How it's consumed

Every coding-agent box ships a global agent-context file — ~/.claude/CLAUDE.md for claude, ~/.codex/AGENTS.md for codex, ~/.grok/AGENTS.md for grok — telling the agent it is inside a box and to treat a repo's .box/ folder as its bootstrap runbook. So the whole flow is (shown with claude; the other agents follow the same shape):

box new           # get a box
box shell         # get in
git clone <repo> && cd <repo>
claude                  # the agent reads .box/ and brings the project up

The operator can also just say: "set this project up per .box".

Suggested contents (all optional)

Author everything here for a reasoning agent.

• .box/SETUP.md — the prose runbook. Prerequisites, how to install deps, how to start services, how to template the env, how to seed data, and how to smoke-test. Written as instructions to the agent.
• Helper scripts (e.g. .box/dev-up.sh) that the runbook tells the agent to run. The agent decides to run them; the host never does.
• .box/env.template — example env the runbook explains how to fill. Staging values the operator pastes in. Never commit real secrets.
• .box/compose.yml — optional services the runbook starts.

Worked example

A minimal .box/SETUP.md for a Node + Postgres app:

# Setup

This is a Node service backed by Postgres.

1. Install deps: `npm ci`
2. Start Postgres: `docker compose -f .box/compose.yml up -d`
3. Create the env file: copy `.box/env.template` to `.env` and ask the
   operator to fill in `DATABASE_URL` and `API_KEY` (staging values).
4. Run migrations: `npm run migrate`
5. Start the app: `npm run dev`
6. Smoke-test: `curl -sf localhost:3000/health` should return `{"ok":true}`.

That's it — the agent reads it top to bottom and adapts if reality differs.

Guidance

• Keep it declarative and resilient. State intent and steps; let the agent adapt when the repo has drifted. Don't hard-code brittle assumptions.
• Never put real credentials in .box/. Templates and staging placeholders only. The operator pastes real values at runtime.
• No .box/ is fine. The operator can stand the project up by hand, or let the agent infer the steps from the repo's README / CLAUDE.md.