Executive Overview & Architectural Significance

The release of Docker's Sandbox Kit Specification v3 marks a profound shift in how developers handle autonomous AI agents and complex, probabilistic workloads. Traditional containerization models, while exceptional for deterministic applications, rely on shared kernel architectures (namespaces and cgroups) that fall short when confronted with agents capable of rewriting their own execution paths, probing system calls, and installing unvetted dependencies. Docker Sandbox Kit Specification v3 addresses this gap by decoupling application packaging from execution boundaries, relying on underlying microVMs to guarantee that execution damage remains strictly isolated.

At its core, a Kit bridges the missing link between the application runtime and its operational privileges. While a Dockerfile defines software construction and baseline configuration, it entirely omits the ambient environment—networks, credentials, volumes, and invocation contexts—which historically scattered across brittle docker run flags, undocumented shell histories, and CI pipelines. By re-architecting Kits into ordinary Open Container Initiative (OCI) images using the vnd.docker.sandbox.kit.descriptor manifest annotation, Docker ensures that security policies, permissions, and agent dependencies travel atomically with the container image. This guarantees consistent runtime behavior and deterministic enforcement across any conforming OCI-compliant runtime infrastructure.

Core Enhancements & Developer Ergonomics

The evolution to v3 introduces transformative developer ergonomics centred around capability-based security and immutable cryptographic digests. Because a Kit is now an ordinary OCI artifact, developers can build images natively via docker buildx build, distribute them seamlessly using standard docker pull mechanics, and integrate them into existing vulnerability scanning and container signing pipelines. Security definitions are expressed through precise, human-readable YAML configurations that explicitly declare permissions—such as network policies, credential proxying, and volume mounts—turning every container launch into a verifiable permission slip where the host retains absolute veto authority.

Furthermore, Kit composition has been fundamentally re-engineered to operate as a functional dependency graph rather than a sequential injection of parameters. Workloads and mixins—modular overlays that append specific CLI capabilities, network rules, or agent context—are dynamically resolved via provides and requires declarations. This strict resolution mechanism eliminates shadow overrides and nondeterministic flag-ordering bugs. If two Kits present contradictory requirements or incompatible overrides, the resolver halts compilation at build time. This shifts security validation from fragile runtime surprises to immediate, compile-time feedback loops.

Architectural Comparison Matrix

| Feature Dimension | Previous Baseline (Dockerfiles & Compose) | Docker Sandbox Kit Specification v3 | Architectural Implication | |---|---|---|---|> | Isolation Boundary | Shared kernel via namespaces and cgroups | Hardware-level microVM with dedicated kernel | Eliminates kernel-probing exploits by autonomous agents | | Permission Management | Unversioned CLI flags, environment variables, manual scripts | Typed, versioned YAML capability manifests (provides/requires) | Converts implicit environment setup into auditable, verifiable grants | | Artifact Distribution | Sidecar configuration files, fragmented Compose files | Native OCI image manifest via vnd.docker.sandbox.kit.descriptor | Unifies packaging, distribution, scanning, and digests into a single artifact | | Composition Logic | Linear inheritance (FROM), sequential override flags | Functional dependency graph resolution | Guarantees deterministic, conflict-free multi-mixin merging |

Breaking Changes & Migration Caveats

Docker Sandbox Kit Specification v3 introduces deliberate breaking changes relative to earlier experimental sbx artifact formats. Previous iterations relied on bespoke sidecar files or custom media types that required specialized registry support. In v3, these legacy formats are completely deprecated in favor of standard OCI image manifests utilizing the vnd.docker.sandbox.kit.descriptor annotation. Existing custom artifacts must be repackaged into OCI-compliant image layouts using updated buildx tooling. Additionally, runtimes that do not implement the v3 specification will treat the new security annotations as inert metadata, effectively disabling capability enforcement. Teams migrating to v3 must audit their existing deployment pipelines to ensure target runtimes are fully conformant before pushing production agent workloads.

Step-by-Step Upgrade Guide

Transitioning your containerized workflows to leverage the Sandbox Kit Specification v3 involves structuring your security requirements directly into your OCI image definitions. Follow these steps to build and run your first conformant Kit:

1. Define Your Capability Manifest: Create a capability configuration within your build structure targeting explicit network and credential constraints. For example, restricting outbound API access:

capabilities:
  - type: com.docker.sandbox/network-policy@2
    config:
      runtime:
        allow:
          - hosts: [api.github.com]
            methods: [GET, POST]
        deny:
          - hosts: [api.github.com]
            methods: [DELETE]

2. Build the OCI Image via Buildx: Compile your workload and embedded capability manifest into a single OCI-compliant image artifact using Docker Buildx:

docker buildx build --annotation vnd.docker.sandbox.kit.descriptor=true -t my-org/agent-kit:v3 .

3. Deploy with a Conforming Runtime: Execute the image within a conforming Docker Sandbox environment, allowing the host runtime to intercept and enforce the declared capability grants:

docker run --runtime=com.docker.sandbox.runtime my-org/agent-kit:v3