Migrate Kit To V3

Migrate a kit to v3

A v2 kit is one spec.yaml plus a Dockerfile that builds a named image. A v3 kit is one OCI image: the descriptor declares what the kit needs as typed capabilities and rides in a manifest annotation, the image config carries the runtime contract (entrypoint, env, user, workdir), and the layers carry the content.

Tooling

Three published tools, nothing repo-local:

• docker buildx builds kits. Nothing to install for the kit frontend — BuildKit pulls docker/sandbox-kit:3 from the descriptor's # syntax= line.

• sbx runs them. Install the stable CLI from Docker Docs / sbx-releases; current releases support Kits v3 in local and cloud mode.

• kit-tck judges conformance: go install github.com/docker/sandbox-kit-spec/v3/cmd/kit-tck@latest, or take an archive from the releases page. (A go install of an untagged ref reports dev; @v3.x.y and the release archives both carry the real version, which internal/version reads from the build info.)

  This repository is private, so both routes need access to it. The public module proxy cannot serve it — proxy.golang.org answers 404 — so go install resolves direct and needs a git credential plus GOPRIVATE=github.com/docker/*. In CI that means a token with read access, and a fork's token does not have one: a fork can still validate a descriptor by building it, since the frontend validates during the build, but it cannot run kit-tck. If the repository becomes public, that whole constraint disappears.

Authorities

In precedence order:

1. spec/ — the Go implementation. Where docs and code disagree, code wins.
2. SPEC-v3.md — the grammar (§3 authoring forms, §4 top-level fields, §5 provides/requires, §6 args, §7 capabilities, §8 launch modes).
3. capability pages — one per capability type, normative for its config schema and runtime behavior.
4. examples — worked kits. claude and claude-mixin are the migration of a real v2 kit into both shapes; read them first.

Working inside the spec repo, all four are also on disk at spec/, docs/spec/ and examples/.

Workflow

Track progress with this checklist:

- [ ] 1. Read the v2 kit end to end, including its README and testdata
- [ ] 2. Write the v3 descriptor, recipe, and context file
- [ ] 3. Add the -mixin variant (workload kits only)
- [ ] 4. Validate the descriptor (fails in seconds on a bad field)
- [ ] 5. Build the kit
- [ ] 6. Run it with sbx and exercise the agent
- [ ] 7. Verify with kit-tck
- [ ] 8. Publish, and delete the CI that published the v2 pair

1. Read the v2 kit first

Read spec.yaml, Dockerfile, README.md and testdata/tck.yaml before writing anything. v2 kits carry their reasoning in comments, and that prose is the most valuable thing to carry across. testdata/tck.yaml is the only record of whether a working non-interactive invocation was ever established (promptArgs), which decides whether the migrated kit declares agent-sessions@1. It says nothing about interactive verbs: declare agent-interactive-sessions@1 beside it only for verbs you have verified against the tool's real CLI, never from a pattern.

2. Write the v3 files

For a kit named <kit>, migrating in place:

The complete field-by-field mapping, the capability rules, and the gotcha list are in FIELD-MAPPING.md. Read it before writing the descriptor.

Migrate faithfully: preserve every declared host, credential, hook, volume, port, env var and instruction, and keep base images verbatim. Where v3 cannot express something, or where a v2 declaration turns out to be dead config, mark it with an inline # MIGRATION NOTE: comment rather than dropping it silently — the claude example shows the convention.

Faithful does not mean literal in one respect: a v2 install hook is often a v2 limitation rather than a v3 requirement, because a v2 mixin had no way to ship content. Decide per hook whether it becomes a layer — the rule, and the five cases where a hook is still correct, are in FIELD-MAPPING.md.

3. Add the -mixin variant

Every workload kit gets a sibling <kit>-mixin/ holding <kit>-mixin.yaml, <kit>-mixin.dockerfile and a context file. Name that last one <kit>-context.md, which is what six of the seven example mixins do — the staged name only has to avoid kit.yaml and kit.dockerfile, so the -mixin- infix buys nothing and the repository is already near-unanimous. The mixin declares the same credentials, network policy, volumes and hooks, minus what only the kit that owns the environment can carry. See the mixin variants section for the exact subtractions and the overlay recipe patterns.

4. Validate the descriptor

The frontend decodes and validates the descriptor before it builds any content, so an export-less build is the fast loop while the descriptor is wrong:

cd <kit> && docker buildx build . -f <kit>.yaml --output type=cacheonly

A malformed descriptor fails in about a second, naming the offending field and its line. Be clear about what cacheonly does, though: it suppresses the export, not the build. Once the descriptor is valid the frontend goes on to solve the whole recipe — downloads, installs and all — so this is fail-fast for bad input rather than a validation-only step. Iterate here until it is clean: a malformed descriptor still costs only the second it takes to reject, even though a valid one costs the whole recipe.

Pass build-phase args by the kit's arg name, not the buildArg name the recipe sees, and supply anything declared required or validation fails:

docker buildx build . -f <kit>.yaml --build-arg version=2.99.0 --output type=cacheonly

Because the recipe is solved too, a bad FROM or COPY --from surfaces here rather than waiting for step 5 — you just do not get an image out of it.

5. Build the kit

Swap the export for --load to put an ordinary tagged image in the local store:

docker buildx build . -f <kit>.yaml -t <kit>-kit:<tag> --load

--load is not optional on the docker-container driver, which is what buildx create gives you: without an output the result stays in the builder's cache and docker run <kit>-kit:<tag> reports no such image.

To judge the artifact with kit-tck without a registry, export an OCI layout directory instead:

docker buildx build . -f <kit>.yaml -t <kit>-kit:<tag> \
  --output type=oci,dest=/tmp/<kit>-layout,tar=false

A workload's recipe must build on a base carrying the platform floor — bash, the agent user (uid 1000), git, a CA store — which the hardened dhi.io/sbx-templates:* images carry. A bare distro base builds fine and fails at agent launch.

6. Run it with sbx

Point sbx at the kit directory — the runtime builds source-form kits on demand, keyed by source hash, so this needs no registry and no push:

sbx run ./<kit> .                            # a workload kit
sbx run ./<workload> --kit ./<kit>-mixin .   # a mixin, composed onto a workload

A mixin cannot run alone; compose it onto the migrated workload or onto a shell workload. Pass kit args with --kit-arg name=value (or --kit-arg kit.name=value to target one kit), and bind a credential the kit declares with sbx secret set <service> before expecting authenticated calls to work. (The -g flag older docs show is deprecated; global is the default now.)

Inside the sandbox, the kit is self-describing — use it to check that what you declared is what arrived:

cat /usr/share/sandbox/kit/<kit>/kit.yaml        # the published descriptor
cat /usr/share/sandbox/kit/<kit>/kit.dockerfile  # the recipe that built it
cat /var/log/sbx-kit-startup.log                 # startup hook output

Then exercise the kit for real: run the agent's own version command, confirm install hooks left what they should, confirm a declared volume is writable by agent, and confirm an undeclared host is refused while a declared one is not.

sbx kit inspect ./<kit> builds the source kit and prints its resolved declarations (kind, network counts, credentials, args) without starting a sandbox. Add --kit-arg to preview how args resolve. The first source build creates the shared builder sandbox and is slow; sbx kit builder status shows it and sbx kit builder rm reclaims the cache.

For the published path instead of the local loop, push the kit as an ordinary image and run it by reference — a kit image that only exists in the local Docker store cannot run, because the runtime resolves kit images from registries:

docker buildx build . -f <kit>.yaml --push -t docker.io/<you>/sbx-kit-<kit>:<tag> \
  --platform linux/amd64,linux/arm64 --provenance=true
sbx run docker.io/<you>/sbx-kit-<kit>:<tag> .

7. Verify with kit-tck

kit-tck judges an artifact's annotations, layers, staged sources and image config, with every check linked to the clause it enforces. The same checks run inside the frontend during a build, so running them here is how an artifact changed by an exporter or a registry on its way out gets judged — and how a kit this frontend did not build gets judged at all.

kit-tck validate --layout /tmp/<kit>-layout <tag>     # the OCI layout from step 5
kit-tck validate docker.io/<you>/sbx-kit-<kit>:<tag>  # a published kit

For the layout form, <tag> is the tag alone as the layout records it (1.0.0), not the full <kit>-kit:1.0.0 reference the build was tagged with.

Add --verbose to list the checks that passed, --format json for every check with its spec link, and --plain-http for a registry served over HTTP.

A published kit built on a multi-node builder warns that the index carries no kit annotations. That is expected, not a defect: a multi-node build merges per-node results into a fresh index client-side, which dissolves them, and §9.3 requires consumers to fall back to the platform manifest, which does carry them. The verdict is still ✓ conforms. A single-node build shows no warning.

Runtime conformance is a separate suite, for people implementing a runtime rather than authoring a kit: kit-tck runtime --adapter <path> drives hundreds of sandbox lifecycles against an adapter implementing conformance.md. It runs long — the bare command defaults --timeout to 30m and fails when that expires, so a real run needs something like --timeout 2h — and migrating a kit does not need it at all.