Skip to main content

​
Run with Docker

The quickest way to run Proxy Hopper is with the pre-built Docker image: 
docker pull ghcr.io/cams-data/proxy-hopper:latest
For the Redis backend (multi-instance HA deployments): 
docker pull ghcr.io/cams-data/proxy-hopper:latest-redis
PyPI packages are not yet published. Docker is the recommended installation method. See Deployment for full Docker and Compose examples.

​
Write a config file

Create a config.yaml. The minimal config needs at least one target: 
targets:
  - name: general
    regex: '.*'
    ipList:
      - "10.0.0.1:3128"
      - "10.0.0.2:3128"
      - "10.0.0.3:3128"
    minRequestInterval: 1s
    maxQueueWait: 30s
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 2m
For a config with named proxy providers and shared IP pools: 
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 -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml \
  -p 8080:8080 \
  ghcr.io/cams-data/proxy-hopper:latest

​
Send a request

curl --proxy http://localhost:8080 https://example.com

​
Validate a config file

docker run -v $(pwd)/config.yaml:/etc/proxy-hopper/config.yaml \
  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

Integration modes

Learn the differences between HTTP proxy, CONNECT tunnel, and forwarding mode.

Config reference

Full reference for all configuration fields.