From 0e6e237843c616ac36d299a6b5abcad5e708e000 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 27 Aug 2026 09:58:19 +0000 Subject: [PATCH 1/3] docs: document Sandbox registry mirrors The registry mirror setting lacked discoverable conceptual configuration. Document how it redirects Docker Hub template and kit images, when it also configures Docker inside a sandbox, and how to disable it. --- .../ai/sandboxes/configuration/_index.md | 6 +- .../configuration/registry-mirror.md | 74 +++++++++++++++++++ .../ai/sandboxes/customize/templates.md | 4 +- 3 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 content/manuals/ai/sandboxes/configuration/registry-mirror.md diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md index 31d09f14b14..b49773d73ca 100644 --- a/content/manuals/ai/sandboxes/configuration/_index.md +++ b/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. diff --git a/content/manuals/ai/sandboxes/configuration/registry-mirror.md b/content/manuals/ai/sandboxes/configuration/registry-mirror.md new file mode 100644 index 00000000000..ef30fc565e2 --- /dev/null +++ b/content/manuals/ai/sandboxes/configuration/registry-mirror.md @@ -0,0 +1,74 @@ +--- +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 +--- + +Configure a registry mirror to route Docker Hub image pulls through your +organization's registry infrastructure. The mirror applies to sandbox template +images and OCI kit images. When the mirror is compatible with Docker Engine, +it also applies to Docker Hub pulls made by Docker inside a sandbox. + +## 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 reachable 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`, `127.0.0.1`, or `0.0.0.0` | Mirrored when host-reachable | Not mirrored | + +Loopback and wildcard 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. + +The mirror serves Docker Engine traffic over HTTPS. 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). + +Changes apply to subsequent template and kit pulls. Docker Sandboxes writes the +in-sandbox Docker Engine configuration when it creates the sandbox, and that +configuration persists across sandbox stops and starts. Remove and create an +existing sandbox again to apply a changed mirror to its Docker Engine. + +## 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. diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index 72bcade5d94..762f61f92a2 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/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 From e102f71dad25a87443cb75d1eaef7f3cbc08e5bc Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 11:39:14 +0000 Subject: [PATCH 2/3] docs: clarify registry mirror behavior --- .../sandboxes/configuration/registry-mirror.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/registry-mirror.md b/content/manuals/ai/sandboxes/configuration/registry-mirror.md index ef30fc565e2..340df0ff7af 100644 --- a/content/manuals/ai/sandboxes/configuration/registry-mirror.md +++ b/content/manuals/ai/sandboxes/configuration/registry-mirror.md @@ -6,10 +6,9 @@ keywords: docker sandboxes, sbx, registry mirror, docker hub, templates, kits, i weight: 50 --- -Configure a registry mirror to route Docker Hub image pulls through your -organization's registry infrastructure. The mirror applies to sandbox template -images and OCI kit images. When the mirror is compatible with Docker Engine, -it also applies to Docker Hub pulls made by Docker inside a sandbox. +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 @@ -52,15 +51,14 @@ 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. -The mirror serves Docker Engine traffic over HTTPS. The sandbox must trust the +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). -Changes apply to subsequent template and kit pulls. Docker Sandboxes writes the -in-sandbox Docker Engine configuration when it creates the sandbox, and that -configuration persists across sandbox stops and starts. Remove and create an -existing sandbox again to apply a changed mirror to its Docker Engine. +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 From af1c3a7cf56a345163f7c758e36bb0c3242d1b59 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 14:49:06 +0000 Subject: [PATCH 3/3] docs: clarify loopback registry mirrors --- .../configuration/registry-mirror.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/registry-mirror.md b/content/manuals/ai/sandboxes/configuration/registry-mirror.md index 340df0ff7af..dc4cb9dea03 100644 --- a/content/manuals/ai/sandboxes/configuration/registry-mirror.md +++ b/content/manuals/ai/sandboxes/configuration/registry-mirror.md @@ -37,19 +37,19 @@ 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 reachable 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`, `127.0.0.1`, or `0.0.0.0` | Mirrored when host-reachable | Not mirrored | - -Loopback and wildcard 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. +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