MirrorProxy
English | 简体中文
Official sources unreachable and public mirrors unreliable? Deploy
MirrorProxy—one self-hosted gateway for every source your builds depend on.
In restricted networks, official sources are often unreachable or too slow for
normal use. Even after finding a public mirror, it may be inaccessible, unstable,
or gone without warning—and every tool has a different way to change sources.
Developers keep switching configurations while CI builds can stall at any time.
The real cost is not just download time, but the time of the entire team.
Instead of continually searching for and maintaining somebody else's mirrors,
deploy your own MirrorProxy on a server with reliable upstream connectivity. It
brings GitHub, container registries, language packages, developer toolchains,
and operating-system repositories behind your domain: one project, one console,
and one stable gateway for the mainstream software sources used every day.
MirrorProxy fetches and caches content on demand, so it does not require a full
copy of every repository. When one upstream becomes unavailable, it can switch
to another automatically. Individuals can stop hunting, benchmarking, and
reconfiguring mirrors; teams also gain consistent source settings, access
control, quotas, health monitoring, and traffic reporting—turning a patchwork of
public mirrors into infrastructure they truly control.
What you gain by deploying MirrorProxy
- Stop hunting for public mirrors: proxy code hosts, containers, language
packages, toolchains, and operating-system repositories with one project
instead of collecting mirror URLs or deploying a service for every ecosystem.
- Stop benchmarking and switching by hand: configure multiple upstreams for
one source, fail over on timeouts, rate limits, and outages, and continuously
monitor endpoint health.
- Fewer failures and faster builds: run MirrorProxy where upstream access is
reliable, point workstations and CI at your own stable domain, and reuse cached
dependencies instead of repeating slow cross-border downloads.
- Consistent configuration on every machine: use the Windows, macOS, and
Linux client to inspect, switch, and restore sources without relearning each
package manager's configuration on every workstation or build host.
- A mirror you can safely share: assign monthly quotas and allowed sources to
users or teams, then combine rate limits, private user endpoints, and IP/CIDR
rules to prevent anonymous abuse and surprise bandwidth bills.
- Operations you can actually see: inspect traffic, trends, visitor regions,
and the health of every source; receive email or webhook alerts before quotas
run out or upstream failures become prolonged outages.
- Ownership of your data: keep accounts, policies, and statistics locally,
including fully offline IP geolocation that never sends visitor addresses to
a third-party lookup service.
- A path from personal service to team platform: start quickly with public
access and sensible defaults, then enable accounts, invitations, OAuth/OIDC,
team quotas, auditing, Prometheus, and automatic HTTPS as needs grow.
Live demo: https://sina.dev · Quick start · Latest release
Supported sources
MirrorProxy includes around 30 proxy adapter types and supports additional
administrator-defined static operating-system repositories:
| Category | Supported sources and ecosystems |
|---|
| Code and release assets | GitHub, GitHub Raw, read-only Git smart HTTP clone |
| Containers and OCI | Docker Hub, GitHub Container Registry, GitLab Container Registry, Quay, Kubernetes Registry, GCR, Microsoft MCR, Elastic Registry, NVIDIA NVCR, Oracle Container Registry, Homebrew OCI |
| JavaScript / Node.js | npm, NVM, Bun through the npm protocol |
| Python | PyPI / pip, Poetry, uv, PDM, Anaconda |
| AI models / datasets | Hugging Face public HTTP downloads (no server cache; set HF_HUB_DISABLE_XET=1). |
| Rust / Go | crates.io / Cargo, Rustup, Go Modules |
| JVM / .NET | Maven Central, Clojars, NuGet |
| Other language ecosystems | Composer, RubyGems, CPAN, CRAN, Hackage, Julia, LuaRocks, CocoaPods, Pub, OPAM |
| Developer tools and application sources | Homebrew, WinGet, TeX Live, ELPA, Nix, GNU Guix, Flatpak |
| Linux / BSD / operating-system sources | Debian, Ubuntu, Fedora, Arch Linux, Alpine, openSUSE, Void Linux, Gentoo, FreeBSD, Kali, Rocky Linux, AlmaLinux, Manjaro, Raspberry Pi OS, Armbian, openEuler, Anolis OS, Deepin, Linux Mint, Solus, Trisquel, Linux Lite, NetBSD, OpenBSD |
| Specialized systems and tool sources | OpenWrt, Termux, MSYS2, ROS, and administrator-defined static repositories |
Capabilities
- Mirror acceleration: on-demand proxying, bounded disk caching, and HTTP
conditional revalidation without the storage cost of a full mirror.
- Resilient upstreams: multiple endpoints per source, ordered or adaptive
selection, automatic failover, circuit recovery, and scheduled health checks.
- Unified source management: enable and configure built-in sources or add
custom static OS repositories in the web console; safely switch and roll back
local settings with the Windows, macOS, and Linux client.
- AI Agent integration: configure instance-bound Skills and native MCP for
Codex, Claude Code, Cursor, Gemini CLI and OpenCode; export activation files
for VS Code/Copilot, TRAE, WorkBuddy and dsh. Discover live mirror capabilities, generate
configuration commands and use separately authorized download tools.
- Controlled custom downloads: fetch public HTTPS files outside the source
catalog. Disabled by default, with user/group grants, download-only tokens,
quotas, domain statistics and blocking, and CLI/MCP access.
- User and team operations: invitations, email login, OAuth/OIDC,
billing groups/teams, global-team-user monthly quotas, and per-team source
restrictions.
- Secure access: rate limiting, IP/CIDR allow and deny rules, private user
subdomains, private-upstream credentials, trusted proxies, administrator roles,
passkeys, session revocation, and audit logs.
- Traffic and health insight: usage trends, offline country and regional
GeoIP reports, source health, Prometheus metrics, structured logs, optional
OTLP tracing, and quota/source-failure alerts.
- Flexible network access: a shared outbound HTTP/SOCKS5 proxy, enterprise
CA certificates, and credentials for private npm, OCI, and other upstreams.
- Simple, reliable deployment: Docker Compose, Linux release archives, and
systemd installation; use an existing Caddy/Nginx/Traefik proxy or automate
HTTPS certificates through ACME HTTP-01/DNS-01.
Deploy the server
Docker Compose
Download the included compose.yaml, set an administrator password,
and start the service. The named volume keeps the database, cache, and GeoIP data
across container upgrades.
MIRRORPROXY_ADMIN_PASSWORD='choose-a-strong-password' docker compose up -d
The console is available at http://localhost:3000/admin when running locally.
Server archive
Download the server archive for your Linux architecture from the
latest release, verify its
SHA-256 file, extract it into a durable directory, then copy and adapt the
configuration before starting the server:
cp config.example.toml config.toml
./mirrorproxy-server --config ./config.toml serve
For systemd, TLS, reverse proxies, persistent storage, and production settings,
see Deployment.
Install the client
One-command installer
# macOS / Linux
curl -fsSL https://sina.dev/https://raw.githubusercontent.com/inbjo/MirrorProxy/main/scripts/install.sh | sh -s -- --mirror https://sina.dev
# Windows PowerShell
& ([scriptblock]::Create((irm 'https://sina.dev/https://raw.githubusercontent.com/inbjo/MirrorProxy/main/scripts/install.ps1'))) -Mirror 'https://sina.dev'
The scripts install only the standalone client, select the current platform
release automatically, and verify its SHA-256 checksum. Run mirrorproxy --version
after installation to confirm it is available.
Package managers
# macOS / Linux
brew install inbjo/tap/mirrorproxy
# Windows
winget install --id Inbjo.MirrorProxy --exact
# Debian / Ubuntu: add the signed MirrorProxy APT repository once
curl -fsSL https://raw.githubusercontent.com/inbjo/MirrorProxy/apt/mirrorproxy-archive-keyring.gpg \
| sudo tee /usr/share/keyrings/mirrorproxy-archive-keyring.gpg >/dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/mirrorproxy-archive-keyring.gpg] https://raw.githubusercontent.com/inbjo/MirrorProxy/apt stable main" \
| sudo tee /etc/apt/sources.list.d/mirrorproxy.list >/dev/null
sudo apt update
sudo apt install mirrorproxy
See Client distribution for details.
The Linux client also provides mirrorproxy systems and a unified native source
migration for 28 distribution profiles. See the OS/version matrix and rollback
guide.
AI agents: Skill and MCP
Connect your coding agents to your instance using direct configuration or client-specific exports. The Skill provides usage
instructions, while native MCP tools discover live sources, enabled adapters and
access policy instead of relying on hard-coded mirror URLs.
The setup workflow requires client v1.7.0 or newer; the homepage installer
can upgrade an older client before configuration. Additional Agent adapters require
a client built from this revision or a later release; the published v1.7.0 client
only offers Codex, Claude Code and Cursor.
On the live demo or your own instance, open Set up your AI
agents and copy the command for your platform. It installs the client and
starts the Skill + MCP wizard. The wizard asks which Agents and scope to use,
strongly recommends the current user's global scope by default, preserves
existing configuration and provides backups and rollback.
With the client already installed, run this with your instance address:
mirrorproxy setup --base-url https://mirror.example.com
Restart your Agent afterward and retain its normal workspace trust and MCP
approval checks. The native stdio entry point is
mirrorproxy mcp --base-url https://mirror.example.com. To install only the Skill,
run npx skills add inbjo/MirrorProxy --skill mirrorproxy; this does not install
the native client or configure its MCP connection. See
Agent Skill and MCP for details.
Controlled custom downloads
Use the instance to download public HTTPS artifacts such as source archives and
installers beyond the supported repository catalog. This channel is disabled
by default: an administrator enables it and grants access to a user or group,
then the user creates a download-only token in their account. Controls include
file-size, traffic, concurrency and rate limits, domain statistics, blocking and
active-download cancellation.
After configuring credentials locally, download to a new file with the CLI;
successful results include its size and SHA-256:
mirrorproxy download --base-url https://mirror.example.com fetch https://example.org/source.tar.xz --output source.tar.xz
The same MCP connection exposes check_download and download_file. File bodies
are written locally rather than entering model context. Keep credentials local,
never send them to an Agent or place them in a Skill; download tools require
separate permission and consume quota. This is not an unrestricted forward proxy
and does not support private-network targets, uploads or forwarding client
credentials. See Custom downloads for setup,
credential storage and verification.
Documentation
Project links