A Multi-user AIO Proxy Manager

---

Magpie is a self-hosted proxy manager that turns messy proxy lists into something you can actually use:

• it scrapes proxies from public sources
• continuously checks which ones are alive
• filters out dead/bad entries
• assigns each proxy a reputation score (uptime/latency/anonymity)
• lets you create your own rotating proxy endpoints from the healthy pool

all via a web dashboard.

More Screenshots

Features

• Multi-user
• Auto-scraping
• Proxy Checking / Health checks
• Reputation & filters
• Rotating proxy endpoints
• Dashboard + API
• Application protocols support (HTTP, HTTPS, SOCKS4, SOCKS5)
• Transport protocols support (TCP, QUIC/HTTP3)

Quick Start

1. Install Prerequisites:

   • Docker Desktop (or Docker Engine + Compose)

2. One-command install (recommended)

   macOS/Linux:

   curl -fsSL https://raw.githubusercontent.com/Kuucheen/magpie/refs/heads/master/scripts/install.sh | bash

   If you see a Docker socket permission error on Linux, the installer will try to use sudo for Docker commands (you may be prompted).
   Alternative fix: sudo usermod -aG docker "$USER" (then log out/in, or run newgrp docker).
   Note: sudo curl ... | bash still runs bash as your user. Try curl ... | sudo bash instead.

   Windows (PowerShell):

   iwr -useb https://raw.githubusercontent.com/Kuucheen/magpie/refs/heads/master/scripts/install.ps1 | iex

   This creates a magpie/ folder with a docker-compose.yml and .env, then starts the stack.

3. Required secrets – Magpie requires:

   • PROXY_ENCRYPTION_KEY to encrypt stored proxy secrets (keep it stable between restarts/updates)

Warning

PROXY_ENCRYPTION_KEY locks all stored secrets (proxy auth, passwords, and ip addresses).
If you start the backend (or update to a new version) with a different key than the one used before, decryption fails and previously added proxies will not display or validate.
Fix: start the backend again using the previous key and everything works like before.
Only rotate on purpose: if you need a new key, export your proxies first.

4. If you don't want to use the installer

   Requires Git

   git clone https://github.com/Kuucheen/magpie.git
   cd magpie
   cp .env.example .env
   # edit .env and set PROXY_ENCRYPTION_KEY
   # optional: override JWT_SECRET
   # optional: override DB_USERNAME/DB_PASSWORD/DB_NAME
   # optional: configure MAIL_FROM_ADDRESS/SMTP_HOST for email delivery
   docker compose up -d

   docker-compose.yml is local/dev oriented. For production deployments, use hardened manifests and secure DB/Redis/TLS settings.

5. Dive in

   • UI: http://localhost:5050

   • API: http://localhost:5656/api

   • Docs: https://magpie.tools/docs/

     The first user who registers becomes admin automatically.

For geo lookups, create a MaxMind GeoLite2 account and generate a License Key. Enter it in the dashboard (Admin → Other) to enable automatic database downloads and updates.

Updating

Use the helper scripts that match how you installed Magpie.

• If you used the one-command installer:

  • Refreshes docker-compose.yml, updates image references, pulls the latest images, and restarts the stack.
  • macOS/Linux:

    curl -fsSL https://raw.githubusercontent.com/Kuucheen/magpie/refs/heads/master/scripts/update.sh | bash

    If you see a Docker socket permission error on Linux, the updater will try to use sudo for Docker commands (you may be prompted).
  • Windows (PowerShell):

    iwr -useb https://raw.githubusercontent.com/Kuucheen/magpie/refs/heads/master/scripts/update.ps1 | iex

• If you cloned the project:

  • Pulls the latest repo changes and rebuilds the frontend and backend containers.
  • macOS/Linux:

    ./scripts/update-frontend-backend.sh

  • Windows (Command Prompt):

    scripts\update-frontend-backend.bat

    Double-click the file or run it from the repo root.

Local Development

• Prerequisites:
  • Go 1.26.x
  • Node.js 20.19+ or 22.12+
  • npm
  • Docker
• Services: docker compose up -d postgres redis
• Backend: cd backend && go run ./cmd/magpie
• Frontend: cd frontend && npm install && npm run start
• Docs site: cd website/docs && npm install && npm run start

Optional email delivery env vars for the backend:

• MAIL_FROM_ADDRESS: sender address used in outbound email, for example no-reply@example.com
• MAIL_FROM_NAME: optional display name, for example Magpie
• PUBLIC_APP_URL: public frontend base URL used in password reset links, for example https://magpie.example.com
• SMTP_HOST: SMTP server host
• SMTP_PORT: SMTP server port, defaults to 587
• SMTP_USERNAME and SMTP_PASSWORD: optional SMTP auth credentials; if one is set, both must be set
• PASSWORD_RESET_TOKEN_TTL_MINUTES: optional reset-link lifetime, defaults to 30

Attributions & External Sources

• AbuseIPDB — logo used with permission when linking to their site.

Community

• Website: https://magpie.tools
• Docs: https://magpie.tools/docs/
• Discord: https://discord.gg/7FWAGXzhkC
• Issues & feature requests: open them on GitHub.

License

Magpie ships under the GNU Affero General Public License v3.0. See LICENSE for the full text. Contributions are more than welcome.