Installation

Install the latest release without cloning the repository. The documentation site serves the installer; release binaries and source archives use the installer's built-in download source:

curl -fsSL https://ocimp.zmide.com/install.sh | sh
oci-mirror-proxy version

Update an existing installation:

curl -fsSL https://ocimp.zmide.com/install.sh | sh -s -- update

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://ocimp.zmide.com/install.sh | sudo sh -s -- --service
# Update the system installation and restart its service:
curl -fsSL https://ocimp.zmide.com/install.sh | sudo sh -s -- update --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://ocimp.zmide.com/install.sh | DOWNLOAD_BASE_URL=https://mirror.example.com/runui/oci-mirror-proxy sh

On Linux, macOS, and FreeBSD, the default binary path is /usr/local/bin/oci-mirror-proxy. No --prefix is needed. The installer requests sudo if that directory is not writable; without sudo, run as root or choose a writable custom directory. For an optional user-only installation, pass --prefix "$HOME/.local" and add $HOME/.local/bin to PATH. 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://ocimp.zmide.com/install.ps1 -OutFile install.ps1
.\install.ps1
# Update the installation and restart its service:
.\install.ps1 update

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. The default binary directory is %ProgramFiles%\oci-mirror-proxy\bin; -Prefix is only needed for a custom installation directory.

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
sudo sh install.sh update --service
sh install.sh uninstall

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

Unix updates find the existing binary in PATH; uninstall also detects managed services. If you used a custom directory and it cannot be detected, specify its original --prefix (Windows: -Prefix).

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.