Goal

“Let’s start!” (translated from Italian). With the project brief already in CLAUDE.md, that meant running the first-session bootstrap checklist (CLAUDE.md §13): check the environment, create the repository layout and the making-of site, record the first two decisions, and put the seven open decisions to the author. The author’s second message (in English) answered them.

What we did

  • Environment check. Wrote scripts/check-env.sh, a read-only report (make check-env): OS, Python, KVM, sbx version, sign-in state, sbx diagnose local and cloud, which secrets are set (names only), other tools. It ends with a “Tier C ready / Tier L ready” summary. On this Codespace both are “no” (see below).
  • Installed sbx v0.50.0 with the method in CLAUDE.md §6, after confirming it against the install page of the docs and reading what Docker’s convenience script does with REPO_ONLY=1 (adds the apt repository and key, installs nothing else). scripts/post-create.sh now does the same for the devcontainer, pinned to 0.50.0.
  • Verified the commands the wrapper will need with sbx <command> --help (local and --cloud) and the v0.50.0 release notes. Results are in references/sbx-notes.md. Most useful finding: the shell agent is accepted by sbx --cloud create, which was an open question in CLAUDE.md §5.3.
  • Repository layout (CLAUDE.md §7): Makefile (check-env, test, run-NN, diagrams, site-check, site-build), .devcontainer/, four slash commands in .claude/commands/ (/status, /wrap, /verify-sbx, /new-piece), .github/workflows/test.yml and pages.yml, placeholder article.md files for all seven articles and READMEs for the five examples and the shared world.
  • References: bibliography.md, aima-ch2-map.md (seeded from CLAUDE.md §2.3), sbx-notes.md.
  • Site: _config.yml, home page with the series status table, workflow.md with a rendered diagram, index pages for journal, decisions and prompts, _data/series.yml (everything at idea) and _data/metrics.yml.
  • Decisions: ADR-0001 and ADR-0002.
  • Recorded the author’s answers as ADR-0003 to ADR-0008 and applied them: the handle andreagalle in the site config, README and LICENSE-text.md (CC BY 4.0 for prose), and the publication URL in series.yml. CLAUDE.md §0.6 and §12 now point at the ADRs.
  • Commits on dev: 33b55ef (the brief, as the author staged it), e142d71 (scaffold), 2a3317f (references), ae520b0 (site), 34fe102 (ADRs), 23b844c (CLAUDE.md updates). This entry has its own commit, and a last commit ticks the bootstrap checklist.
  • Not yet written: scripts/sbx-run.sh. Its command sequence is verified on paper, but nothing can run until the Codespace is signed in to Docker, so writing it now would mean shipping untested code.

Commands that mattered

From scripts/post-create.sh:

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y "docker-sbx=${pkg}"
npm install -g "@mermaid-js/mermaid-cli@${MERMAID_CLI_VERSION}"

From the Makefile:

make check-env    # scripts/check-env.sh
make diagrams     # mmdc --quiet -i <src>.mmd -o <src>.png --size 1600 -b white
make site-check   # scripts/site-check.sh

Decisions

Dead ends and surprises

  • The GitHub .gitignore template ignored /site. The Python template that GitHub added in the initial commit contains /site (for mkdocs), which would have silently dropped the whole making-of site from git. Removed, with a comment explaining why.
  • KVM is there but out of reach. /dev/kvm exists in the Codespace, but it belongs to GID 109, a group with no name in /etc/group, and the codespace user isn’t a member. sbx diagnose says Virtualization — not accessible. CLAUDE.md forbids privileged workarounds, so nothing was changed. The documented fix is to add the user to the device’s group, and whether that’s acceptable is a question for the author.
  • sbx v0.50.0 was a few hours old. It was released on 2026-10-26 at 14:44 UTC; CLAUDE.md §5.1 had been checked against the v0.49.2 era five days earlier. That’s the release cadence §0.4 warns about.
  • A command the release notes announce isn’t in the help index. sbx --cloud inspect is announced in the v0.50.0 notes and works, but sbx --help doesn’t list it.
  • The docs’ “append .md” rule has an exception. The install page is linked as /ai/sandboxes/get-started/install/, but its raw Markdown lives at /ai/sandboxes/install.md.
  • mermaid-cli 12 changed its flags. -w (width) is gone, replaced by --size. The first make diagrams failed on a flag written from memory: the same failure mode §0.4 guards against for sbx, in a different tool.
  • Headless Chrome needed one system library (libasound2t64) to render diagrams. post-create.sh now installs Chrome’s full library list for a bare devcontainer image.
  • The first two layouts of the workflow diagram tangled the edges. Modelling the sandbox round trip as one two-way edge fixed it.

Who did what

  • The author wrote the project brief (CLAUDE.md) and started the session.
  • Claude ran the bootstrap checklist: environment checks, sbx installation and verification, all scaffolding, references, site pages, ADR-0001/0002 (recording decisions the brief already made) and this entry.
  • The author decided D1, D3, D4, D6 and D7, deferred D2, and asked for D2 and D5 to be explained better. The author kept the git identity and the LICENSE copyright line as they are, and declined to change KVM group membership.

Next

  1. Author: add the DOCKER_ID / DOCKER_PAT Codespaces secrets and set Pages → Source to “GitHub Actions”. Then sign in with sbx login, confirm cloud access with sbx --cloud diagnose, and check which Python the shell template ships.
  2. Write scripts/sbx-run.sh and the shared vacuum world, then example 01. The first cloud run decides whether the wrapper design holds.
  3. Answer D5 once explained; answer D2 before example 03.