Overview

A local, read-only registry mirror proxy for dockerd. It sits between dockerd and one or more user-chosen Registry v2 mirrors and adds what dockerd's built-in mirror support lacks:

• Runtime management. Add, remove and disable upstreams without restarting dockerd.
• Failure isolation. A silent or failing mirror costs one timeout, then a circuit breaker takes it out of rotation until a probe succeeds.
• Optional racing. Hedged requests can answer from whichever mirror responds first.
• Resumable layers. A layer that breaks mid-transfer continues from the same byte offset on another mirror, and the daemon still verifies the digest.
• Safe fallback. When the proxy cannot serve a request, dockerd falls back to the official registry, so the proxy can never make a pull impossible.

It supports both dockerd image stores: containerd (hosts.toml) and the classic graphdriver store (daemon.json, docker.io only).

PreviewCopy Anchor Link

oci-mirror-proxy completed in 508.0 s versus 740.3 s directly from the mirror: 1.46× as fast, or 31.4% less time in this preview.

Direct mirror · 740.3 s	Through oci-mirror-proxy · 508.0 s
asciinema recording	asciinema recording

GIFs are time-compressed previews; the original recordings preserve real timing. See the recording details.

StatusCopy Anchor Link

Supported features: the registry API for pulls, failover, circuit breaking, hedged requests, blob resumption, token and basic authentication, the admin socket, configuration reload, and dockerd setup with revert.

Not supported: push, a local blob cache, keychain secret backends, and metrics export.

RequirementsCopy Anchor Link

• Go 1.26 or newer, to build.
• A local Docker Engine on Linux or Docker Desktop on macOS/Windows (Linux containers). See automatic Docker integration. Rootless dockerd needs the listen address reachable from its network namespace, which is left to the operator (see rootless dockerd).

Security notesCopy Anchor Link

• The registry API has no authentication, so it listens on 127.0.0.1 by default. A non-loopback listen exposes unauthenticated pulls to the network.
• Credentials never appear in the configuration file: a password is a reference such as env:NAME or file:/path. Secrets are redacted in logs and in %v output.
• Client Authorization headers are never forwarded upstream.
• The admin socket is protected by file permissions: its directory is 0700, and the socket is 0600 for private instances. Root services using the standard /run/oci-mirror-proxy/admin.sock or /var/run/oci-mirror-proxy/admin.sock endpoint allow all local users to access the management API (0711 directory, 0666 socket), including configuration changes and reloads. Only root can replace the directory or socket; the management API is not exposed over TCP.
• Mirror configuration is merged from actual files, without installation state. Changed files are backed up and atomically replaced; revert removes only the selected proxy entries.