From 1f6bf36d429f70522d69ef00bc5a84bbc41bdb43 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 4 Nov 2026 10:08:45 +0100
Subject: [PATCH] Clarify published references for built-in sandbox kits
 (#26458)

Explain how built-in names such as `claude` and `codex` resolve to
Docker Hub kits, with the canonical Codex reference as an example.
Distinguish these references from the versioned v3 workloads listed in
the guide.

Validation: Markdown formatting and scoped rumdl/Vale checks passed with
no findings. Runtime examples were not run because `sbx` was
unavailable.
---
 .../ai/sandboxes/configuration/settings.md    | 26 +------------------
 .../ai/sandboxes/customize/use-kits.md        | 10 ++++---
 2 files changed, 8 insertions(+), 28 deletions(-)

diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md
index 5dff6081c9..c23caf0eaf 100644
--- a/content/manuals/ai/sandboxes/configuration/settings.md
+++ b/content/manuals/ai/sandboxes/configuration/settings.md
@@ -340,8 +340,7 @@ $ sbx settings set kit.allowedSources '["docker.io/","github.com/myorg/"]'
 Prefixes match on a path-segment boundary: `github.com/myorg/` permits that
 organization's repositories, but not `github.com/myorg-other/`. The value
 `["*"]` permits any remote source. Local directories and ZIP files are controlled
-by [kit.allowLocalKits](#kitallowlocalkits), and pinned agent kits have the
-[kit.allowExtractedAgents](#kitallowextractedagents) exception.
+by [kit.allowLocalKits](#kitallowlocalkits).
 
 See [restrict kit sources](../customize/use-kits.md#restrict-kit-sources) for source
 formats and examples.
@@ -363,27 +362,6 @@ Keep this enabled while developing kits locally. Allowing local kits doesn't
 exempt them from signature requirements when
 [kit.requireSignature](#kitrequiresignature) is enabled.
 
-#### kit.allowExtractedAgents {.wrap-anywhere}
-
-{{< setting-metadata type="boolean" default="true"
-  env="DOCKER_SANDBOXES_KIT_ALLOW_EXTRACTED_AGENTS" >}}
-
-Some agents that previously shipped inside Docker Sandboxes are distributed
-as kits. By default, Docker Sandboxes permits the exact pinned references it
-uses for those agents even if their sources aren't in `kit.allowedSources`,
-and exempts them from `kit.requireSignature`.
-
-To apply your source and signature requirements to those kits too:
-
-```console
-$ sbx settings set kit.allowExtractedAgents false
-```
-
-After this change, launching one of those agents can fail unless you allow its
-source and, when signatures are required, it has a signature from a trusted
-signer. The default exception applies only to the pinned references, not to
-other kits from the same publisher.
-
 #### kit.requireSignature {.wrap-anywhere}
 
 {{< setting-metadata type="boolean" default="false"
@@ -399,8 +377,6 @@ $ sbx settings set kit.requireSignature true
 
 The check applies when installing kits from local directories, Git, or OCI
 registries. ZIP kits can't carry verifiable signatures and are rejected.
-Pinned agent kits remain exempt while
-[kit.allowExtractedAgents](#kitallowextractedagents) is `true`.
 
 A signature covers the kit's `spec.yaml` and `files/` content. It doesn't pin
 image tags or verify downloads performed by the kit's commands. See
diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md
index e38e806aec..1879ddc09f 100644
--- a/content/manuals/ai/sandboxes/customize/use-kits.md
+++ b/content/manuals/ai/sandboxes/customize/use-kits.md
@@ -18,9 +18,13 @@ for built-in agent references such as `claude` and `codex`.
 
 ## Run a kit
 
-The built-in agent names are shortcuts for kit references. To run another kit,
-replace the agent name with that kit's reference. For example, run Docker's
-published v3 Codex workload:
+Built-in names such as `claude` and `codex` resolve to kits published on
+Docker Hub under `docker.io/sbx/<NAME>:latest`. For example, `codex` resolves
+to `docker.io/sbx/codex:latest`. These references differ from the versioned
+v3 workloads listed below.
+
+To run another kit, replace the agent name with that kit's reference. For
+example, run Docker's published v3 Codex workload:
 
 ```console
 $ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit