Quick Start

Run with Docker

docker pull ghcr.io/cams-data/proxy-hopper:latest

For the Redis backend (multi-instance HA):

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

PyPI packages are not yet published. Docker is the recommended installation method. See Simple Docker Deployment for full examples.

Write a config file

Create a config.yaml. Every config follows a three-tier model:

proxyProviders — your proxy supplier’s IPs and credentials
ipPools — named collections that draw IPs from one or more providers
targets — URL routing rules that reference a pool

proxyProviders:
  - name: my-provider
    auth:
      type: basic
      username: user
      password: secret
    ipList:
      - "10.0.0.1:3128"
      - "10.0.0.2:3128"
      - "10.0.0.3:3128"
    regionTag: US-East

ipPools:
  - name: my-pool
    ipRequests:
      - provider: my-provider
        count: 3

targets:
  - name: general
    regex: '.*'
    ipPool: my-pool
    minRequestInterval: 1s
    maxQueueWait: 30s
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 2m

Start the server

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

Send a request

Add X-Proxy-Hopper-Target to your request headers with the destination URL and send it to Proxy Hopper:

curl -H "X-Proxy-Hopper-Target: https://httpbin.org" \
     http://localhost:8080/get

import requests

session = requests.Session()
session.headers["X-Proxy-Hopper-Target"] = "https://httpbin.org"

resp = session.get("http://localhost:8080/get")
print(resp.json())

import httpx

with httpx.Client(
    base_url="http://localhost:8080",
    headers={"X-Proxy-Hopper-Target": "https://httpbin.org"},
) as client:
    resp = client.get("/get")
    print(resp.json())

import aiohttp

async with aiohttp.ClientSession(
    headers={"X-Proxy-Hopper-Target": "https://httpbin.org"}
) as session:
    async with session.get("http://localhost:8080/get") as resp:
        print(await resp.json())

Validate a config file

Check your config file without starting the server:

docker run --rm \
  -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml:ro \
  ghcr.io/cams-data/proxy-hopper:latest \
  proxy-hopper validate --config /etc/proxy-hopper/config.yaml
# Config OK — 1 target(s) defined.
#   'general': 3 IP(s), regex='.*'
# Server defaults: host=0.0.0.0, port=8080, backend=memory

Next steps

Sending Requests

All control headers and request behaviour.

Config Reference

Full reference for all configuration fields.

Docker deployment

Production-ready Docker and Compose setups.

Authentication

Secure Proxy Hopper with API keys or SSO.

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Run with Docker

Write a config file

Start the server

Send a request

Validate a config file

Next steps

Sending Requests

Config Reference

Docker deployment

Authentication

​Run with Docker

​Write a config file

​Start the server

​Send a request

​Validate a config file

​Next steps

Sending Requests

Config Reference

Docker deployment

Authentication

Run with Docker

Write a config file

Start the server

Send a request

Validate a config file

Next steps