From Dockerfile to Kit: the Docker Sandboxes Kit Specification

Introduction to the Docker Sandbox Kit Specification

The Docker Sandbox Kit Specification v3 introduces a new paradigm for defining and managing the permissions and resources available to AI agents and other probabilistic actors within a sandboxed environment. Unlike traditional containers, which are designed for deterministic workloads, sandboxes are tailored for agents that make decisions and interact with the host system in unpredictable ways. The Kit specification addresses the gap in container-based systems by formalizing the external dependencies, permissions, and configurations that an agent requires to operate safely and effectively.

Kit as an OCI Image

The Kit specification leverages the Open Container Initiative (OCI) image format, making it possible to package all necessary declarations—such as network policies, credential bindings, and volume mounts—into a single, versioned OCI image. This approach ensures that the same Kit can be used across different runtimes and environments, as long as they conform to the specification. The Kit is built using standard Docker tools like docker buildx build, pulled with docker pull, and can be scanned and signed using existing tooling. This integration with the OCI ecosystem simplifies the management and distribution of Kit-based environments.

Kit Composition and Declaration

A Kit is composed of two types of components: workloads and mixins. A workload defines the root filesystem and the base environment for an agent, while a mixin is an overlay that adds specific capabilities, such as network policies or credential bindings. Mixins are applied in dependency order, ensuring that the same set of components always results in the same Kit, regardless of the order in which they are specified. This deterministic composition is crucial for ensuring consistency and reproducibility in agent environments.

Authority as Code

The Kit specification formalizes the concept of authority as code, where the permissions and capabilities of an agent are explicitly declared within the Kit itself. These declarations are structured as a set of capabilities, each with a type, version, and configuration. For example, a network policy might specify which hosts an agent is allowed to reach, while a credential binding might define how and when a token is injected into the sandbox. These declarations are not enforced by default; instead, they are requests that must be approved by a conforming runtime.

Conformance and Enforcement

A conforming runtime is responsible for enforcing the capabilities declared in a Kit. If a Kit requests access to a host or resource that is not allowed by the runtime, the launch of the agent is refused. This ensures that agents do not operate with more authority than they are explicitly granted. The specification includes two conformance suites: one to verify that an artifact is a valid Kit, and another to ensure that a runtime behaves according to the specification. This dual-layer verification helps maintain consistency and trust across different implementations.

Practical Implications and Use Cases

The Kit specification is particularly useful in environments where agents are used to perform complex tasks, such as code generation, testing, and infrastructure management. By explicitly declaring the permissions and resources required by an agent, the Kit specification enables more secure and reproducible workflows. It also facilitates collaboration, as the declarations can be reviewed and modified by multiple stakeholders before being deployed. This is especially valuable in development and operations teams where trust and accountability are critical.

Conclusion

The Docker Sandbox Kit Specification v3 represents a significant step forward in the management of AI agents and other probabilistic actors within sandboxed environments. By formalizing the external dependencies and permissions of an agent, the Kit specification ensures that agents operate with the correct level of authority and that their environments are consistent and reproducible. As the specification continues to evolve, it is expected to become a foundational component of secure and scalable agent-based systems.

Source: Docker. Analysis based on publicly available information; no hands-on testing is claimed.