diff --git a/docs/box-design.md b/docs/box-design.md index efc41ad..d55e7ca 100644 --- a/docs/box-design.md +++ b/docs/box-design.md @@ -1,28 +1,30 @@ # box design `box` is a CLI that mints and manages **trust-less, network-isolated VMs -with Claude Code installed**. It is infrastructure, not a project provisioner. +with a coding agent installed** (`claude`, `codex`, `grok`, or `blank` for +none). It is infrastructure, not a project provisioner. See issue #3 for the full reframe and rationale. This doc captures the durable design decisions. ## Principle: separate the tool from the agent -- **The tool** mints isolated boxes with Claude installed but **unauthenticated**. +- **The tool** mints isolated boxes with the agent installed but **unauthenticated**. It knows nothing about projects, secrets, recipes, or memory. -- **The agent** (Claude Code, inside the box) reads an optional `.box/` - runbook in a cloned repo and acts on it. The recipe's consumer is the - reasoning agent, not host machinery. +- **The agent** (Claude Code, Codex, Grok — whichever template, inside the box) + reads an optional `.box/` runbook in a cloned repo and acts on it. The recipe's + consumer is the reasoning agent, not host machinery. ## Boxes are strictly creds-free `box new --name ` launches a blank box: everything installed, **no** -git credentials and **no** Claude credentials. The operator authenticates +git credentials and **no** agent credentials. The operator authenticates interactively *inside* the box: -- **Claude** — `claude` → `/login` (paste-a-code OAuth: copy the URL, open it in - your own browser, paste the code back). Works because the box is outbound-only; - the tool never handles a token. +- **The coding agent** — e.g. `claude` → `/login` (paste-a-code OAuth: copy the + URL, open it in your own browser, paste the code back); `codex` and `grok` + have their own login step. Works because the box is outbound-only; the tool + never handles a token. - **Git** — the operator adds their own PAT / `gh auth login` inside the box. The tool stores and injects **no** credentials, ever. This dissolves the @@ -43,8 +45,9 @@ Log in once → snapshot → spin up authed boxes from it. ## The box announces itself to the agent -cloud-init installs a global `~/.claude/CLAUDE.md` in every box telling Claude it -is running in a box (trust-less, ephemeral, creds-free) and to treat a +cloud-init installs a global agent-context file in every coding-agent box +(`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.grok/AGENTS.md`) telling the +agent it is running in a box (trust-less, ephemeral, creds-free) and to treat a repo's `.box/` folder as its bootstrap runbook. No "tell it" step, no host execution. diff --git a/docs/box-recipe.md b/docs/box-recipe.md index 6d4f345..6544c93 100644 --- a/docs/box-recipe.md +++ b/docs/box-recipe.md @@ -1,14 +1,15 @@ # The `.box/` convention -`box` mints trust-less, creds-free, isolated VMs with Claude Code already -installed (`box new/shell/snapshot/restore/exec/down/start/rm/status`). The -tool knows **nothing** about your project. There is no `install` step and no -host-run setup script. +`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`, `codex`, and `grok` 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 Claude Code (the reasoning agent) running inside the box. It is not -shell that the host executes. +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 @@ -26,15 +27,17 @@ shell that the host executes. ## How it's consumed -Every box ships a global `~/.claude/CLAUDE.md` telling Claude it is inside a -box and to treat a repo's `.box/` folder as its bootstrap runbook. -So the whole flow is: +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 && cd -claude # Claude reads .box/ and brings the project up +claude # the agent reads .box/ and brings the project up ``` The operator can also just say: *"set this project up per .box"*. @@ -45,9 +48,9 @@ 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 Claude. -- **Helper scripts** (e.g. `.box/dev-up.sh`) that the runbook tells Claude - to run. Claude decides to run them; the host never does. + 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. @@ -70,7 +73,7 @@ This is a Node service backed by Postgres. 6. Smoke-test: `curl -sf localhost:3000/health` should return `{"ok":true}`. ``` -That's it — Claude reads it top to bottom and adapts if reality differs. +That's it — the agent reads it top to bottom and adapts if reality differs. ## Guidance @@ -79,4 +82,4 @@ That's it — Claude reads it top to bottom and adapts if reality differs. - **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 Claude infer the steps from the repo's `README` / `CLAUDE.md`. + or let the agent infer the steps from the repo's `README` / `CLAUDE.md`. diff --git a/drill/README.md b/drill/README.md index cdb41e9..d7a06cf 100644 --- a/drill/README.md +++ b/drill/README.md @@ -84,9 +84,9 @@ a **design veto** for #16, caught before the code is written. ## What it does not check -`claude /login` — it's interactive by design, and the box is creds-free by -design. The drill confirms Claude Code is installed and runnable; authenticating -is yours. +agent login (e.g. `claude /login`) — it's interactive by design, and the box is +creds-free by design. The drill confirms each coding-agent template's CLI is +installed and runnable; authenticating is yours. If the host has no `/dev/kvm`, box falls back to container mode. The drill still runs, but it says loudly that **the VM trust boundary was not validated**