hapheus/torproxy repository overview

⁠torproxy

Production-grade, leak-proof Tor HTTP and SOCKS5 proxy packaged for Docker. Route entire container networks with zero application changes, connect AI coding assistants (Claude Desktop, Cursor) via built-in MCP, and rotate circuits dynamically via REST.

Source repository: https://github.com/hapheus/torproxy⁠

⁠⚡ Core Value & Features

• 🛡️ Zero Clearnet Leaks: True fail-closed protection. If Tor disconnects, Privoxy and the netfilter kill-switch immediately drop traffic (HTTP 503) — your real IP is never exposed.
• 🚀 Transparent Tor Gateway: Attach any container via network_mode: "service:torproxy" to tunnel all outbound TCP & DNS through Tor automatically — zero app proxy flags or code changes.
• 🤖 Native AI Agent MCP Server: Built-in Model Context Protocol server on port 2501 (SSE) and via Stdio (torproxy mcp) for seamless Claude Desktop, Cursor, and Antigravity integration.
• 🔄 Dynamic Circuit Rotation: Rotate Tor identities (SIGNAL NEWNYM) or switch exit countries on the fly without container restarts via the REST API (:8080).
• 🔒 Hardened Non-Root Security: Daemons run strictly under an unprivileged user (torproxy), with authenticated loopback Tor ControlPort.
• 🌍 Country-Specific Routing: Select Tor exit relays by country (e.g. TORPROXY_COUNTRY=DE or DE,AT) backed by built-in tor-geoipdb.
• 📦 Multi-Architecture: Built natively for linux/amd64, linux/arm64, and linux/arm/v7.

⁠🚀 Quick Start

⁠Recommended: Docker Compose

Create a docker-compose.yml:

services:
  torproxy:
    image: hapheus/torproxy:latest
    container_name: torproxy
    restart: unless-stopped
    ports:
      - "127.0.0.1:8118:8118"   # HTTP/HTTPS proxy (Privoxy)
      - "127.0.0.1:9050:9050"   # SOCKS5 proxy (Tor)
      - "127.0.0.1:8080:8080"   # REST API & Health status

Launch the proxy:

docker compose up -d

⁠Alternative: Docker Run (Single Command)

docker run -d \
  --name torproxy \
  --restart unless-stopped \
  -p 127.0.0.1:8118:8118 \
  -p 127.0.0.1:9050:9050 \
  -p 127.0.0.1:8080:8080 \
  hapheus/torproxy:latest

⁠🧪 Verifying Tor Connectivity

Wait a few seconds for Tor to finish bootstrapping, then test:

# 1. Test HTTP proxy via Privoxy (port 8118) — returns {"IsTor": true, "IP": "..."}
curl --proxy http://127.0.0.1:8118 https://check.torproject.org/api/ip

# 2. Test SOCKS5 proxy with remote DNS resolution (port 9050)
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip

# 3. Check live connection status via REST API (port 8080)
curl -s http://127.0.0.1:8080/status | jq .

# 4. Request a new Tor identity / circuit on demand
curl -X POST http://127.0.0.1:8080/reconnect

# 5. Dynamically switch exit country without restarting
curl -X POST "http://127.0.0.1:8080/reconnect?country=DE"

⁠🎯 When to Use torproxy

• ✅ Ideal For:
  • Automated web scraping, data mining, and distributed crawling without IP rate limits.
  • Empowering AI coding assistants (Claude Desktop, Cursor) with native .onion and web fetch tools via MCP.
  • Zero-code privacy: Tunnel existing containers with network_mode: "service:torproxy".
  • Geolocation testing across exit countries (TORPROXY_COUNTRY=DE,AT,US).
• ⚠️ Not Designed For:
  • High-bandwidth 4K video streaming or latency-critical online gaming.
  • Bypassing strict anti-bot protections (Cloudflare, Akamai) that systematically block public Tor exit relays.

⁠🌟 Popular Modes & Use Cases

⁠1. Transparent Gateway (Zero-Config Routing for Any Container)

Route another container's entire network traffic (TCP + DNS) through Tor without setting proxy flags:

services:
  torproxy:
    image: hapheus/torproxy:latest
    pull_policy: always
    cap_add:
      - NET_ADMIN
    environment:
      TORPROXY_GATEWAY_MODE: "true"
    restart: unless-stopped

  # Any container attached to torproxy's network stack is automatically anonymized:
  scraper:
    image: curlimages/curl:latest
    network_mode: "service:torproxy"
    depends_on:
      torproxy:
        condition: service_healthy
    command: ["-s", "https://check.torproject.org/api/ip"]

⁠2. AI Coding Assistants (Model Context Protocol / MCP)

Connect Claude Desktop directly via Docker Stdio without exposing host ports:

{
  "mcpServers": {
    "torproxy": {
      "command": "docker",
      "args": ["exec", "-i", "torproxy", "torproxy", "mcp"]
    }
  }
}

Or connect Cursor / Antigravity via HTTP/SSE (http://127.0.0.1:2501/sse).

⁠3. Country-Specific Exit Proxy

Route traffic exclusively through specific countries:

docker run -d \
  --name torproxy \
  --restart unless-stopped \
  -e TORPROXY_COUNTRY=DE,AT \
  -p 127.0.0.1:8118:8118 \
  -p 127.0.0.1:9050:9050 \
  -p 127.0.0.1:8080:8080 \
  hapheus/torproxy:latest

⁠REST API Reference

The management API listens on port 8080 (HTTP):

⁠Configuration & Environment Variables

⁠Production Hardening

For maximum security in production, run with a read-only root filesystem and drop all Linux capabilities:

services:
  torproxy:
    image: hapheus/torproxy:latest
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=32M
      - /run:rw,noexec,nosuid,size=16M
      - /var/lib/tor:rw,noexec,nosuid,size=64M
      - /var/log/privoxy:rw,noexec,nosuid,size=16M
    ports:
      - "127.0.0.1:8118:8118"
      - "127.0.0.1:9050:9050"
      - "127.0.0.1:8080:8080"

⁠License

This project is licensed under the MIT License⁠.