ronxldwilson/torousel repository overview

⁠torousel

A lightweight Docker image that provides a single HTTP proxy endpoint backed by many Tor exit IPs, designed for web crawling and scraping.

A single Tor process handles all circuits using SOCKS5 authentication-based isolation (IsolateSOCKSAuth). A Go-based HTTP proxy sits in front, round-robin routing each request through a different circuit credential — no HAProxy, no Privoxy, no per-instance processes.

⁠Usage

Supported platforms:

• linux/amd64
• linux/arm64

⁠Simple case

docker run --rm -it -p 3128:3128 ronxldwilson/torousel

At the host, 127.0.0.1:3128 is the HTTP/HTTPS proxy address.

⁠Advanced

docker run --rm -it -p 3128:3128 -p 4444:4444 -e "TOR_INSTANCES=500" -e "TOR_REBUILD_INTERVAL=3600" ronxldwilson/torousel

⁠Port 4444/TCP

Port 4444/TCP exposes a JSON stats endpoint. With docker run -p 4444:4444, stats are available at http://127.0.0.1:4444⁠ showing the number of instances, total requests, and errors.

⁠TOR_INSTANCES

Number of virtual Tor circuits (each with a unique SOCKS5 credential for circuit isolation). The default is 500, and the valid range is 1-500.

Note: the Tor network has ~1,000-1,500 exit nodes at any time. With 500 instances, expect ~300 unique exit IPs since multiple circuits can share the same exit relay.

⁠TOR_REBUILD_INTERVAL

Each Tor circuit rotates every 30 seconds (NewCircuitPeriod) and circuits are considered dirty after 5 minutes (MaxCircuitDirtiness). The controller periodically checks exit IPs at this interval (default: 1800 seconds, minimum: 600 seconds).

⁠Test the proxy

while :; do curl -sx localhost:3128 http://checkip.amazonaws.com; echo ""; sleep 2; done

⁠Architecture

Client → :3128 (Go HTTP proxy) → SOCKS5 auth (i0:x, i1:x, ... iN:x) → single Tor process → exit relays

Each request is assigned a round-robin credential (i0 through i{N-1}). Tor's IsolateSOCKSAuth ensures each credential gets its own circuit, providing IP diversity without spawning multiple processes.

⁠Benchmark (500 instances, 500 concurrent requests)

⁠Credit

Originally forked from zhaow-de/rotating-tor-http-proxy⁠, which used multiple Privoxy-Tor pairs behind HAProxy. This version replaces that stack with a single Tor process and a Go HTTP proxy for significantly lower resource usage and higher scalability.

⁠Bill-of-Material

• Alpine Linux (edge)
• Arti (Rust-based Tor client)
• Go (build only)
• bash, curl (runtime utilities)