Configure a registry mirror
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:
$ 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:
$ 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 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.
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:
$ 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.