mcr-mirror / pull-through cache

This host proxies and caches image pulls from mcr.microsoft.com — .NET, Windows base images, Azure SQL Edge, and other Microsoft-published container images. Point Docker or containerd here to speed up pulls and cut outbound traffic. Replace mirror.example.com below with this server's actual hostname.

01 — LINUX / DOCKER ENGINE

Edit daemon.json

Add this mirror as a registry-mirror in the Docker daemon config, then restart the daemon.

/etc/docker/daemon.json

{
  "registry-mirrors": ["https://mirror.example.com"]
}

shell

# apply the config
sudo systemctl daemon-reexec
sudo systemctl restart docker

If daemon.json already has other keys, just add the registry-mirrors array — don't overwrite the file. Note that Docker's registry-mirrors only intercepts pulls for unqualified/Docker Hub-style names; since MCR images are always pulled with the full mcr.microsoft.com/... reference, most setups instead rely on the containerd hosts.toml approach below for a true per-registry mirror.

02 — DOCKER DESKTOP

macOS / Windows

Open Settings → Docker Engine, merge the same key into the JSON editor there, then click Apply & Restart.

Docker Desktop → Settings → Docker Engine

{
  "builder": { "gc": { "enabled": true } },
  "registry-mirrors": ["https://mirror.example.com"]
}

03 — CONTAINERD / AKS NODES

hosts.toml, scoped to mcr.microsoft.com

For containerd nodes — including AKS — configure a mirror specifically for the MCR registry namespace:

/etc/containerd/certs.d/mcr.microsoft.com/hosts.toml

server = "https://mcr.microsoft.com"

[host."https://mirror.example.com"]
  capabilities = ["pull", "resolve"]

Restart containerd afterward: sudo systemctl restart containerd. On AKS, this is typically delivered via a node bootstrap script or DaemonSet rather than edited by hand on each node.

04 — VERIFY

Confirm the daemon picked it up

shell

docker info --format '{{ .RegistryConfig.Mirrors }}'

# pull an MCR image and check it came from the mirror
docker pull mcr.microsoft.com/dotnet/runtime:8.0
curl -s https://mirror.example.com/v2/ -o /dev/null -w "%{http_code}\n"

Check	Expected result
`docker info`	Mirror URL listed under `Registry Mirrors`
`GET /v2/`	`200` or `401` — mirror is reachable
First pull of an image	Slower — cache miss, fetched from upstream and stored
Repeat pull of same image	Fast — served from local cache

05 — NOTES

Pull-through, not a full copy. This mirror caches images as they're requested — it doesn't proactively sync the entire MCR catalog. The first pull of any given image/tag is still fetched from mcr.microsoft.com.

MCR is read-only and syndicated from the Microsoft Artifact Registry — there's no docker push path to worry about here. Windows base images (mcr.microsoft.com/windows/...) can be significantly larger than Linux images, so caching them locally has an outsized bandwidth payoff. If this mirror is served over plain HTTP internally, add it to insecure-registries instead of registry-mirrors, or terminate TLS in front of it.