v3.0.0-m.8

Highlights

• Host-shared storage. New com.docker.sandbox/host-mount@1 lets Kits request runtime-owned host directories shared across their sandboxes and retained after sandbox removal. Kits choose the container path and optional initial mode; runtimes choose the backing directory and mount mechanism. Sharing has its own permission surface, identity isolation, conflict validation, and conformance checks. An optional shared-cache example demonstrates the capability. (#101)

• Agent instruction discovery. agent-context@1 gains an optional absolute directory, allowing workloads, agent mixins, and sets to select locations their harnesses discover. Explicit mixin profiles override legacy workload defaults, conflicting profiles fail, and existing instructions outside runtime-managed sections are preserved. Updated examples cover Codex, Claude Code, Gemini CLI, OpenCode, Docker Agent, and Cursor. Codex ACP launches receive CODEX_HOME, and the repository environment stores Codex sessions separately for each sandbox. (#97)

• Capability selection decisions. Policy callbacks receive cancellation context and the owning Kit descriptor and return CapabilityDecision{Accepted, Message}. Selection records retain decision messages, required-rejection diagnostics explain refusals, and cancellation discards partial results. (#98)

• Reproducible OCI creation metadata. kit-tck validate accepts RFC 3339 org.opencontainers.image.created annotations derived from SOURCE_DATE_EPOCH, including conforming fractional seconds, offsets, lowercase separators, and leap seconds. Wall-clock creation timestamps remain prohibited by the specification. (#100)

Artifacts

• kit-tck binaries for Linux, macOS, and Windows on amd64 and arm64, with checksums.txt, attached to this release.
• Hub image: docker/sandbox-kit:3.0.0-m.8.
• Go module: go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.8.

Notes

• Breaking Go API change. Capability selectors now use func(context.Context, spec.Descriptor, spec.Capability) spec.CapabilityDecision instead of returning a boolean. SelectCapabilities takes context first; selectors returned by Supported use the same new callback signature. Descriptor and capability arguments are passed by value, with nested maps and slices shared.

• Agent-context compatibility. Existing descriptors retain their previous discovery default. The new directory field extends agent-context@1 in place under the approved draft-versioning exception; older strict readers reject declarations using it. The external Docker Sandboxes runtime handler needs corresponding support before consuming the updated examples.

• Host-mount runtime support. Adding this capability requires no existing capability-version or schemaVersion bump. Required requests fail on runtimes without host sharing; optional requests can be skipped. The repository's sbx adapter does not yet advertise this capability. Its conformance checks were exercised against the fake adapter, not a live Docker Sandboxes runtime.

• Conformance limits. Artifact validation checks creation-timestamp syntax but cannot determine whether its source was SOURCE_DATE_EPOCH or the wall clock. Cross-Kit reattachment of retained private volumes also remains explicitly waived because the adapter cannot express that operation.

• Milestone frontend tag. This prerelease publishes the exact version tag and leaves floating docker/sandbox-kit:3 unchanged.

Full changelog: v3.0.0-m.7...v3.0.0-m.8.

v3.0.0-m.7

Highlights

• Dependency security fixes. Upgrade containerd to v2.3.6 for CVE-2026-53493 and replace the repository's transitive eBPF requirement with v0.22.0 for CVE-2026-10722. The dev-tools mixin now permits HTTPS access to vuln.go.dev and api.osv.dev for dependency scanners.

• Atomic capability groups and environment references. Kits can group requests into required or optional features: rejecting an optional member omits the whole feature, including its hooks, files, and context. Capability entries gain human-readable names and source attribution. ${{ kit.env.NAME }} references expand from the final container environment during assembly.

• SSH agents, Git identity, and long-running workloads. New capabilities request phase-scoped SSH agent access with authentication/signing bounds, runtime-provided Git name and email defaults, and sandboxes that remain running after clients disconnect. The Docker Sandboxes TCK adapter claims SSH-agent and Git-identity support and retains selection decisions.

• Bundled agent skills and unified discovery. Mixins can ship skills through agent-skill@1, with an optional discovery-name override. agent-skills@1 exposes bundled skills and available host-shared skills at an agent's discovery directory; missing or disabled host sharing no longer prevents startup. Credentials can use one configuration for both install and runtime phases.

• Runtime assembly APIs. fetch.Assemble loads, resolves, and assembles Kits in one call, with configurable loaders, capability selection, container overrides, progress, and layer validation. Resolution exposes per-Kit environment exports and published descriptors. Custom loaders can supply built images for local paths or Git URLs while preserving those references as Kit identities.

• Validation and conformance. Validation reports multiple errors with field paths, locations, and source excerpts. Layer judging verifies compressed and uncompressed digests, bounds inventory, and checks collisions across resolved filesystems. Overlay checks better match containerd extraction and avoid stalls on crafted layers. Runtime coverage adds groups, environment precedence, bundled skills, credential phases, SSH agents, and Git identity.

• Examples and development tooling. Add dev-tools, Git-over-SSH, Git signing, optional-cache, and bundled-skill examples. Refresh agent and ACP versions, including Codex 0.159.2, Codex ACP 2.0.1, and Gemini CLI 0.62.0. Codex Kits ship the complete CLI package, accept model/reasoning arguments, register the MCP gateway correctly, and preserve active and archived transcripts across repository sandbox recreation.

Artifacts

• kit-tck binaries for Linux, macOS, and Windows on amd64 and arm64, with checksums.txt, attached to this release.
• Hub image: docker/sandbox-kit:3.0.0-m.7 (does not move floating :3).
• Go module: go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.7.

Notes

• eBPF version for Go module consumers. The eBPF fix uses a replace directive for repository builds. Go module consumers do not inherit dependency replacements; consumers whose selected module graph includes github.com/cilium/ebpf v0.16.0 need to upgrade it to v0.22.0 or add the same replacement to their own main module.

• This milestone includes breaking Go API changes. fetch.Client.Assemble and AssemblePartial are replaced by Resolve and ResolvePartial, returning fetch.Resolved. Argument exports are available as Resolved.ContainerEnv and each resolve.Unit.Env, and should be applied at container creation. The new package-level fetch.Assemble returns an image, resolved declarations, and container settings.

• Typed image assembly. assemble.Merge returns *assemble.Image instead of *assemble.Merged. Merged.ConfigJSON and its stored manifest are removed; use Image.Config, Image.Manifest(), and Image.WriteMetadata().

• Layer validation is opt-in. LoadedKit.OpenLayer becomes LayerLoader. Set fetch.Options.LayerValidator to fetch.DefaultLayerValidator to retain built-in integrity, safe-extraction, resource-limit, and collision checks. A nil validator skips layer reads; callers remain responsible for those checks before using the image.

• Selection source fields. KitSelection.Original and Raw become PublishedDescriptor and PublishedBytes, retaining the unexpanded published declarations and exact source bytes. Use Resolved.Kits for expanded, selected declarations.

• Credential phase lists. Credential.Phase changes from string to spec.Phases ([]string). Scalar descriptor spelling remains valid; phase: [install, runtime] requires an updated reader. This intentionally extends credential@1 in place under the approved versioning exception.

• Agent-skills semantics change. agent-skills@1 now declares bundled-skill discovery with optional host sharing, while mode bounds host-store access only. Runtimes implementing the previous contract need updating. Users of development builds must replace the removed agent-skills-directory@1 capability and AgentSkillsDirectoriesOf reader with agent-skills@1 and AgentSkillsOf. The existing @1 version is retained under the approved versioning exception.

• Descriptor compatibility. No existing descriptor field is renamed or removed. New capability name, group, and source forms require updated strict readers. schemaVersion remains 3 under the approved exception for the unfinished draft; this prerelease does not promote the floating frontend tag.

Full changelog: v3.0.0-m.6...v3.0.0-m.7.

v3.0.0-m.6

Highlights

• fetch assembles a kit from registry references. Consumers can resolve published kits (and indexes) without a source tree: platform ranking, nested-index walks, create-phase env exports, and a hard refusal of indexes that set artifactType. Import as github.com/docker/sandbox-kit-spec/v3/fetch.

• kit-tck inspect, and kit is now validate. Inspect reads a kit without judging it (descriptor and staged recipe); validate is the conformance verb. Descriptor-only inspect skips layer reads. Overlay judging models the applier for home owners and dangling links, and skips overlay checks where the source cannot walk them.

• Build stamps. Both binaries and every kit the frontend publishes carry the tag and commit (internal/version); kit-tck version, the report header, frontend progress, and vnd.docker.sandbox.kit.built-by all agree.

• Companion sub-solve fidelity. Caller build options forward into dockerfile.v0 the way BuildKit expects: reserved control and gateway attributes stay out of the way, FROM args and stage aliases match dockerfile.v0, --target and platform targeting work, mixin external bases load through named-context lookup, and --no-cache never leaks into the lower stage.

• Schema accepts ${{ kit.args.* }} in capability configs. Remaining constrained fields that authors already parameterized at the top level can use the same kit-arg refs in config.

• Builder kit exposes BuildKit to host buildx. Opt-in TCP publish (buildkitExpose), kit-arg port/size, default engine-store volume 20 GiB.

• Authoring skills ship as a kit, with create/migrate guidance aligned to stable sbx (Kits v3 in local and cloud). README get-started leads with published docker/* v3 images (sbx/* remains v2).

• Examples. Expanded agent kits (including Codex ACP set / Claude ACP wrapper fixes), Alpine workload example, and shared skills store wiring for Claude.

Artifacts

• kit-tck binaries (linux/darwin/windows, amd64/arm64) attached to this release
• Hub image: docker/sandbox-kit:3.0.0-m.6 (does not move floating :3)

Notes

• CLI rename: kit-tck kit → kit-tck validate. Update scripts and docs that still call kit.
• go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.6

v3.0.0-m.5

Highlights

• com.docker.sandbox/sbx@1 names what an agent sandbox needs and makes both halves checkable. A workload declaring it says the host launches the agent rather than letting the image entrypoint be PID 1, and that the host honors the identity the image config states instead of assuming one. Config-less and singleton, with no permission surface — it asks the host to run the workload a particular way and to read what the image already declares.

  The kit owes a /bin/sh and a /bin/bash the declared user can actually execute, a non-empty user in the image config, and that user resolving in /etc/passwd to a uid, gid and home. Occupying the path is not enough: a FIFO, a device node, or bits that leave the declared user out resolve at publish and then fail at the first hook. The host owes the four duties on the other side, which the runtime suite judges. Two new kit checks, sbx-platform-floor and sbx-persistent-env, judge the kit's half from the artifact alone — so a kit that cannot be operated this way is caught at publish rather than at first launch.

• A workload's provides now says what its image actually carries. Publishing reads the package databases out of the content and states one entry per installed package under the reserved deb/ and apk/ namespaces (§9.6). This replaces a fiction: a version: fallback answers for names an author chose, and applying it to inherited software published bash@1.0.0 — a kit's release number wearing the name of a shell.

  deb/bash@5.2.37     deb/apt@3.0.3        deb/binutils@2.44
  deb/openssl@3.5.7   deb/jq@1.8.2         deb/zlib1g@1.3       ... one per package
  

  The version published is the upstream core and never the distribution's wrapping, so an epoch, a Debian revision, a binNMU, a backport suffix and an apk release all come off. Fewer than three parts stays as it is rather than being padded — binutils really is 2.44. A prerelease is dropped rather than promoted, because dpkg sorts 1.69~deb13u1 below 1.69 and stating 1.69 would claim a release the content has not reached. Entries are stated only where every platform agrees, so an architecture-specific package is dropped rather than asserted for all of them. Derivation is workload-only: a mixin's layers are a delta, and a set carries its kits' entries through the union rather than re-deriving. A new derived-provides check holds every published entry back to the database that shipped beside it.

• An adapter that drives Docker Sandboxes through the conformance contract, at tck/adapters/sbx (task tck:runtime:sbx). Running a real runtime against the suite is also what found the defects the rest of this release fixes — in the suite and the pages as often as in the runtime, which is the point of writing one.

• kit-tck kit me/sbx-kit:1.0.0 works. References are normalized the way docker pull normalizes them, so Hub shorthand reaches Hub instead of failing on a DNS lookup for a host that was never one. A reference pinned by both a tag and a digest resolves the digest.

• The sbx@1 floor reports every gap, not the first. An image with no declared user used to report that and stop, leaving its missing shells to be discovered one rebuild at a time.

• Claude Code 2.1.274 and claude-agent-acp 0.79.0 in the claude kits, and task kit:build resolves a version override from every argument source rather than only the first.

Artifacts

• kit-tck binaries (linux/darwin/windows, amd64/arm64) attached to this release
• Hub image: docker/sandbox-kit:3.0.0-m.5 (does not move floating :3)

Notes

• Normative statements moved this time. sbx@1 is a new capability page with nine anchored statements, §9.6 is new, and §5.1 gained a MUST: a namespace anyone defines is reverse-DNS, and the single-label space is reserved — deb/ and apk/ live there. The capability-name charset now admits dots and pluses, because a package name is a capability name and Debian ships libstdc++6 and containerd.io.
• The kit suite went from 12 checks to 15. As RELEASES.md says, a suite that gains a check can fail an artifact that passed the previous tag, and that is intended: the check reflects a duty the specification already stated. A workload declaring sbx@1 is the one most likely to notice.
• Rebuilding a workload kit changes its published descriptor, which now carries its package inventory. Nothing is required of authors, but a kit that listed tool names with no versions of their own should drop them — examples/shell/shell.yaml shows the shape.
• go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.5
• First release tag carrying a signature; m.1 through m.4 are annotated but unsigned.

v3.0.0-m.4

Highlights

• kit-tck reports what a run judged, not only what it found. Findings are grouped by severity under a tally that accounts for every check, and each names the statement it judged with a link into the specification — SPEC-v3 §9.3 and lifecycle@1/install-once resolve to the section and the anchored statement that state them. The pages are embedded and resolved through the same anchors the coverage guard holds the suites to, so a renamed section fails a test rather than shipping a dead link.

  kit-tck dev · kit · /tmp/motd-broken broken
  
    failed
      ✗ schema-version-annotation vnd.docker.sandbox.kit.schema-version is "2", descriptor says "3"
                                  [SPEC-v3 §9.3]
      ✗ oci-annotations           org.opencontainers.image.created must not be emitted [SPEC-v3 §9.3]
    12 checks · 3 failed · 9 passed
  
  ✗ does not conform
  

  New flags: --verbose lists the checks that passed, --format json is the run as data with each finding carrying its spec URL, and --color auto|always|never settles what the terminal and NO_COLOR otherwise decide. Identical per-platform reports collapse to the platforms that share them. Fixes: a flag after the reference (kit-tck kit <ref> -v) was ignored, a bad flag printed two usage blocks, and the verdict went to stderr while its findings went to stdout.

• task kit:build and task kit:push resolve their tag from the kit itself, refreshing an upstream-tracked descriptor from the vendor's latest release first, so a published tag cannot name a version the kit did not install. TAG still pins a build, a --build-arg version= override outranks the descriptor and the tag follows it, and an unreachable upstream falls back to what the descriptor records. The upstream map that versions:check carried inline now lives in hack/kit-version.sh, with task versions:update as the same refresh without a build.

• Claude Code 2.1.273 and claude-agent-acp 0.78.0 land in the claude kits, and the set names them by the versions they now publish as.

• The README no longer opens by asking for a local docker build of the frontend: docker/sandbox-kit:3 is on Docker Hub, so BuildKit pulls it when it reads the # syntax= line.

Artifacts

• kit-tck binaries (linux/darwin/windows, amd64/arm64) attached to this release
• Hub image: docker/sandbox-kit:3.0.0-m.4 (does not move floating :3)

Notes

• No normative statement moved. The conformance checks, their ids, and their verdicts are unchanged — this release changes how a run is written down, not what it judges.
• go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.4

v3.0.0-m.3

Highlights

• Adopt Go module path github.com/docker/sandbox-kit-spec/v3 so v3.* tags are importable:

  go get github.com/docker/sandbox-kit-spec/v3@v3.0.0-m.3
  

  Import packages as github.com/docker/sandbox-kit-spec/v3/spec (and siblings).

• Document that schema-3 frontend releases and the Go module major share the v3.* tag axis.

Artifacts

• kit-tck binaries (linux/darwin/windows, amd64/arm64) attached to this release
• Hub image: docker/sandbox-kit:3.0.0-m.3 (does not move floating :3)

Breaking for Go consumers

• Requires updating require / imports from github.com/docker/sandbox-kit-spec/... to github.com/docker/sandbox-kit-spec/v3/....

v3.0.0-m.2

Highlights

• Fix the release workflow so task lint can run: install the pinned golangci-lint binary (same as CI) and run markdownlint via Task. Unblocks tagged releases after v3.0.0-m.1 failed at lint with exit 127.

Artifacts

• kit-tck binaries (linux/darwin/windows, amd64/arm64) attached to this release
• Hub image: docker/sandbox-kit:3.0.0-m.2 (does not move floating :3)

Notes

• Go module path is still github.com/docker/sandbox-kit-spec (no /v3) on this tag. Prefer v3.0.0-m.3 or later for module consumers.