From ab3d7385461e6e20d25e075837e4c321ba676716 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 14 Oct 2026 12:25:56 +0200 Subject: [PATCH] docs: clarify the recommended v3 kit workflow (#26344) ## Description Built-in agent names select v2 kits, while published v3 workloads such as `sbx/claude` collide with those names. This change recommends v3, maps built-in agents to published v3 workloads with distinct names, and shows compatible CLI, kit set, and environment-file examples. The environment-file guide starts with a built-in v2 agent and links to a separate v3 workflow. Compatibility, capability requirements, and migration steps each live on the page where readers need them. Scoped Markdown and Vale checks pass. OCI manifests verify the v2 Playwright mixin and the published v3 references; v0.48.0 agent-registration and environment kit-resolution tests pass. A full sandbox launch was unavailable because Docker sign-in is required in this workspace. @netlify /ai/sandboxes/customize/use-kits/ Generated by Codex --- .../configuration/environment-files.md | 40 ++++++++++++-- .../manuals/ai/sandboxes/customize/_index.md | 37 ++++++------- .../manuals/ai/sandboxes/customize/kits-v2.md | 23 ++++---- .../ai/sandboxes/customize/use-kits.md | 53 +++++++++++++++---- 4 files changed, 106 insertions(+), 47 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index ffa370d8b0..6f216f6929 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -64,6 +64,10 @@ ports: host: 3000 ``` +> [!NOTE] +> This example uses kits v2, the format used by built-in agents. For v3, see +> [Add v3 kits](#add-v3-kits). + From `web-app-env`, run the environment: ```console @@ -286,6 +290,36 @@ second time. The following examples combine environment file fields into configurations you can adapt for a project. +### Add v3 kits + +To add v3 mixins, include a v3 workload in `kits` and set `agent` to the +workload's name. + +For example, save this as `web-app-env/v3.sbxenv.yaml` to use a v3 Claude Code +workload with the v3 Playwright mixin: + +```yaml +schemaVersion: "1" +name: web-app-v3 +agent: sbx-kit-claude +workspace: ./web-app + +kits: + - docker.io/docker/sbx-kit-claude:2.1.267 + - docker.io/sbx/playwright:1.61.1 +``` + +From `web-app-env`, run: + +```console +$ sbx env run v3.sbxenv.yaml +``` + +The `agent` value, `sbx-kit-claude`, matches the last component of the +workload's repository name. The `web-app-v3` name creates a separate sandbox. +For other agents, see the +[published v3 workloads](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads). + ### Combine team defaults and personal settings Keep the shared configuration in a version-controlled environment directory @@ -605,10 +639,8 @@ true`. `kits` accepts local directories, ZIP archives, OCI registry references, and Git URLs prefixed with `git+https://` or `git+ssh://`. Kits can install tools, configure the sandbox, and give the agent project-specific instructions. -The examples on this page pair built-in agents with v2 mixins. See -[Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md) for that format, or -[Version compatibility](/manuals/ai/sandboxes/customize/_index.md#version-compatibility) -when selecting v3 kits. +Built-in agents use v2 mixins. For v3 workloads and mixins, see +[Add v3 kits](#add-v3-kits). An environment file selects kits and configures a sandbox's host resources. A kit descriptor defines the package itself. The environment file's diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index 042d0aa52d..20c6527dbe 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -19,9 +19,8 @@ A kit can define the whole environment or add something to an existing one, such as a toolchain or your team's shared configuration. Package those choices once, then reuse them across projects and share them with your team. -This page covers v3 kits, which require `sbx` v0.45 or later. See -[Version compatibility](#version-compatibility) for compatibility with earlier -kit formats. +Docker recommends v3 kits. This section covers v3. For the supported v2 +format, see [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md). ## What is a kit? @@ -31,9 +30,9 @@ credentials, setup commands, or instructions for the agent. You publish the kit as a container image containing its files and descriptor. You identify a published kit by its container image reference, such as -`me/my-kit:latest`. When you use the kit, `sbx` prepares its files and applies -its settings. You can use one kit for a complete environment or combine kits -that contribute different parts. +`docker.io/docker/sbx-kit-claude:2.1.267`. When you use the kit, `sbx` +prepares its files and applies its settings. You can use one kit for a +complete environment or combine kits that contribute different parts. ## What kits can do @@ -63,11 +62,11 @@ and launch command, and mixins add tools or behavior to it. For example, this command runs a workload with a mixin: ```console -$ sbx run me/my-agent-kit:latest --kit me/my-mixin:latest +$ sbx run docker.io/docker/sbx-kit-claude:2.1.267 --kit docker.io/sbx/playwright:1.61.1 ``` -The workload supplies the environment and launch command. The mixin adds its -tools and configuration to that environment. +The Claude Code workload starts the agent, and the Playwright mixin adds +browser-testing tools. ## Kit sets @@ -96,18 +95,17 @@ and add mixins. To customize and publish your own combination, see ## Version compatibility -V3 kits cannot be combined with v1 or v2 kits in the same sandbox. To use -v3, select a v3 workload and use v3 for every mixin you add. +V3 requires `sbx` v0.45 or later. Every kit in a v3 sandbox must use v3: +select a v3 workload and add only v3 mixins. -The built-in agent names, such as `claude` and `codex`, select v2 kits. -You can't add a v3 mixin to these built-ins. For example, -`sbx run claude --kit ./some-v3-mixin` fails because it mixes kit versions. -Instead, select a v3 workload by its published image, local path, or Git -reference, as shown in [Run a kit](/manuals/ai/sandboxes/customize/use-kits.md#run-a-kit). +Built-in agent names such as `claude` and `codex` select v2 kits, so +`sbx run claude --kit ./some-v3-mixin` fails. To use that mixin, choose a +[v3 workload](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads) +by its image, local path, or Git reference. -V2 remains supported, including the built-in agents and -existing v2 customizations. See [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md) for maintenance -and migration guidance. +A kit's capabilities can require a later release or a local sandbox. See +[Kit capability support](/manuals/ai/sandboxes/customize/author/capabilities.md) +for details. V2 remains supported and is not deprecated. ## Choose your next step @@ -118,6 +116,5 @@ and migration guidance. - Explore the [sandbox-kit-spec repository](https://github.com/docker/sandbox-kit-spec) for the authoritative v3 specification, build frontend, and examples. -For the earlier format used by built-in agents, see [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md). To save an environment you've configured inside a sandbox, see [Save a sandbox as a template](/manuals/ai/sandboxes/usage.md#saving-a-sandbox-as-a-template). diff --git a/content/manuals/ai/sandboxes/customize/kits-v2.md b/content/manuals/ai/sandboxes/customize/kits-v2.md index 7664687874..59c45f0a50 100644 --- a/content/manuals/ai/sandboxes/customize/kits-v2.md +++ b/content/manuals/ai/sandboxes/customize/kits-v2.md @@ -11,13 +11,10 @@ aliases: {{< summary-bar feature_name="Docker Sandboxes sbx" >}} -V2 kits remain supported. This page covers v2 usage, configuration, and the -specification. For new kit development with the `sbx` CLI, use -[v3 kits](/manuals/ai/sandboxes/customize/_index.md). - -Built-in shortcuts such as `claude` and `codex` select v2 kits and still work -with v2 mixins. V3 workloads and mixins can't be combined with v1 or v2 kits. -V1 also remains supported. +V2 kits remain supported and are not deprecated. Built-in agent names such +as `claude` and `codex` select v2 kits and work with v2 mixins. This page +covers their usage and specification. For new kits, Docker recommends +[v3](/manuals/ai/sandboxes/customize/_index.md). V1 also remains supported. ## Use existing kits @@ -805,9 +802,13 @@ controlled by the user through ## Move an environment to v3 -Select a v3 workload, convert or replace its mixins, and create a separate -sandbox with a different `--name`. Use the explicit workload reference in -place of the built-in shortcut. Every selected kit must use v3. +Select a [v3 workload](/manuals/ai/sandboxes/customize/use-kits.md#published-v3-workloads), +convert or replace its mixins, and create a separate sandbox. Every selected +kit must use v3. Running an existing sandbox keeps its recorded kit configuration. + +For an environment file, see [Add v3 kits](/manuals/ai/sandboxes/configuration/environment-files.md#add-v3-kits). +Keep its `schemaVersion: "1"`: the environment file version is independent of +kit descriptor versions. Changing `schemaVersion` alone doesn't convert a kit. Separate reusable image content from sandbox initialization, and declare runtime capabilities: @@ -831,5 +832,3 @@ when converting runtime setup and capability declarations. Use a [kit set](/manuals/ai/sandboxes/customize/author/kit-sets.md) to combine published v3 components with your settings. To rebuild the agent environment from a base image, follow [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md). -Running an existing sandbox keeps its recorded configuration. It doesn't -migrate the kit composition. diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md index 5503a57f96..e045c27ef6 100644 --- a/content/manuals/ai/sandboxes/customize/use-kits.md +++ b/content/manuals/ai/sandboxes/customize/use-kits.md @@ -13,8 +13,8 @@ settings. You run kits you build yourself or get from another publisher in the same way: give `sbx` a reference, and Docker Sandboxes prepares the environment and applies the kit's settings. -This page shows how to run published kits, combine them with mixins, and -customize their settings. +Docker recommends v3 kits. V2 remains supported and is the default format +for built-in agent references such as `claude` and `codex`. ## Run a kit @@ -26,8 +26,45 @@ published v3 Codex workload: $ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit ``` -This starts Codex using a v3 kit from Docker Hub. The built-in `codex` -shortcut uses a v2 kit to preserve compatibility with existing customizations. +### Published v3 workloads + +Use these published v3 workloads in place of built-in shortcuts when adding +v3 mixins with `sbx run` or `sbx create`. + +A workload's agent name comes from the last component of its repository name. +It must differ from built-in agent names: `docker/sbx-kit-claude` registers +`sbx-kit-claude`, while `sbx/claude` conflicts with built-in `claude` and +fails to register. Changing the sandbox's `--name` doesn't change the agent name. + +| Built-in agent | V3 workload OCI reference | +| --- | --- | +| `claude` | `docker.io/docker/sbx-kit-claude:2.1.267` | +| `codex` | `docker.io/docker/sbx-kit-codex:0.155.1` | +| `copilot` | `docker.io/docker/sbx-kit-copilot:1.0.86` | +| `cursor` | `docker.io/docker/sbx-kit-cursor:2026.09.18-9a7762b` | +| `devin` | `docker.io/docker/sbx-kit-devin:3000.10.31` | +| `docker-agent` | `docker.io/docker/sbx-kit-docker-agent:1.141.0` | +| `droid` | `docker.io/docker/sbx-kit-droid:0.223.0` | +| `kiro` | `docker.io/docker/sbx-kit-kiro:1.0.0` | +| `opencode` | `docker.io/docker/sbx-kit-opencode:1.18.31` | +| `shell` | `docker.io/docker/sbx-kit-shell:1.0.0` | + +For a [sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md), +list the workload reference under `kits` and set `agent` to its repository +name, such as `sbx-kit-claude`. + +Published `sbx/*` mixins, such as `sbx/playwright` and `sbx/codex-mixin`, can +be combined with these workloads. Their sources are on the +[v3 branch of docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/v3). +For more source examples, see +[sandbox-kit-spec](https://github.com/docker/sandbox-kit-spec/tree/main/examples). + +Use a version tag to select a kit release, or a digest to identify exact +content. A `latest` tag can move to a kit that needs a later `sbx` release. +V3 format support starts at v0.45, but a kit's capabilities can require a +later version or a local sandbox. Check +[Kit capability support](/manuals/ai/sandboxes/customize/author/capabilities.md) +and the publisher's requirements before choosing a kit. ### Choose a kit source @@ -100,8 +137,7 @@ instructions intact. ## Add mixins Mixins add tools and configuration to a workload. Use `--kit` to add a mixin -when creating a sandbox. For v3 kits, both the workload and the mixin must -use v3. +when creating a sandbox. For example, an internal CLI mixin can package your company's executable along with network rules and a credential request for its API: @@ -120,11 +156,6 @@ when prompted. Codex starts with `company-cli` available to use. Docker Sandboxes applies the files and settings from both the workload and the mixin. -Built-in shortcuts such as `claude` and `codex` use v2 kits and require -[v2 mixins](/manuals/ai/sandboxes/customize/kits-v2.md). -See [Version compatibility](/manuals/ai/sandboxes/customize/_index.md#version-compatibility) -for details. - ### Combine multiple mixins Repeat `--kit` to add more mixins. You can also add compatible mixins to a