nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify the recommended v3 kit workflow (#26344)

Browse Source 
## 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
This commit is contained in:
David Karlsson authored and GitHub committed 2026-10-14 12:25:56 +02:00
1 parent 9643ba0813
commit ab3d738546
4 files changed
+106 -47
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/manuals/ai/sandboxes/configuration/environment-files.md
+36 -4
View File
@@ -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
content/manuals/ai/sandboxes/customize/_index.md
+17 -20
View File
@@ -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).
content/manuals/ai/sandboxes/customize/kits-v2.md
+11 -12
View File
@@ -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.
content/manuals/ai/sandboxes/customize/use-kits.md
+42 -11
View File
@@ -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