From 8da69ed6c237ca7a252904df6203118fbea3efdd Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 4 Nov 2026 10:04:06 +0100
Subject: [PATCH] Update shell base image references for custom sandbox
 workloads (#26474)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update the base-image reference, v2 kit guidance, and Mistral Vibe
example to use the published shell base images. Distinguish these images
from the shell kit so users choose the appropriate base for custom
workloads.

Validation: Scoped Markdown and Vale checks passed. Verified image
publication and the Docker-enabled image’s user and tools; the full Vibe
sandbox workflow was not rerun.
---
 content/guides/mistral-vibe-sandbox.md        |  4 ++--
 .../sandboxes/customize/author/base-images.md | 20 +++++++++++++++++--
 .../manuals/ai/sandboxes/customize/kits-v2.md |  2 +-
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/content/guides/mistral-vibe-sandbox.md b/content/guides/mistral-vibe-sandbox.md
index 4816d43012..86dcf1ee1e 100644
--- a/content/guides/mistral-vibe-sandbox.md
+++ b/content/guides/mistral-vibe-sandbox.md
@@ -94,11 +94,11 @@ mistral-vibe/
 └── vibe.dockerfile
 ```
 
-Create `mistral-vibe/vibe.dockerfile`. The `shell-docker` template supplies
+Create `mistral-vibe/vibe.dockerfile`. The `shell-docker-image` base image supplies
 the agent account, Python, `uv`, and the sandbox's Docker tooling:
 
 ```dockerfile {title="mistral-vibe/vibe.dockerfile"}
-FROM docker/sandbox-templates:shell-docker
+FROM docker.io/sbx/shell-docker-image:latest
 
 ARG VIBE_VERSION
 
diff --git a/content/manuals/ai/sandboxes/customize/author/base-images.md b/content/manuals/ai/sandboxes/customize/author/base-images.md
index c4d9124a61..b9d546c0c4 100644
--- a/content/manuals/ai/sandboxes/customize/author/base-images.md
+++ b/content/manuals/ai/sandboxes/customize/author/base-images.md
@@ -22,7 +22,8 @@ To save and reuse an environment you've configured interactively, see
 
 ## Docker-provided images
 
-Docker's sandbox templates are published as
+To customize an existing agent, start from one of Docker's sandbox templates,
+published as
 `docker/sandbox-templates:<variant>`. They are based on Ubuntu and run as a
 non-root `agent` user with sudo access. Most variants include Git, Docker
 CLI, and common development tools like Node.js, Python, Go, and Java. Full
@@ -41,7 +42,22 @@ templates also include a C/C++ compiler toolchain for building native code.
 | `gemini`              | [Gemini CLI](https://github.com/google-gemini/gemini-cli)            |
 | `kiro`                | [Kiro](https://kiro.dev)                                             |
 | `opencode`            | [OpenCode](https://opencode.ai)                                      |
-| `shell`               | No agent pre-installed. Use for manual agent setup.                  |
+
+Docker rebuilds the `claude-code`, `claude-code-minimal`, `gemini`,
+`claude-code-docker`, and `gemini-docker` variants. The other variants in the
+table remain available as previously published images.
+
+### Build a custom agent on a shell image
+
+To package an agent that Docker doesn't provide, start from
+`docker.io/sbx/shell-image:latest`. This base image provides a development
+environment without a pre-installed agent, so you can add your agent's tooling
+on top. Use `docker.io/sbx/shell-docker-image:latest` if your workload needs
+Docker Engine inside the sandbox.
+
+If you need a different operating system or want to choose every package,
+[use your own Linux image](#use-your-own-linux-image). You'll need to prepare
+the tools and user account that Docker Sandboxes expects yourself.
 
 ## Use an image in a v3 workload
 
diff --git a/content/manuals/ai/sandboxes/customize/kits-v2.md b/content/manuals/ai/sandboxes/customize/kits-v2.md
index 6d83f41fa4..c19b0d470a 100644
--- a/content/manuals/ai/sandboxes/customize/kits-v2.md
+++ b/content/manuals/ai/sandboxes/customize/kits-v2.md
@@ -303,7 +303,7 @@ The agent's container image must provide:
 - HTTP proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) preserved across sudo.
 - The agent binary, either baked in or installed with [`setup.install`](#setup).
 
-Build on top of `docker/sandbox-templates:shell-docker` to get these base
+Build on top of `docker.io/sbx/shell-docker-image:latest` to get these base
 requirements.
 
 ## Agent instructions