claude-hdb 4eb6b35a7b chore: finish the debrand — env vars, install dir, docs are 'box', not 'claudebox'

The 0.4.0 rename left surface leftovers the user hit through the
CLAUDEBOX_* env vars. Sweep them, drawing a clean line:

  box       = everything the user touches — env vars (BOX_REPO/REF/HOME/
              BIN), installer messages (box-install:), the install tree
              (~/.local/share/box, with the installer sweeping the old
              ~/.local/share/claudebox on upgrade), tool prose, and the
              docs (docs/box-{design,recipe}.md).
  claudebox = the GitHub repo name (URLs, the claudebox-<ref> tarball
              dir, issue refs), the legacy user.claudebox=1 tag, the
              old-stack cleanup code (claudenet/claude-dev/claude-isolate/
              claudebox-firewall), and the .claudebox/ runbook convention
              — a deliberate v1 hold, since renaming it breaks consuming
              repos.

Renamed the two doc files and their links; updated drill.sh/doctor.sh
paths and BOX_REPO/BOX_REF; fixed the claude template's in-box briefing
to say 'box'. RUNS.md left as-is (append-only history). No behavior
change beyond the install-dir move, which the installer migrates.

2026-07-14 17:44:24 +00:00

3.1 KiB

Raw Blame History

The `.claudebox/` 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.

A project makes itself easy to stand up inside a box by shipping an optional .claudebox/ 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.

What it is / what it is not

Optional. No .claudebox/ 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 box ships a global ~/.claude/CLAUDE.md telling Claude it is inside a box and to treat a repo's .claudebox/ folder as its bootstrap runbook. So the whole flow is:

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

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

Worked example

A minimal .claudebox/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 .claudebox/compose.yml up -d`
3. Create the env file: copy `.claudebox/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 — Claude 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 .claudebox/. Templates and staging placeholders only. The operator pastes real values at runtime.
No .claudebox/ is fine. The operator can stand the project up by hand, or let Claude infer the steps from the repo's README / CLAUDE.md.

3.1 KiB Raw Blame History

The .claudebox/ convention