Skip to main content

Proxy Hopper

A rotating HTTP/HTTPS proxy server that routes outbound requests through a pool of external proxy IP addresses — with automatic retries, failure tracking, and IP quarantine.

●Open Source●Self Hostable●Docker Ready●No cloud required

The problem

When your application needs to make outbound HTTP requests at scale — scraping, API polling, data collection — you run into rate limits, IP blocks, and connection failures. Managing a pool of proxy IPs manually means writing retry logic, tracking which IPs are healthy, rotating through them fairly, and handling failures gracefully. Every project reinvents this wheel.

Proxy Hopper solves it once, as a standalone service.

Proxy Hopper architecture

Point your HTTP client at Proxy Hopper as its proxy. Proxy Hopper handles everything else.

How it works

1

Configure your proxy providers and targets

Define your external proxy IPs — grouped by provider with credentials and region tags. Set targets as URL regex patterns, each with its own pool, rate limit, and retry policy.
2

Point your HTTP client at Proxy Hopper

Use standard HTTP proxy settings, HTTPS CONNECT tunnels, or forwarding mode. No changes to your application logic.
3

Proxy Hopper handles the rest

IP rotation, rate limiting between requests, automatic quarantine of failing IPs, retries on failure, and health probing in the background.

Key features

IP rotation

Each target maintains its own FIFO queue. IPs are held off the pool between requests to respect rate limits.

Automatic quarantine

IPs that accumulate failures are quarantined automatically and released back into rotation after a configurable timeout.

Per-target policies

Different targets can have different rate limits, retry counts, and quarantine thresholds — match the policy to the site.

Three integration modes

HTTP proxy, HTTPS CONNECT tunnel, and URL-forwarding — all using the same rotation and retry logic.

Redis HA

In-memory backend for single-instance deployments. Redis backend for multi-instance HA with shared pool state.

Prometheus metrics

Full observability — request rates, retry counts, queue depth, quarantine events, and per-IP probe status.

Three integration modes

Proxy Hopper supports three ways for clients to send requests. All three use the same IP rotation and retry logic.

ModeHow to useHTTPS retries
HTTP proxyhttp_proxy=http://proxy-hopper:8080Yes
CONNECT tunnelhttps_proxy=http://proxy-hopper:8080No — tunnel is opaque
URL forwardingX-Proxy-Hopper-Target headerYes — recommended for APIs
Use forwarding mode for HTTPS APIs where you need retry support. CONNECT tunnels are opaque byte relays — Proxy Hopper cannot retry a mid-flight failure once the TLS handshake is complete.

Get started

# config.yaml
targets:
  - name: general
    regex: '.*'
    ipList:
      - "10.0.0.1:3128"
      - "10.0.0.2:3128"
    minRequestInterval: 1s
    numRetries: 3

docker run -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml \
  ghcr.io/cams-data/proxy-hopper:latest

import requests
resp = requests.get(
    "https://example.com",
    proxies={"https": "http://localhost:8080"}
)

Full quick start

Step-by-step guide with providers, pools, and all three integration modes.

Docker images

Pre-built multi-arch images for amd64 and arm64.

Deployment options

Single container

In-memory backend. Zero external dependencies. Good for development and single-host deployments.

Docker Compose + Redis

Redis backend. Survives restarts. Scale to multiple replicas sharing a single IP pool.

Kubernetes

Full manifests — Deployment, HPA, Redis StatefulSet, Services. Scales automatically with traffic.

Free and open source. Forever.

Proxy Hopper is MIT licensed and built for self-hosting. No SaaS, no usage fees, no data leaving your infrastructure. Run it on a single container or scale it across a Kubernetes cluster — you own the deployment entirely.

Contributions, bug reports, and feature requests are welcome on GitHub.

# Memory backend (default)
docker pull ghcr.io/cams-data/proxy-hopper:latest

# Redis backend
docker pull ghcr.io/cams-data/proxy-hopper:latest-redis