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.

HomebrewCopy Anchor Link

Install the prebuilt release on macOS (Apple Silicon or Intel) or Linux (ARM64 or x86-64). The project repository also serves as its Homebrew tap, so the explicit repository URL is required on the first brew tap:

brew tap runui/oci-mirror-proxy https://github.com/runui/oci-mirror-proxy.git
brew install runui/oci-mirror-proxy/oci-mirror-proxy
oci-mirror-proxy version

Homebrew verifies the release archive's SHA256 checksum. Go is not required. Use Homebrew without sudo, and do not use the shell installer to update or remove a Homebrew-managed executable. If you already use an installer-managed system service, stop it before starting a Homebrew service; both use the same default port.

Before the first start, create the user configuration. Skip init if you already have one; it refuses to overwrite an existing configuration unless --force is used:

oci-mirror-proxy init
brew services start runui/oci-mirror-proxy/oci-mirror-proxy
oci-mirror-proxy status
oci-mirror-proxy remote update

The service runs as your current user, using the normal per-user configuration and administration socket. On macOS it starts at login; on Linux it uses a systemd user service. Without a service, run oci-mirror-proxy serve in the foreground. Logs are written to $(brew --prefix)/var/log/oci-mirror-proxy.log. remote update adds the default mirror catalog; use remote update --all on later updates to refresh every configured catalog while preserving its region selection.

Installing or starting the Homebrew service does not change Docker settings. Once the service is running, follow automatic Docker integration. On macOS, run these commands as the logged-in Docker Desktop user, without sudo:

oci-mirror-proxy dockerd plan
oci-mirror-proxy dockerd apply
oci-mirror-proxy doctor

If a Docker restart is pending, restart it when convenient. The explicit dockerd apply --restart option restarts Docker Desktop and interrupts running containers. See macOS installation for details.

Update and restart an existing Homebrew service:

brew update
brew upgrade runui/oci-mirror-proxy/oci-mirror-proxy
brew services restart runui/oci-mirror-proxy/oci-mirror-proxy

If Docker was configured to use the proxy, revert that integration while the service is still running, following the platform-specific Docker integration instructions, and activate the restored Docker settings before stopping the proxy. On macOS:

oci-mirror-proxy dockerd revert --restart
brew services stop runui/oci-mirror-proxy/oci-mirror-proxy
brew uninstall runui/oci-mirror-proxy/oci-mirror-proxy
brew untap runui/oci-mirror-proxy

--restart interrupts running containers. Skip the revert step if Docker was never connected to the proxy. Homebrew removal preserves user configuration, caches, and logs, and does not revert Docker settings automatically.

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.