Skip to content

Docker Sandboxes

Preinstall Docker Doctor in every Docker Sandbox so coding agents lint their own Dockerfile and Compose changes before committing.

On this page

Docker Sandboxes run AI coding agents unattended inside disposable, hardware-isolated microVMs — each sandbox gets its own kernel, filesystem, network policy, and a private Docker daemon. It's the natural home for "YOLO mode" agent sessions: the agent can build images, run Compose stacks, and edit anything, and the host stays safe.

Safe for your host, that is. The Dockerfiles the agent writes still ship to production. That's the gap the Docker Doctor kit closes: every sandbox comes up with the linter preinstalled and the agent instructed to use it.

Install the kit

Kits extend a sandbox at creation time. The Docker Doctor kit is published to Docker Hub, which sbx trusts by default — no configuration needed:

sbx run --kit docker.io/pungrumpy/docker-doctor-kit:latest claude

Kit releases from 0.2.0 on need sbx 0.51 or later. The tag is required, because sbx does not default to :latest for registry kits. Pin a kit version tag instead if you want reproducible sandboxes. Each kit release ships one exact, pinned CLI version.

On sbx older than 0.51, use docker.io/pungrumpy/docker-doctor-kit:0.1.14, the last kit in the v2 format. From 0.51 on, the built-in agents such as claude are v3 kits, and sbx refuses to combine them with v1 or v2 kits (release notes).

It's a mixin kit, so it composes with any agent (claude, codex, gemini, opencode, …) and stacks with your other kits.

You can also pull it straight from the repository (requires allowing the source once with sbx settings set kit.allowedSources '["docker.io/","github.com/PunGrumpy/"]'):

sbx run --kit "git+https://github.com/PunGrumpy/docker-doctor.git#dir=kits/docker-doctor" claude

What the kit does

The kit is a Kit Specification v3 image, so everything it adds is ready before the agent starts:

  1. The CLI. A pinned @docker-doctor/cli with its own Node.js runtime, and docker-doctor on the PATH. The base image needs no Node.js, and sandbox creation does not download the CLI from npm. npm verifies the tarball against the registry's integrity metadata when the kit is built, so the version pin also pins content.
  2. The agent skill. The /docker-doctor triage skill ships with the CLI. sbx exposes it in every skills directory the agent's kit declares, which today means ~/.claude/skills for Claude Code and ~/.agents/skills for Codex. With other agents, the agent memory below names the skill's path in the image. Nothing is written to your mounted workspace, so your git status stays clean.
  3. Agent memory. A short instruction tells the agent to run docker-doctor after editing any Dockerfile or Compose file, and to fix the diagnostics before committing.

The result: the agent writes a Dockerfile, lints it, fixes what it finds, and only then commits — without you asking.

Verify it

Inside a sandbox created with the kit:

sbx exec <sandbox> -- docker-doctor --version
sbx exec <sandbox> -- ls ~/.claude/skills/docker-doctor

Or just watch the agent: ask it to containerize something and it should run docker-doctor on its own before committing.

Mind the mounts

A sandbox isolates the agent from the host, with one deliberate exception: the workspace you mount into it. That shared folder is served from the host, so a bug in the file server turns a writable mount into a hole in the VM. CVE-2026-77179 was exactly that: a container on Docker VMM opened a file, deleted its directory, replaced it with a symlink, and read and wrote anywhere on the macOS host. It is fixed in Docker Sandboxes 0.42.0 and Docker Desktop 4.88.0.

The defense that does not depend on the hypervisor is to mount less and mount read-only. Docker Doctor enforces that for the Compose files the agent writes:

  • no-broad-bind-mount warns when a service bind-mounts /, ~, a hidden directory like ~/.ssh, a parent of the project, or a system directory.
  • prefer-read-only-bind-mount reports bind mounts outside the project that are not marked :ro.

Apply the same rule to the sandbox itself: mount the one repository the agent is working on, not your home directory.

Requirements

  • sbx 0.51 or later for kit 0.2.0 and later. The kit follows Kit Specification v3, and Docker marks kits as experimental. On older sbx, use the 0.1.14 tag.
  • A glibc-based agent image, which every built-in agent has. The bundled Node.js runtime needs glibc and libstdc++.

The kit's source of truth lives at kits/docker-doctor in the monorepo.