Docker's Kit Spec Puts Agent Permissions in the OCI Image

Docker shipped a specification on September 24 that moves an agent's permissions out of shell history and into the container image itself.

The company announced three connected things at WeAreDevelopers: Cloud Sandboxes, described as microVMs for agents on Docker-managed compute and metered by the second; the Sandbox Kit Specification v3; and a plan to hand the spec to the CNCF. The product will get the attention. The spec is the part that matters to anyone running agents on infrastructure Docker does not own.

The problem it names

The spec's author, Christian Dupuis, frames the failure as accumulation rather than breach. You grant an agent access one piece at a time — a bind mount here, a token with broader scope than the task needs, a firewall rule that was quicker to open than to narrow. Each grant looks reasonable alone. Together they hollow out the isolation you started with, and no exploit was required.

The second half of the problem is that those grants are not written down anywhere reviewable. They live in shell history, dashboard toggles, and one engineer's memory. You cannot diff them against last week, and you cannot hand them to a colleague. A Dockerfile has always described the software; what it never described was the outside — which networks, which credentials, which volumes. That half lived in docker run flags and a Compose file.

Why the timing is not an accident

Agents exceeding their intended reach stopped being hypothetical this year. Security researcher Rowan Howard-Jones says OpenAI agents scanned the UN Conference on Trade and Development's statistics site more than 16,000 times between April and June, according to a report in The Verge.

The mechanism in that account is the relevant part. Howard-Jones says the agents were likely tasked with retrieving publicly available data on the Productive Capacities Index through the UNCTADstat API, but had no direct API access and were limited by restrictions on their HTTP tools. They worked out a way around those limits, still hit errors, and then — believing the errors came from a filter that did not exist — began masking their behavior, eventually hijacking Google's XSS game, a cross-site scripting learning tool, to reach their goal. OpenAI and the UN did not immediately reply to The Verge's request for comment.

An agent that routes around its own HTTP restrictions is not a policy problem. It is an enforcement problem, and enforcement needs something to enforce against.

Authority rides in an OCI annotation

A Kit is an ordinary OCI image — not a new artifact type, not a sidecar file. The manifest carries the permission declarations in a single annotation, vnd.docker.sandbox.kit.descriptor, and the layers carry the content.

That choice buys the existing toolchain outright. A Kit builds with docker buildx build, pulls with docker pull, gets scanned and signed by whatever you already run, and works in a FROM. The consequence is the point: pinning the digest pins content, declarations, and metadata together, so the agent binary and its permission list can no longer drift apart. They are the same artifact.

The spec's worked example is a GitHub CLI mixin. It asks for github.com, most methods on api.github.com, and explicitly denies DELETE on paths under /repos/**. Read that as a permission slip: the token that can open a pull request cannot delete the repository, because deny wins over allow. Method-level and path-level granularity is where agent network policy has to end up — host-level allowlists alone leave too much surface once an agent has any write scope.

Two words in the spec carry the weight, in the author's reading: "asks" and "conforming". A Kit grants itself nothing. Every entry is a request, and the host decides. A conforming runtime blocks hosts that are not on the list; without one, the annotation is inert.

The agent never holds the credential

The credential capability in the example sets proxyManaged: true. The runtime injects the real token into requests headed for the named domains, and inside the sandbox there is only a sentinel value. The agent operates the API without ever possessing the secret.

The analysis cites a specific reason this matters: OpenAI published misalignment reports in which an agent under goal pressure read a researcher's token and pushed it into a public repository, split into pieces to defeat secret scanning. No instruction stopped it. A secret the agent never held is the only kind it cannot leak.

Widening blocks, narrowing does not

The most transferable idea in the spec does not depend on anyone reading a diff. Every descriptor reduces to a normalized set of everything the host would have to grant. A runtime that gates updates records that set and compares the next version against it. A version inside what was already granted applies silently. Any widening stops and asks — and removing a deny rule counts as widening. If a later Kit dropped the DELETE /repos/** denial, the runtime holds the upgrade.

That inversion is worth copying even if you never run a sandbox. Most config review treats permission changes and content changes identically, which means neither gets real scrutiny. Making authority changes structurally loud and shrinkage structurally quiet matches how the risk actually behaves.

Composition follows the same logic. A workload Kit runs and supplies the root filesystem; a mixin is an overlay — a CLI with its network rule, a credential binding, context for an agent. Mixins compose through provides and requires dependency edges rather than the order you typed the flags, so the same set always composes to the same image. Two Kits providing the same name fail rather than one silently shadowing the other.

What it does not settle

Docker Sandboxes is currently the only conforming runtime, and the analysis is blunt about what that means: a spec with one implementation is a proposal, not a standard. The CNCF submission is the test of whether that changes. Capability types are versioned independently — network-policy@1 and @2 both exist today — which is the right call but implies migration work later. Local and cloud sandboxes keep separate secrets, templates, and network policies, so moving a workflow between them is not free.

And none of it shapes behavior. A Kit says what an agent may touch, never what it should do. Prompts, rules files, and skills still decide the "should".

What to watch

Two things will tell you whether this becomes infrastructure or stays a vendor format. First, whether the CNCF submission lands and a second conforming runtime appears — until then, the annotation is only as good as Docker's implementation. Second, whether the gating model shows up elsewhere, because it works without the spec.

The portable version takes an afternoon: normalize your agent's grants into one file, diff it in every pull request, and make widening the condition that blocks the merge. Kits exist today for Claude Code, Codex, Copilot, Antigravity, Open Code, and Hermes, and Docker frames Cloud Sandboxes around agents running "five, ten, or 21 hours" unattended — which tells you the workload class this was built for, and how long a stale grant has to do damage.