hapheus/torproxy repository overview

⁠torproxy

A lightweight, secure, and production-ready Docker container combining Tor, Privoxy (HTTP/HTTPS proxy), SOCKS5, and a local REST control API.

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

⁠Key Features

• HTTP/HTTPS Proxy (Port 8118): Powered by Privoxy, automatically resolving DNS lookups through Tor exit relays to prevent DNS leaks.
• SOCKS5 Proxy (Port 9050): Standard Tor SOCKS5 interface supporting remote hostname resolution (socks5h://).
• REST Control API (Port 8080): Inspect circuit status, trigger circuit rotation (/reconnect), query health diagnostics, and pull Prometheus metrics.
• Fail-Closed Security: Privoxy strictly routes to Tor SOCKS5; if Tor circuits drop, proxy requests fail immediately (500/503) rather than leaking to clearnet.
• Authenticated Tor Control: Local Tor ControlPort is secured using ephemeral 32-byte filesystem cookie authentication.
• Non-Root Execution: Runs under a dedicated, unprivileged system user (torproxy), never as root.
• Multi-Architecture: Built natively for linux/amd64, linux/arm64, and linux/arm/v7.
• Country-Specific Exit Nodes: Route traffic through exit relays in specific countries (e.g. TORPROXY_COUNTRY=DE or DE,AT) backed by tor-geoipdb.
• Zero Breaking Changes: Guaranteed backward compatibility across minor releases.

⁠Quick Start

⁠Option 1: Docker Run

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

⁠Option 2: Docker Compose

services:
  torproxy:
    image: hapheus/torproxy:latest
    container_name: torproxy
    restart: unless-stopped
    ports:
      - "127.0.0.1:8118:8118"
      - "127.0.0.1:9050:9050"
      - "127.0.0.1:8080:8080"

⁠Option 3: Country-Specific Exit Proxy (e.g. Germany or Austria)

docker run -d \
  --name torproxy \
  --restart unless-stopped \
  -e TORPROXY_COUNTRY=DE \
  -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 bootstrap, then test:

# 1. Check REST API status
curl -s http://127.0.0.1:8080/status | jq .

# 2. Test HTTP proxy via Privoxy
curl --proxy http://127.0.0.1:8118 https://check.torproject.org/api/ip

# 3. Test SOCKS5 proxy (using remote DNS to prevent leaks)
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip

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

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

⁠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⁠.