docker · dvdksn · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/content/guides/mistral-vibe-sandbox.md b/content/guides/mistral-vibe-sandbox.md
@@ -168,7 +168,7 @@ Each field does the following:
 | Field                       | Purpose                                                                                                        |
 | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `kind: sandbox`             | Declares a sandbox agent: a complete image plus its launch configuration.                                      |
-| `name`                      | The kit's identifier, reused in the `sbx run` command.                                                         |
+| `name`                      | The kit's identifier. Pass the kit directory to `sbx run`.                                                         |
 | `sandbox.image`             | The pinned image you published in Step 3. Its `CMD` launches Vibe, so the kit doesn't set an entrypoint.       |
 | `agentInstructions.filename`| The instructions file Vibe reads in the project.                                                               |
 | `agentInstructions.content` | Markdown appended to `AGENTS.md` at creation to prime the agent about its environment.                         |
@@ -177,8 +177,8 @@ Each field does the following:
 | `credentials[].apiKey.name` | The environment variable the proxy manages. Vibe sees a sentinel value; the proxy swaps in the real key.       |
 | `credentials[].apiKey.inject`| Where and how the proxy attaches the key. `scheme: bearer` sets `Authorization: Bearer <key>` for the domain. |
 
-For the full kit format, see
-[Kits](../manuals/ai/sandboxes/customize/kits.md).
+For the v2 kit format used in this guide, see
+[Kits v2](../manuals/ai/sandboxes/customize/kits-v2/_index.md).
 
 > [!WARNING]
 > `--agent auto-approve` runs Vibe in a mode that approves every tool
@@ -197,13 +197,13 @@ $ sbx kit validate ./mistral-vibe
 Then, from your project directory, launch the agent with the kit:
 
 ```console
-$ sbx run --kit ./mistral-vibe --name mistral-vibe mistral-vibe .
+$ sbx run ./mistral-vibe --name mistral-vibe .
 ```
 
-- `--kit ./mistral-vibe` points to the folder that contains `spec.yaml`.
+- `./mistral-vibe` is the sandbox kit reference, pointing to the folder that
+  contains `spec.yaml`.
 - `--name mistral-vibe` names the sandbox. Without it, `sbx` derives a name
   from the agent and the working directory, and the commands below won't match.
-- `mistral-vibe` is the agent name from `spec.yaml`.
 - `.` is the project directory to mount in the sandbox.
 
 Vibe starts in an isolated microVM, talks to the Mistral API through the
@@ -223,7 +223,7 @@ it. Use it to spot a host missing from `permissions.network.allow`. After you
 change `spec.yaml`, recreate the sandbox for a clean start:
 
 ```console
-$ sbx rm mistral-vibe && sbx run --kit ./mistral-vibe --name mistral-vibe mistral-vibe .
+$ sbx rm mistral-vibe && sbx run ./mistral-vibe --name mistral-vibe .
 ```
 
 ## Clean up

@@ -37,7 +37,7 @@ value for the same service, the stored secret takes precedence.
 | [Stored secrets](#stored-secrets) (`sbx secret set`)                        | A value or dynamic source in your OS keychain, keyed by service | The default for any built-in or kit-declared service                                                          |
 | [Custom secrets](#custom-secrets) (`sbx secret set-custom`)                 | A value keyed to a domain and environment variable           | The service model doesn't fit — the agent validates the variable's format, or the secret rides in a request body |
 | OAuth                                                                       | A host-side sign-in flow; the token never enters the sandbox | The agent supports it, such as Claude Code, Codex, Cursor, or Droid                                              |
-| [Credential bindings](#credential-bindings) (`credentials.yaml`)            | Per-service mechanism and domain approval                    | Required for third-party `schemaVersion: "2"` kits                                                               |
+| [Credential bindings](#credential-bindings) (`credentials.yaml`)            | Per-service mechanism and domain approval                    | Required for third-party kits                                                               |
 | [Registry credentials](#registry-credentials) (`sbx secret set --registry`) | Authentication for pulling images and kits                   | Pulling templates or kits from a private registry                                                                |
 
 For multi-provider agents (OpenCode, Docker Agent), the proxy selects
@@ -211,8 +211,33 @@ it into requests to the listed API domains.
 
 ### Services declared by kits
 
-Custom kits can declare their own service identifiers in `spec.yaml`. In
-`schemaVersion: "2"`, credentials are declared under the `credentials:` list:
+Custom kits declare their service identifiers in the kit descriptor. V3 uses a
+credential capability, and v2 uses a top-level `credentials` list:
+
+{{< tabs >}}
+{{< tab name="v3" >}}
+
+```yaml
+capabilities:
+  - type: com.docker.runtime/network-policy@1
+    config:
+      runtime:
+        allow: [api.my-service.com]
+  - type: com.docker.runtime/credential@1
+    config:
+      service: my-service
+      phase: runtime
+      apiKey:
+        name: MY_SERVICE_TOKEN
+        proxyManaged: true
+        inject:
+          - domain: api.my-service.com
+            header: Authorization
+            format: "Bearer %s"
+```
+
+{{< /tab >}}
+{{< tab name="v2" >}}
 
 ```yaml
 credentials:
@@ -223,8 +248,15 @@ credentials:
       inject:
         - domain: api.my-service.com
           scheme: bearer
+
+permissions:
+  network:
+    allow: [api.my-service.com]
 ```
 
+{{< /tab >}}
+{{< /tabs >}}
+
 Each service declares `apiKey`, `oauth`, or both. When both resolve at runtime,
 the API key takes precedence and OAuth acts as the fallback. To provide the
 credential value, run `sbx secret set` with the same identifier the kit
@@ -434,8 +466,8 @@ you've approved for each service. It lives at
 `~/.config/sbx/credentials.yaml`, or `%APPDATA%\sbx\credentials.yaml` on
 Windows.
 
-Third-party kits that declare `schemaVersion: "2"` require an approved binding
-for each credential they use. `sbx` creates one interactively the first time you
+Third-party kits require an approved binding for each credential they use,
+regardless of schema version. `sbx` creates one interactively the first time you
 run such a kit (see [First-run approval](#first-run-approval)); you can also
 write entries by hand. Credentials declared only by embedded, built-in kits are
 authorized by provenance and don't need a binding.
@@ -478,25 +510,23 @@ both cases, you approve the domains declared by the kit. `sbx` writes the entry
 to `credentials.yaml`.
 
 In non-interactive contexts (CI or `--detached`), there's no one to answer the
-prompt. Without a binding, the sandbox starts with the credential withheld. If
-the kit marks the credential as `required: true`, `sbx` also prints a warning.
+prompt. Without a binding, the sandbox starts with the credential withheld. For a
+required credential, `sbx` also prints a warning.
 Pre-create the binding by running the kit interactively once or by writing
 `credentials.yaml` directly before running unattended.
 
-The bindings file gates whether a third-party v2 kit can use a service
+The bindings file gates whether a third-party kit can use a service
 credential. The kit's credential injection rules and network permissions still
 constrain which requests can carry the credential.
 
 ### Kits that require a binding
 
-Only third-party kits that declare `schemaVersion: "2"` require a binding.
-Built-in agents also use `schemaVersion: "2"`, but credentials declared only by
-embedded kits are authorized by provenance and inject automatically. A
-third-party kit that extends a built-in agent inherits its credentials, but not
-its built-in provenance. The inherited credentials therefore require approval.
+Third-party kits require a binding regardless of schema version. Credentials
+declared only by embedded kits are authorized by provenance and inject
+automatically. A third-party v2 kit that extends a built-in agent inherits its
+credentials, but not its built-in provenance. The inherited credentials therefore require approval.
 If a third-party kit declares the same service itself, that service also
-requires approval. Kits on `schemaVersion: "1"` inject their declared
-credentials without a binding.
+requires approval.
 
 ## Registry credentials
 
@@ -561,10 +591,11 @@ To scope the credential to a single sandbox, store it under that sandbox's name:
 $ gh auth token | sbx secret set --sandbox my-app --registry ghcr.io --password-stdin
 ```
 
-For Docker Hub, `sbx kit pull` and `sbx kit push` use the session from
+For v2 kits on Docker Hub, `sbx kit pull` and `sbx kit push` use the session from
 `sbx login`. For other registries, both commands use these credentials. Both
 commands fall back to the Docker credential store, so credentials from
-`docker login` also work.
+`docker login` also work. V3 kits are published with Docker Buildx, which uses
+the credentials from `docker login`.
 
 ### Remove registry credentials
 

@@ -1,8 +1,8 @@
 ---
 title: Customizing sandboxes
 linkTitle: Customize
-description: Build reusable sandbox images and extend or define agents using templates and kits.
-keywords: sandboxes, sbx, customize, templates, kits, mixins, custom agents
+description: Build reusable sandbox workloads and extensions with kits, or customize and save sandbox template images.
+keywords: sandboxes, sbx, customize, templates, kits, mixins, workloads, custom agents
 weight: 90
 aliases:
   - /ai/sandboxes/agents/custom-environments/
@@ -15,56 +15,43 @@ params:
 
 {{< summary-bar feature_name="Docker Sandboxes sbx" >}}
 
-Docker Sandboxes offers two ways to customize a sandbox beyond the built-in
-defaults:
+Use kits and templates to package the tools, configuration, and runtime
+behavior your sandboxes need.
 
-- [Templates](templates.md) — reusable sandbox images with tools, packages,
-  and configuration baked in. Extend a base image with a Dockerfile, or
-  save a running sandbox as a template.
-- [Kits](kits.md) — declarative YAML artifacts that extend an agent with
-  tools, credentials, network rules, and files at runtime, or define a new
-  agent from scratch.
+- [Kits](kits.md) combine reusable image content with runtime declarations for
+  credentials, network access, storage, lifecycle hooks, and agent instructions.
+  A workload kit defines what the sandbox runs. Mixin kits extend it.
+- [Templates](templates.md) are reusable sandbox images. Extend a base image
+  with a Dockerfile, or save a configured running sandbox as a template.
 
-Kits are experimental. The kit file format, CLI commands, and experience for
-creating, loading, and managing kits are subject to change as the feature
-evolves. Share feedback and bug reports in the
+Kits are experimental. The format and CLI commands are subject to change.
+Share feedback in the
 [docker/sbx-releases](https://github.com/docker/sbx-releases) repository.
 
-## Templates and kits, side by side
+## Choose a customization
 
-A template is a Docker image that the sandbox runs. It's built ahead
-of time with a Dockerfile (or saved from a running sandbox), pushed to a
-registry, and pulled when a sandbox is created. Use templates for things
-that belong in an image: system packages, language toolchains, large
-dependencies — anything you'd rather not reinstall on every sandbox start.
+| Goal | Option |
+| --- | --- |
+| Define an agent or another sandbox workload | [Workload kit](build-an-agent.md) |
+| Add a tool, configuration, or runtime capability to a v3 workload | [Mixin kit](kit-examples.md) |
+| Customize the image used by a built-in agent | [Template](templates.md#build-a-custom-template) |
+| Capture a configured running sandbox for reuse | [Saved template](templates.md#saving-a-sandbox-as-a-template) |
+| Maintain an existing v2 sandbox or mixin kit | [Kits v2](kits-v2/_index.md) |
 
-A kit is a YAML artifact applied at sandbox creation. The kit can run
-install commands, drop files into the sandbox, declare network and
-credential rules, and (for sandbox kits) define which template image the
-agent runs in. Use kits for things that vary per agent or per team:
-shared linter config, project-specific install steps, credential
-injection for a service the agent talks to.
+Use v3 for authoring kits. Docker Sandboxes also supports v1 and v2, whose
+`spec.yaml` workflow is documented in [Kits v2](kits-v2/_index.md). A single
+composition cannot combine v3 kits with v1 or v2 kits.
 
-Templates and kits work together. A sandbox kit's `sandbox.image` field
-points at a template: the template provides the base environment, the
-kit layers config, secrets, and runtime behavior on top. A team can ship
-one heavy template and several thin kits without rebuilding the image
-each time something changes.
+## Builds and runtime configuration
 
-## When to use which
+A kit starts as source files: a YAML descriptor for sandbox behavior and a
+Dockerfile for software and files to package. Building them produces an image
+you can share. Docker Sandboxes reads the descriptor when it runs the kit.
 
-| Goal                                                      | Option                                                        |
-| --------------------------------------------------------- | ------------------------------------------------------------- |
-| Pre-install tools and packages into a reusable base image | [Template](templates.md)                                      |
-| Capture a configured running sandbox for reuse            | [Saved template](templates.md#saving-a-sandbox-as-a-template) |
-| Add a tool, credential, or config to agent runs via YAML  | [Kit (mixin)](kits.md)                                        |
-| Define a new agent from scratch                           | [Kit (sandbox)](kits.md#define-an-agent)                      |
+For example, an agent kit can install the agent during its build, then request
+access to its API and credentials when the sandbox runs. The installed agent
+is reused across sandboxes, while each sandbox receives its own configuration.
 
-Templates and kits can be used together. A template bakes heavy tools into
-the image for fast sandbox startup; a kit layered on top adds per-run
-credentials, config, or extra capabilities.
-
-## Tutorials
-
-- [Build your own agent kit](build-an-agent.md) — step-by-step walkthrough
-  for packaging [Amp](https://ampcode.com/) as a sandbox kit.
+A workload kit can use a sandbox template as its base image. Mixins add tools
+or behavior to that workload. See [Kits](kits.md) for the file layout, a
+complete example, and how the parts work together.