Deep dives and operational runbooks that extend the quickstart. Each guide mirrors an integration test so you can adopt changes with confidence.

Guides

Choosing a Guide

Not sure where to start?

• Building a scraper or crawler? Start with Async Client Guide and Advanced Rotation Strategies

• Deploying to production? Read Retry & Failover Guide then Deployment Security & Reverse Proxy Configuration

• Automating proxy management? See CLI Reference and Automation & CI/CD Runbook

• Integrating with AI tools? Jump to MCP Server Guide

Client & Concurrency

Async Client

Use AsyncProxyWhirl for high-concurrency workloads with asyncio.

• When to use async vs sync

• Initialization patterns – basic, with proxies, custom strategy

• Connection pooling & context managers

• Error handling & proxy ejection

asyncio httpx

Async Client Guide

Advanced Strategies

Performance-based, session-persistent, geo-targeted, and composite strategies.

• Performance-based strategy – EMA scoring, warmup periods

• Session persistence – sticky sessions, TTL cleanup

• Geo-targeted routing – region-aware filtering

• Composite pipelines – filter + select chains

strategies advanced

Advanced Rotation Strategies

Resilience & Caching

Caching

Multi-tier cache architecture (L1/L2/L3) with encryption support.

• Architecture overview – L1 in-memory, L2 encrypted disk, L3 SQLite

• Tier promotion & demotion

• CacheManager API – get, set, invalidate, warmup

• CacheConfig options – TTL, max size, encryption keys

performance encryption

Caching Subsystem Guide

Retry & Failover

Circuit breakers, retry policies, and automatic proxy failover.

• Retry vs failover – same proxy vs different proxy

• RetryPolicy configuration – attempts, backoff, jitter

• Backoff strategies – exponential, linear, custom

• Circuit breaker patterns

resilience production

Retry & Failover Guide

Operations & Deployment

Deployment Security

Reverse proxy configuration, X-Forwarded-For security, and production hardening.

• X-Forwarded-For attack surface – spoofing defense

• Nginx configuration – rate limiting, trusted proxies

• Caddy configuration – automatic TLS

• HAProxy, Traefik, AWS ALB, GCP – cloud load balancers

security production

Deployment Security & Reverse Proxy Configuration

CLI Reference

Complete command-line interface documentation for all 12 commands.

• Global options – config path, verbosity, output format

• request command – GET/POST with proxy rotation

• pool command – list, add, remove, test proxies

• fetch, export, cleanup – manage proxy data

• tui dashboard – interactive terminal UI

CLI typer

CLI Reference

Automation & AI

Automation

CI/CD integration, pre-flight checks, and release automation.

• Pre-flight checks – lint, test, type-check gates

• Smoke tests – docs example validation

• Release automation – tag, build, publish

• CI stage pipeline

CI/CD GitHub Actions

Automation & CI/CD Runbook

MCP Server

Model Context Protocol server for AI assistant integration.

• Quick start – install, run, auto-load proxies

• Available actions – list, rotate, validate, stats

• Claude Desktop integration – stdio transport

• CLI options – transport, host, port, database path

AI MCP

MCP Server Guide

Troubleshooting

Troubleshooting

Diagnose and resolve common issues with error codes, debugging tips, and FAQ.

• Error codes reference – all ProxyWhirl error codes

• Common issues – proxies unhealthy, rate limiting, SSL errors

• Debugging tips – logging, metrics, health monitoring

• FAQ – custom sources, strategies, persistence, async

troubleshooting debugging

Troubleshooting Guide

---

Related: Getting Started for installation | Reference for API specs | Project for contributing