Installation

Install the latest release from GitHub without cloning the repository:

curl -fsSL https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.sh | DOWNLOAD_BASE_URL=https://github.com/runui/oci-mirror-proxy sh -s -- --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
oci-mirror-proxy version

Update an existing installation:

curl -fsSL https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.sh | DOWNLOAD_BASE_URL=https://github.com/runui/oci-mirror-proxy sh -s -- update --prefix "$HOME/.local"

On Linux, run the installer with root privileges. It starts the proxy at boot and automatically connects local Docker; no separate Docker setup is needed:

curl -fsSL https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.sh | sudo env DOWNLOAD_BASE_URL=https://github.com/runui/oci-mirror-proxy sh -s -- --service
# Update the system installation and restart its service:
curl -fsSL https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.sh | sudo env DOWNLOAD_BASE_URL=https://github.com/runui/oci-mirror-proxy sh -s -- update --prefix /usr/local --service

The script downloads the matching Linux, macOS, or FreeBSD binary and verifies its SHA256 checksum. When no matching binary is available, or --build is specified, it builds release source using Go 1.26.8 or newer (or Go toolchain auto-download). Use --version v1.0.1 to select a release. To use a mirror, set DOWNLOAD_BASE_URL to its repository root URL (with the same /releases and /archive layout). When piping the script, pass the variable to sh, not just to curl:

curl -fsSL https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.sh | DOWNLOAD_BASE_URL=https://mirror.example.com/runui/oci-mirror-proxy sh -s -- --prefix "$HOME/.local"

The default prefix is /usr/local, which requires write permission. Existing configuration is preserved; without --service, no service is installed or restarted. Restart a running proxy manually after updating without --service.

Platforms and Windows installationCopy Anchor Link

Prebuilt binaries are available for the following platforms:

On Windows, download and inspect the PowerShell installer, then run it in PowerShell. Approve the Windows administrator prompt when requested:

Invoke-WebRequest https://github.com/runui/oci-mirror-proxy/raw/refs/heads/master/install.ps1 -OutFile install.ps1
.\install.ps1 -DownloadBaseUrl https://github.com/runui/oci-mirror-proxy
# Update the installation and restart its service:
.\install.ps1 update -DownloadBaseUrl https://github.com/runui/oci-mirror-proxy

The installer starts the proxy as a Windows service, enables startup at boot, automatically connects Docker Desktop, and adds the program to PATH. No separate Docker setup is needed. Open a new terminal to run oci-mirror-proxy directly. Updates preserve existing configuration. .NET Framework 4.x is required.

For troubleshooting and service management, see operations. For optional installation settings, run Get-Help .\install.ps1 -Full.

The --service option supports Linux systemd/OpenRC and macOS launchd system services. Sudo installs without --service initialize user configuration as the verified invoking user. See macOS installation and permissions for service management and recovery from older root-owned user configurations.

Update and uninstallCopy Anchor Link

sh install.sh update --prefix "$HOME/.local"
sudo sh install.sh update --prefix /usr/local --service
sh install.sh uninstall --prefix "$HOME/.local"
sudo sh install.sh uninstall --prefix /usr/local

.\install.ps1 update
.\install.ps1 uninstall

Updates preserve existing configuration. If automatic Docker setup cannot finish, the installer keeps the proxy installed and prints recovery instructions. Docker is not restarted automatically; if a restart is needed, follow the installer's output.

Windows PowerShell 5.1 and PowerShell 7 are supported. Registry compatibility warnings do not by themselves indicate installation failure: Docker Desktop mirrors only Docker Hub, so other registries may be skipped. A pending restart means the settings were saved but are not yet active. The installer does not restart Docker or interrupt running containers automatically.

Service uninstall first removes this proxy from the invoking Docker user's current settings, preserving other mirrors and settings. Cleanup failure aborts removal; use -SkipDocker (Windows) or --skip-docker (Unix) to explicitly leave Docker unchanged. Proxy configuration, caches and logs are preserved. Binary-only removal does not edit Docker. See operations for manual recovery.

For options, run sh install.sh --help or Get-Help .\install.ps1 -Full.

Docker deploymentCopy Anchor Link

Docker Engine and macOS Docker Desktop users can deploy with docker-compose.yaml. Prepare the writable configuration directory, then run docker compose up -d --no-build. The image supports amd64/arm64 and uses bridge networking with a host-loopback-only published port, without mounting the Docker socket. See Docker deployment for setup, local builds, and host dockerd configuration.

Build from sourceCopy Anchor Link

make build                                   # produces dist/oci-mirror-proxy

dist/oci-mirror-proxy init                   # writes the per-user config file
dist/oci-mirror-proxy serve &                # runs the proxy in the background

dist/oci-mirror-proxy upstream add \
  --id mirror-a --url https://mirror-a.example.com

sudo dist/oci-mirror-proxy dockerd plan      # shows what will change; writes nothing
sudo dist/oci-mirror-proxy dockerd apply     # writes the dockerd configuration
dist/oci-mirror-proxy doctor                 # verifies proxy, dockerd and config

Start from examples/config.example.yaml for a complete configuration with every option explained.