docs: document Sandbox registry mirrors

content/manuals/ai/sandboxes/configuration/_index.md

@@ -2,8 +2,8 @@
 title: Configure Docker Sandboxes
 linkTitle: Configuration
 weight: 60
-description: Configure credentials, project environments, GPU passthrough, and upstream proxy settings for Docker Sandboxes.
-keywords: docker sandboxes, sbx, configuration, credentials, environment files, gpu passthrough, upstream proxy
+description: Configure credentials, project environments, GPU passthrough, registry mirrors, and upstream proxy settings for Docker Sandboxes.
+keywords: docker sandboxes, sbx, configuration, credentials, environment files, gpu passthrough, registry mirror, upstream proxy
 ---
 
 Configure credentials and how Docker Sandboxes run for a project, host, or
@@ -17,5 +17,7 @@ sandbox, see [Customize](../customize/).
   configuration in `.sbxenv.yaml`.
 - [GPU passthrough](gpu-passthrough.md) configures a Linux host and sandbox for
   NVIDIA GPU workloads.
+- [Registry mirror](registry-mirror.md) routes Docker Hub template, kit, and
+  in-sandbox Docker image pulls through an organization's registry mirror.
 - [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through
   an operating system or corporate proxy.

content/manuals/ai/sandboxes/configuration/registry-mirror.md

@@ -0,0 +1,72 @@
+---
+title: Configure a registry mirror
+linkTitle: Registry mirror
+description: Route Docker Hub template, kit, and in-sandbox Docker image pulls through an organization's registry mirror.
+keywords: docker sandboxes, sbx, registry mirror, docker hub, templates, kits, image pulls
+weight: 50
+---
+
+A registry mirror routes Docker Hub pulls for sandbox templates and OCI kits
+through your organization's registry infrastructure. If the mirror meets
+Docker Engine's requirements, Docker inside the sandbox uses it too.
+
+## Configure the mirror
+
+Set `platform.images.registryMirror` to the mirror host. Include a port when
+needed, but omit the URL scheme:
+
+```console
+$ sbx settings set platform.images.registryMirror registry.example.com
+```
+
+You can include a path prefix for registries that store mirrored Docker Hub
+content below a repository path:
+
+```console
+$ sbx settings set platform.images.registryMirror registry.example.com/docker-remote
+```
+
+Docker Sandboxes redirects image references that resolve to Docker Hub and
+preserves their repository path, tag, and digest. References that explicitly
+name another registry remain unchanged.
+
+If the mirror requires authentication, configure
+[registry credentials](credentials.md#registry-credentials) for the mirror
+host.
+
+## Mirror Docker pulls inside the sandbox
+
+Docker Sandboxes configures Docker Engine inside a sandbox to use the same
+mirror when the setting contains a non-loopback host without a path prefix.
+
+| Mirror setting                         | Template and OCI kit pulls | Docker pulls inside the sandbox |
+| -------------------------------------- | -------------------------- | ------------------------------- |
+| `registry.example.com`                 | Mirrored                   | Mirrored                        |
+| `registry.example.com:5000`            | Mirrored                   | Mirrored                        |
+| `registry.example.com/docker-remote`   | Mirrored                   | Not mirrored                    |
+| `localhost:5000` or `127.0.0.1`        | Mirrored                   | Not mirrored                    |
+
+Loopback addresses refer to the sandbox itself from inside its network
+namespace, so Docker Sandboxes doesn't add them to the sandbox's Docker Engine
+configuration. A path prefix is also excluded because Docker Engine interprets
+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).
+
+Template and kit pulls use the changed setting immediately. Existing sandboxes
+retain the Docker Engine mirror configuration with which they were created.
+Recreate a sandbox to apply a changed mirror to Docker inside it.
+
+## Disable the mirror
+
+Unset the setting to disable mirroring:
+
+```console
+$ sbx settings unset platform.images.registryMirror
+```
+
+An empty setting value also disables mirroring. Recreate existing sandboxes to
+remove a mirror from their Docker Engine configuration.

content/manuals/ai/sandboxes/customize/templates.md

@@ -115,7 +115,9 @@ $ docker build -t my-org/my-template:v1 --push .
 > [!NOTE]
 > The Docker daemon used by Docker Sandboxes pulls templates from a
 > registry directly; it doesn't share the image store of your local Docker
-> daemon on the host.
+> daemon on the host. To route Docker Hub image pulls through your
+> organization's registry infrastructure, configure a
+> [registry mirror](../configuration/registry-mirror.md).
 
 > [!IMPORTANT]
 > For Docker Hub, `sbx` reuses your `sbx login` session to pull private