# Docker Sandbox

> Docker Sandbox is an Agent Skill for devops & security published in the infection/infection repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Maintain Infection's Docker Sandbox image and sbx template. Use when asked to add, remove, or upgrade sandbox tooling; change the PHP sandbox image; update Codex sandbox telemetry; recreate or load the codex-infection sandbox; or diagnose devTools/sbx image and test failures.

- Skill name: `docker-sandbox`
- Category: [DevOps & Security](https://www.openparable.com/skill/devops-security/1)
- Source: https://github.com/infection/infection/blob/HEAD/.codex/skills/docker-sandbox/SKILL.md
- Repository: infection/infection (2,223 GitHub stars when collected)

## SKILL.md

# Docker Sandbox

## Mental Model

- Docker Sandbox means Docker's `sbx` product: kernel-isolated development environments built from
  templates and kits. It is not a plain `docker run` container.
- Infection's sandbox lives under `devTools/sbx/` and extends
  `docker/sandbox-templates:codex-docker`.
- This image supports Codex/PHP sandbox work in this repository. It is separate from
  `devTools/Dockerfile`, which supports the normal Docker Compose development flow.
- Do not install tools into a running sandbox as the fix. Runtime installs are disposable and do not
  change the shared image.

## Workflow

1. Read `devTools/sbx/README.md` first. Treat it as the local source of truth for usage, commands,
   telemetry notes, and manual `sbx run` examples.
2. Inspect the specific implementation file before editing:
   - image/tooling: `devTools/sbx/Dockerfile`
   - image contract: `devTools/sbx/test.yaml`
   - build and load behaviour: `devTools/sbx/build-image.sh`, `devTools/sbx/load-template.sh`,
     `devTools/sbx/config.sh`
   - Codex telemetry kit: `devTools/sbx/codex-otel.toml`,
     `devTools/sbx/codex-otel-kit/spec.yaml`, and files under
     `devTools/sbx/codex-otel-kit/files/`
   - public targets: `Makefile`
   - CI behaviour: `.github/workflows/sbx-image.yaml`
3. For image tooling changes, update `devTools/sbx/Dockerfile`, then add or adjust matching
   assertions in `devTools/sbx/test.yaml`.
4. For PHP version changes, update every image-name/version reference consistently, including
   `devTools/sbx/config.sh`, tests, `Makefile`, and `devTools/sbx/README.md`.
5. Validate with the build or test command documented in `devTools/sbx/README.md`. If `sbx` is not
   available, do not claim to have loaded or recreated the sandbox; report the partial validation.

## Guardrails

- Every baked-in tool and meaningful runtime setting should have a `container-structure-test`
  assertion.
- Prefer `apt` packages in the existing install block when available.
- For downloaded binaries, use a version `ARG` when practical and follow the existing
  `CONTAINER_STRUCTURE_TEST_VERSION` style.
- Keep comments tied to why Infection needs the tool.
- `sbx` lifecycle commands require the host `sbx` CLI. Docker image builds/tests may work anywhere
  Docker and `container-structure-test` are available.
- `sbx` kits apply at sandbox creation. Recreate the sandbox or add the kit explicitly when kit
  behaviour changes.

## Resources

- Local usage: `devTools/sbx/README.md`
- Docker Sandboxes overview: https://docs.docker.com/ai/sandboxes/
- `sbx` CLI reference: https://docs.docker.com/reference/cli/sbx/
- Custom templates and
  `sbx template load`: https://docs.docker.com/ai/sandboxes/customize/templates/
- Kits: https://docs.docker.com/ai/sandboxes/customize/kits/
- Kit spec reference: https://docs.docker.com/ai/sandboxes/customize/kit-reference/
- Container Structure Test: https://github.com/GoogleContainerTools/container-structure-test

## Don't

- Do not use `apt-get install`, `composer global require`, `npm install -g`, or similar inside a
  running sandbox as the fix.
- Do not replace the `sbx` template flow with an ad hoc `docker run`.
- Do not update `devTools/Dockerfile` for sandbox-only requirements.

---

Source: https://www.openparable.com/skill/devops-security/docker-sandbox (OpenParable). Cite the canonical URL above.