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

The tag is required — sbx does not default to :latest for registry kits. Pin a specific kit release instead if you want reproducible sandboxes, e.g. docker.io/pungrumpy/docker-doctor-kit:0.1.0. Each kit release installs an exact, pinned CLI version.

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

At sandbox creation, before the agent starts:

  1. Installs the CLI — a pinned @docker-doctor/cli from npm. The only network access the kit needs is registry.npmjs.org, and npm verifies the tarball against the registry's integrity metadata, so the version pin also pins content.
  2. Installs the agent skill — docker-doctor install --global places the /docker-doctor triage skill in the sandbox home for Claude Code, Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot, Droid, and Kiro. Nothing is written to your mounted workspace — your git status stays clean.
  3. Injects agent memory — a short instruction: after editing any Dockerfile or Compose file, run docker-doctor and 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

  • A base template with Node.js — every standard agent template ships it (claude-code-minimal does not).
  • sbx with kits support (kits are marked experimental by Docker; the kit tracks the v2 spec).

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