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