Customizing sandboxes
Docker Sandboxes offers two ways to customize a sandbox beyond the built-in defaults:
- Templates — reusable sandbox images with tools, packages, and configuration baked in. Extend a base image with a Dockerfile, or save a running sandbox as a template.
- Kits — declarative YAML artifacts that extend an agent with tools, credentials, network rules, and files at runtime, or define a new agent from scratch.
Kits are experimental. The kit file format, CLI commands, and experience for creating, loading, and managing kits are subject to change as the feature evolves. Share feedback and bug reports in the docker/sbx-releases repository.
Templates and kits, side by side
A template is a Docker image that the sandbox runs. It's built ahead of time with a Dockerfile (or saved from a running sandbox), pushed to a registry, and pulled when a sandbox is created. Use templates for things that belong in an image: system packages, language toolchains, large dependencies — anything you'd rather not reinstall on every sandbox start.
A kit is a YAML artifact applied at sandbox creation. The kit can run install commands, drop files into the sandbox, declare network and credential rules, and (for agent kits) define which template image the agent runs in. Use kits for things that vary per agent or per team: shared linter config, project-specific install steps, credential injection for a service the agent talks to.
Templates and kits work together. An agent kit's agent.image field
points at a template: the template provides the base environment, the
kit layers config, secrets, and runtime behavior on top. A team can ship
one heavy template and several thin kits without rebuilding the image
each time something changes.
When to use which
| Goal | Option |
|---|---|
| Pre-install tools and packages into a reusable base image | Template |
| Capture a configured running sandbox for reuse | Saved template |
| Add a tool, credential, or config to agent runs via YAML | Kit (mixin) |
| Define a new agent from scratch | Kit (agent) |
Templates and kits can be used together. A template bakes heavy tools into the image for fast sandbox startup; a kit layered on top adds per-run credentials, config, or extra capabilities.
Tutorials
- Build your own agent kit — step-by-step walkthrough for packaging Amp as an agent kit.
