proxyguard

capabilities

everything you need.
nothing you don't.

↺

proxy rotation

automatically distributes requests across your pool of upstream proxies with smart load balancing based on latency and health.

⚿

circuit breaker

dead proxies get pulled from the pool after consecutive failures. they come back when health checks pass again.

🔒

hmac-sha256 auth

secure your gateway with time-based hmac signatures. no one touches your proxies without a valid token.

📌

sticky sessions

pin a client to a specific proxy for a configurable duration. perfect for session-based scraping workflows.

⚡

hot reload

update your proxy list without restarting. just edit the file and proxyguard picks up changes on the next health check cycle.

📈

prometheus metrics

built-in /metrics endpoint with connection counts, bytes transferred, upstream failures, and more. plug into grafana.

architecture

how it works

client sends CONNECT

your scraper sends a standard HTTP CONNECT request to proxyguard with an optional hmac auth header.

auth & proxy selection

the request is authenticated, then the best upstream proxy is selected based on health, latency, and sticky session rules.

tunnel established

a bidirectional tunnel is opened between the client and the upstream proxy. data flows both ways at full speed with tcp_nodelay.

retry on failure

if an upstream fails, proxyguard retries with a different proxy up to 3 times. the failed proxy's circuit breaker is updated.

quickstart

up and running
in 30 seconds

docker-compose.yml YAML

services:
  proxyguard:
    build: .
    ports:
      - "8888:8888"  # proxy
      - "9090:9090"  # dashboard + metrics
    volumes:
      - ./proxies.txt:/app/proxies.txt
    environment:
      - PG_SECRET=your-secret-here
      - PG_STICKY_TTL=300

authenticate & connect Python

import time, hmac, hashlib, requests

def get_proxy(secret, client_id):
    ts = str(int(time.time()))
    sig = hmac.new(
        secret.encode(),
        f"{client_id}{ts}".encode(),
        hashlib.sha256
    ).hexdigest()
    return f"http://{client_id}:{ts}:{sig}@localhost:8888"

proxies = {"https": get_proxy("your-secret", "bot-1")}
requests.get("https://httpbin.org/ip", proxies=proxies)

configuration

env vars. that's it.

variable	default	what it does
`PG_SECRET`	dev-secret...	hmac signing secret
`PG_ENABLE_AUTH`	true	toggle hmac authentication
`PG_PROXY_FILE`	proxies.txt	path to proxy list file
`PG_STICKY_TTL`	0	session pin duration (seconds)
`PROXY_PORT`	8888	incoming proxy connections
`METRICS_PORT`	9090	dashboard & prometheus endpoint
`PG_CONNECT_TIMEOUT`	10	upstream connect timeout (seconds)
`PG_HEALTH_CHECK_INTERVAL`	60	seconds between health checks

everything you need.nothing you don't.