docker · dvdksn · Sep 14, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 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).
+This guide uses the deprecated v2 format. For its reference and migration
+guidance, 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

@@ -122,7 +122,7 @@ See [Git workflows](../workflows/git.md) for clone-mode details.
 ## Base image
 
 The sandbox uses `docker/sandbox-templates:claude-code`. See
-[Templates](../customize/templates.md) to build your own image on top of
+[Base images](../customize/base-images.md) to build your own image on top of
 this base.
 
 ## Use a local model

@@ -69,5 +69,5 @@ $ sbx run --name <sandbox-name> -- run --yolo agent.yml
 ## Base image
 
 The sandbox uses `docker/sandbox-templates:docker-agent`. See
-[Templates](../customize/templates.md) to build your own image on top of
+[Base images](../customize/base-images.md) to build your own image on top of
 this base.
@@ -52,7 +52,7 @@ $ sbx secret set openai
 
 Once inside the shell, you can install agents using their standard methods,
 for example `npm install -g @continuedev/cli`. For complex setups, build a
-[custom template](../customize/templates.md) instead of installing
+[workload kit](../customize/kits.md) instead of installing
 interactively each time.
 
 ## Base image

@@ -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,34 @@ 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. The deprecated v2 format 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 +249,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
@@ -237,7 +270,8 @@ $ sbx secret set my-service
 There's no separate registration step; the keychain entry is keyed on the
 identifier the kit already uses. See
 [Authenticate to external services](../customize/kits.md#authenticate-to-external-services)
-for the full kit-side wiring.
+for the v3 configuration. For existing v2 kits, see
+[V2 credentials](../customize/kits-v2/_index.md#credentials).
 
 ### List and remove secrets
 
@@ -434,8 +468,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,30 +512,28 @@ 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
 
 Registry credentials authenticate to private OCI registries when pulling
-[templates](../customize/templates.md) or [kits](../customize/kits.md), and can
+[templates](../usage.md#load-a-template) or [kits](../customize/kits.md), and can
 also let the agent pull and push images from inside the sandbox through the
 host-side proxy. Use `sbx secret set --registry <host>` to store them. For
 Docker Hub, `sbx` reuses your `sbx login` session — no registry secret needed.
@@ -561,10 +593,12 @@ 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](../customize/kits.md#publish-an-image),
+which uses the credentials from `docker login`.
 
 ### Remove registry credentials
 

@@ -54,7 +54,7 @@ mirror URL paths differently from image repository prefixes.
 Docker Engine connects to the mirror over HTTPS, so the sandbox must trust the
 certificate that the mirror presents. For a mirror that uses an internal
 certificate authority, add the CA to the sandbox's system trust store. See
-[Install an internal CA certificate](../customize/kit-examples.md#install-an-internal-ca-certificate).
+[Install an internal CA certificate](../customize/kits-v2/_index.md#install-an-internal-ca-certificate).
 
 Template and kit pulls use the changed setting immediately. Existing sandboxes
 retain the Docker Engine mirror configuration with which they were created.

@@ -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 and share sandbox environments with v3 workload and mixin kits, using Docker-provided base images or your own Linux image.
+keywords: sandboxes, sbx, customize, templates, kits, mixins, workloads, custom agents
 weight: 90
 aliases:
   - /ai/sandboxes/agents/custom-environments/
@@ -15,56 +15,37 @@ params:
 
 {{< summary-bar feature_name="Docker Sandboxes sbx" >}}
 
-Docker Sandboxes offers two ways to customize a sandbox beyond the built-in
-defaults:
+Use kits to package the tools, configuration, and runtime behavior your
+sandboxes need. A workload kit defines the environment and command to run.
+Mixin kits extend it with tools, configuration, or instructions.
 
-- [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.
+A workload's build recipe can start from a Docker-provided agent image or
+another Linux base image. Its descriptor declares network access, credentials,
+and lifecycle hooks alongside that build.
 
-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 |
+| --- | --- |
+| Run a v3 workload and add mixins | [Use kits](kits.md#use-kits) |
+| Define an agent or another sandbox workload | [Build an agent](build-an-agent.md) |
+| Add tools, configuration, or instructions to a v3 workload | [Mixin examples](kit-examples.md) |
+| Choose an existing agent image or your own Linux base | [Base images](base-images.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.
+## Start with v3 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.
+V3 is the recommended format for kit development. To use it, select an
+explicit v3 workload reference and combine it with v3 mixins. Built-in agent
+shortcuts such as `claude` and `codex` select v2 kits, so they can't be used
+with v3 mixins. See [Run a kit](kits.md#run-a-kit) for the opt-in workflow.
 
-## When to use which
+V2 is deprecated but remains supported. For existing customizations, see
+[Kits v2](kits-v2/_index.md), including guidance for moving a complete
+environment to v3.
 
-| 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)                      |
-
-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.
+To capture an interactively configured sandbox's container filesystem for reuse,
+see [Save a sandbox as a template](/manuals/ai/sandboxes/usage.md#saving-a-sandbox-as-a-template).