The Docker Sandbox Kit specification has been updated to version 3, and the most visible change is that a Kit is now an ordinary OCI image rather than a custom artifact. For engineers who build and run agents, this means the sandbox’s policy, credentials, and overlay mixins travel with the image through the same build, scan, and distribution pipelines you already use, but the policies are only enforced when a runtime that implements the spec – currently Docker Sandboxes – is present.
What Changed in v3
Version 3 replaces the previous side‑car file and custom media type with a single OCI manifest annotation named vnd.docker.sandbox.kit.descriptor. All declarative content – required capabilities, network rules, credential bindings, and mixin layers – is stored as image layers. Because the Kit is now a standard OCI image, you can create it with docker buildx build, pull it with docker pull, and subject it to the same vulnerability scanning and signing tools you already run. The image digest now uniquely identifies both the filesystem payload and the attached policy, eliminating the need for separate version tracking.
Why It Matters to Practitioners
Two Kit types are defined: a workload that provides the root filesystem, and a mixin that overlays additional capabilities such as a CLI, network policy, or credential injection. You launch a single workload and attach any number of mixins, letting you compose an agent’s environment from reusable building blocks. Because the policy lives inside the image, it can be version‑controlled, reviewed, and diffed just like code. This reduces the ad‑hoc, undocumented grants that typically accumulate in shell history or dashboards, and it makes the entire sandbox definition reproducible across teams and weeks.
Architectural and Operational Implications
Enforcement is not automatic. The Kit’s entries are merely requests; a conforming runtime decides whether to honor them. Docker Sandboxes is the first runtime that implements the spec, blocking any host, network, or credential request not explicitly listed. If a runtime does not conform, the annotation is inert and the sandbox runs without the declared restrictions. Consequently, adopting the Kit format requires either deploying Docker Sandboxes or ensuring that any alternative runtime explicitly supports the specification.
From an operational perspective, the shift to a single OCI image simplifies CI/CD integration. Build steps that previously produced a Dockerfile and a separate Kit descriptor can now be collapsed into one docker buildx invocation. The unified digest also means that signing the image automatically signs the policy, and scanning tools see the full attack surface in one pass. Mixins are ordered by a dependency graph rather than a linear sequence, avoiding the “single FROM” limitation of traditional Dockerfiles and enabling true multiple‑inheritance of capabilities.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
- Update your build pipelines to generate Kit images with
docker buildx buildand store them in existing registries. - Integrate Kit scanning into your existing vulnerability and compliance workflows; the policy is now part of the signed artifact.
- Validate that your execution environment runs a conforming runtime (Docker Sandboxes) before relying on Kit‑declared restrictions.
- Adopt mixins as reusable modules for common needs (network whitelists, credential injection, CLI tools) to reduce configuration drift.
- Monitor the Docker Sandbox Kit repository for future spec revisions and runtime updates that could affect enforcement semantics.