docker-sandbox

name	docker-sandbox
description	Docker usage in readme2demo — the base image, hardened sandbox lifecycle, the Docker-socket opt-in, and diagnosing container/daemon failures. Use when touching sandbox.py, images/base/Dockerfile, render.py, verify.py, or when a run fails with a docker/daemon/permission/disk error.

Docker & the sandbox

The container IS the security boundary. READMEs are untrusted code; the agent runs INSIDE the container so --dangerously-skip-permissions is safe.

The base image (images/base/Dockerfile)

• Built FROM ghcr.io/charmbracelet/vhs:latest so ONE image serves the agent run, the verify replay, AND the video render (vhs + ttyd + ffmpeg from the base; git/Go/Python/Node + Claude Code added on top). This is why the video can execute real toolchain steps on camera.
• ENTRYPOINT [] + CMD ["bash"]: the VHS image ships ENTRYPOINT ["vhs"]; reset it so sandbox.py can run arbitrary commands. The renderer re-invokes vhs via --entrypoint vhs.
• Go comes from the official tarball at build time (distro packages lag and strand agents on "go >= 1.2x required"). Rebuild periodically to stay current.
• The Claude Code npm pin is COUPLED to the stream-json parser (engines/claude_code.py) — bump them together.
• Rebuild after ANY Dockerfile change: docker build --no-cache -t readme2demo/base:latest images/base/. The render stage preflights the image (render.check_render_image) and errors clearly if it's stale (missing vhs/ffmpeg/git).

Hardening (sandbox.py — never weaken without discussion)

Every container: --cap-drop ALL, --security-opt no-new-privileges, --memory/--cpus/--pids-limit, non-root user demo (uid 1000), wall-clock timeout, destroyed after the stage. Run dirs are mounted with ABSOLUTE paths (docker -v treats relative as a volume name).

Docker-socket opt-in (--allow-docker-socket)

For tools that manage containers themselves (toolhive thv run, testcontainers, compose repos). Mounts /var/run/docker.sock into agent + verify + render. The non-root user needs --group-add $(socket gid) — sandbox.docker_socket_gid probes it (stat -c %g) or every socket call is EACCES and the tool reports "no container runtime available" despite the mount. Pierces isolation: trusted repos only; the CLI prints the warning in red.

Diagnosing docker failures

• input/output error / containerd meta.db → Docker VM disk full (VHS writes a PNG per frame). docker system prune -af --volumes; restart Docker Desktop; raise the VM disk. The render mitigations (24fps, mp4-only, short ffmpeg gif preview) exist because full-length GIFs once filled the disk.
• exit 125 from docker run → bad flags / relative mount path — check the Sandbox args.
• "no container runtime available" WITH --allow-docker-socket → group-add gid problem (above).
• verify passes but render image errors → stale base image; rebuild.