Create Kit V3

Create a v3 kit

A kit is one OCI image. Its layers are the content and its manifest annotation carries the descriptor: what the kit offers, what it needs from the host as typed capability requests, and what it needs from other kits. An engine that does not read the annotation runs it as an ordinary image.

To migrate an existing v2 spec.yaml kit rather than write a new one, use the migrate-kit-to-v3 skill instead; its FIELD-MAPPING.md is also the best field-by-field reference if you are unsure what a given declaration means.

Decide the kind first

Everything else follows from this.

Write a workload when you own the environment the agent runs in. Write a mixin when you add a tool, a credential or a policy to somebody else's. Most new kits should be mixins, and a tool worth shipping as a workload is usually worth shipping as both — that is what the claude/claude-mixin pair in the examples is.

A mixin cannot set ENTRYPOINT, CMD, USER or WORKDIR and have it take effect: the workload anchors the composition and owns those contract fields. The additive fields do merge — env, labels, ports and volumes — so a mixin's ENV reaches the composed image, and PATH is appended rather than replaced.

Prefer ENV for static environment. It is what the agent process sees, and sbx@1 launches the agent under bash via BASH_ENV precisely because profile and rc files do not run for it — so an /etc/profile.d/<kit>-env.sh drop reaches a terminal the user opens and misses the agent itself. Reach for profile.d only when a value is likely to collide, because two mixins setting one variable to different values is a hard composition failure, or when the value genuinely only makes sense in an interactive shell.

Layout

The default authoring form is a companion pair, found by filename stem:

<kit>/
  <kit>.yaml           # the descriptor; first line `# syntax=docker/sandbox-kit:3`
  <kit>.dockerfile     # the content recipe (omit for a declaration-only mixin)
  <kit>-context.md     # agent-context body, referenced as contentFile:
  README.md

No dockerfile: field is needed — the stem convention finds it. Three other forms exist (an inline build: block, a # kit: comment descriptor inside a Dockerfile, and a kind: set list of other kits); see SPEC-v3 §3.

Descriptor skeleton

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: mixin
displayName: GitHub CLI
description: gh, installed from the official release tarball
sourceUrl: https://github.com/cli/cli
licenses: [MIT]

# One value drives the install, the provide, the published version and the tag.
version: "${{ kit.args.version }}"

args:
  version:
    default: "2.98.0"
    pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
    description: GitHub CLI release to install
    buildArg: GH_VERSION

provides: ["gh@${{ kit.args.version }}"]
# No requires: this overlay ships a release tarball and needs nothing from the
# workload. Add entries only for what the composed runtime must already have —
# see below, and note the comment under `requires` about refusing to compose.

capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow: [github.com, api.github.com]

  - type: com.docker.sandbox/agent-context@1
    config:
      contentFile: ./gh-context.md

Every key is lowerCamelCase with acronyms title-cased (sourceUrl, apiKey). Decoding is strict: an unrecognized key anywhere is an error, which is deliberate — a misspelled key silently ignored would be a policy silently absent.

Capabilities

Use an optional entry-level name for a short display label and description for its explanation. Names may contain spaces and need not be unique; they do not change identity, permissions, or merge keys. When entries merge, the first nonempty label in contribution order wins. This label is separate from config fields such as apiKey.name.

A capability is a typed request the host answers. optional: true means the kit degrades without it; the default is required, which fails resolution closed. Read the page for each type you emit — each is normative for its config and for what a runtime must do. The ones you will reach for, and the rule most often got wrong:

Host sharing is a separate grant from volume@1, including when the in-container path stays the same. Do not supply a host path or assume a Linux bind mount: runtimes may use VM filesystem sharing. Host-shared directories may have weaker filesystem semantics than private volumes. Concurrent writers coordinate access themselves. The initial mode does not reset existing directory permissions on later creates. Two host mounts at one path, or a host mount and a volume there, conflict.

Bundled skills

Use agent-skill@1 to package a skill as a mixin; see examples/review-skill. Ship the whole directory under a Kit-specific prefix such as /usr/share/example-skills/review, and declare that absolute source path. A source path must be literal after publishing; use a build-phase argument if it varies. Supporting scripts and references retain their relative paths. An optional config.name overrides the source basename at discovery destinations; it does not rename or rewrite the source.

Agent Kits declare agent-skills@1 at their discovery paths. The runtime links or otherwise exposes every selected agent-skill@1 bundle at each path, even when the host store is missing, empty, or disabled. The same declaration permits host sharing when available, bounded by mode and host policy; no second directory declaration is needed. Runtime assembly of these sources is implementation-specific. Different source paths claiming one effective name conflict at composition, and an existing destination entry makes a skill request unsatisfiable. Without any selected destination, a required skill request fails; optional requests are skipped and recorded. Registration does not execute scripts.

Versions, provides and requires

Pin the tool, and say so once. Declare a build-phase version arg, wire it through to the installer, and reference it from both provides and the top-level version: — publishing expands all of it, so one value drives the install, the matchable capability, org.opencontainers.image.version and the published tag.

A pinned provide is a claim about content, so make the build enforce it. Add a step that re-reads the installed version and fails on mismatch. Pinning the provide without pinning the install is worse than floating: it asserts a version the content may not have.

An unversioned provide is not a resting place. It resolves by falling through: an explicit @version wins, else a version-shaped consumption reference, else the descriptor's version: — and :latest is not version-shaped. So an unversioned provide under version: "1.0.0" publishes <tool>@1.0.0, the kit's release number wearing the tool's name, which a lower-bound constraint will not match. With no version: at all it does not publish: RequireVersionedProvides fails the build. Pin the version, or drop the provide — a kit with no provides publishes fine, and offering nothing matchable is honest when the kit cannot know what it installed.

requires is a closed-set check: a name nothing in the composition provides makes your kit refuse to compose anywhere, which is worse than saying nothing. It constrains the composed runtime set, not your builder — a mixin that only touches apt inside a build stage needs no deb/apt, and adding one there rejects every Alpine or distroless workload that could otherwise have run the shipped binary perfectly well.

Two things follow, and both cut against the instinct to list whatever a lifecycle hook shells out to:

Never require the platform floor. §12 lets kit content assume bash and sh, curl, git, a populated CA store, and the agent user at uid 1000. A hook running curl or git has declared nothing by doing so. Worse, requires: ["deb/curl"] refuses every workload without a dpkg database — an Alpine or Wolfi base publishes apk/ names — so the entry rules out bases that were always going to satisfy it.

A conditional dependency cannot be expressed here, so do not try. There is no either/or in requires: an entry is a hard precondition on every composition. A hook that reaches for apt-get only when the tool it installs is missing works fine on a base that already ships the tool, and requires: ["deb/apt"] converts "degrades on some bases" into "refuses on them". Let the hook probe and fail with an actionable message, and say in a comment that the silence is deliberate — otherwise the next reader adds the entry back.

The test is not "what do my hooks run" but "what must already be present, on every base, for this kit to work at all". Usually that is nothing.

Where a requirement is real, deb/ names are the right vocabulary and invented ones are wrong: publishing derives a deb/<pkg> provide from a workload's dpkg database, so requires: ["deb/apt"], ["deb/jq"] or ["deb/docker-ce"] resolve against any Debian-based workload. On a multi-platform workload the derived set is the intersection — §9.6 emits a package only where every published platform agrees on its normalized name and version — so check each arch, not just your own (docker run --rm --platform linux/arm64 <base> dpkg-query -W -f='${Version} ${Status}\n' <pkg>), and never author a deb/ provide — the frontend refuses it.