Executive Overview & Architectural Significance

The software engineering landscape has reached a critical inflection point regarding autonomous AI agents. A decade ago, the container ecosystem faced a similar fragmentation crisis, which was successfully resolved when Docker donated its image format and the Runc runtime to the Linux Foundation, establishing the Open Container Initiative (OCI). Today, a parallel challenge emerges around artificial intelligence agents: while Model Context Protocol (MCP) successfully standardized how agents communicate with external tools, there has been a complete absence of a shared, portable artifact format defining what an agent is structurally permitted to do. To solve this systemic security and portability gap, Docker has partnered with the Cloud Native Computing Foundation (CNCF) to introduce the Docker Sandbox Kit Specification, open-sourced under the Apache 2.0 license.

Architecturally, this release fundamentally redefines how agentic workflows are packaged, governed, and secured. Traditional container images were designed for immutable software components, encapsulating the application build logic while deliberately omitting runtime operational boundaries. Web services could easily operate within these loose boundaries by simply claiming a network port. In contrast, modern AI agents like Claude Code or Codex are inherently mutable; they dynamically install packages, execute API calls, manipulate local credentials, and continuously alter their execution environment. By leveraging existing OCI extension points rather than creating a proprietary runtime format, Docker Kits combine the agent binary, its toolchain, and a strictly typed capability manifest into a singular, unified OCI image. This guarantees that pinning an image inherently pins the exact operational permissions and access boundaries of the agent, creating a truly portable trust model.

Core Enhancements & Developer Ergonomics

The core engineering breakthrough of the Docker Sandbox Kit Spec is its ability to transform runtime permissions into immutable, version-controlled artifacts. A Kit encapsulates three vital components within a single standard image: the execution agent itself, the integrated tools, and a strongly typed manifest delineating requested operational scopes such as host endpoints, credential stores, and volume mounts. Because this manifest travels directly inside the OCI artifact, teams can seamlessly inspect, diff, sign, and scan agent permissions using existing registry pipelines, security scanners, and artifact signing tools without deploying auxiliary infrastructure. When an agent definition updates to request expanded system access, the permission delta manifests clearly as added lines within a standard code review.

Developer ergonomics are radically streamlined through ecosystem-wide collaboration. Docker has coordinated directly with major technology leaders—including AWS, Box, Datadog, Dynatrace, JFrog, Palo Alto Networks, and Snyk—to ensure out-of-the-box compatibility across cloud platforms, observability stacks, and security linchpins. This collaborative ecosystem allows database vendors, agent developers, and internal enterprise platform teams to publish pre-scoped Kits directly to standard registries. Consequently, engineers can bootstrap compliant, highly secure agentic workflows instantly, inheriting vetted guardrails without sacrificing the velocity required in modern software development lifecycles.

Architectural Comparison Matrix

Breaking Changes & Migration Caveats

Fully backwards-compatible with previous releases. Because the Docker Sandbox Kit Spec is implemented entirely on top of established OCI image specification extension points rather than establishing a completely isolated or forked artifact format, existing container registries, vulnerability scanners, and signing mechanisms will experience zero breaking changes. Standard OCI tooling can pull, push, and store Kits natively. However, organizations migrating legacy, unmanaged agent execution pipelines to the new Kit standard must explicitly define their capability manifests. Teams transitioning from ad-hoc script-based agents will need to audit their runtime dependencies and explicitly codify their required host endpoints, credential mounts, and network rules into the typed Kit specification manifest.

Step-by-Step Upgrade Guide

Transitioning your autonomous agent workflows to leverage the new Docker Sandbox Kit Spec requires three straightforward configuration and build steps:

1. Define the Kit Manifest & Dockerfile: Create a standard OCI-compliant definition incorporating your agent binary, required tools, and the strongly typed capability schema (kit.yaml) outlining explicit network and volume boundaries.

apiVersion: sandbox.docker.com/v1alpha1
kind: Kit
metadata:
  name: secure-code-agent
spec:
  agent: ./bin/agent
  capabilities:
    hosts:
      - "api.anthropic.com"
    volumes:
      - source: "./workspace"
        destination: "/app/workspace"
        readOnly: false

2. Build and Tag the OCI Image: Leverage your standard container build tooling to package the agent and its declarative capability manifest into a single OCI-compliant artifact.

docker build -t myregistry.azurecr.io/agents/secure-code-agent:v1.0.0 .

3. Push and Enforce via Conforming Runtime: Push the unified Kit to your enterprise registry of choice and execute it within a conforming runtime environment (such as Docker Sandboxes) to automatically enforce the bundled security guardrails.

docker push myregistry.azurecr.io/agents/secure-code-agent:v1.0.0
docker sandbox run myregistry.azurecr.io/agents/secure-code-agent:v1.0.0