🧅 torproxy

Quick Start · Model Context Protocol (MCP) · Transparent Gateway · Architecture · REST API · Configuration · Examples · Contributing

A minimal, secure, and reliable Tor HTTP and SOCKS5 proxy packaged for Docker. torproxy routes traffic through the Tor network with fail-closed protection, non-root execution, an authenticated Tor control interface, and a lightweight JSON REST API for circuit rotation, health monitoring, and dynamic exit node routing.

Architecture

Host Client / Dependent Containers
        │
        ├── HTTP Requests ────────► Privoxy (:8118)
        │                             │ (forward-socks5t)
        ├── SOCKS5 Requests ──────────┼───────────────► Tor Daemon (:9050)
        │                             │                   │
        └── REST Control API ─────► API Server (:8080)   │ (Cookie Auth)
                                      │                   │
                                      └─ ControlPort ─────┘ (:9051 loopback)
                                                          │
                                                          ▼
                                                  Tor Onion Network
                                                          ▼
                                                    Target Website

Related MCP server: tor-mcp

Quick Start

# 1. Start torproxy in the background
docker compose up -d

# 2. Test HTTP proxy (port 8118)
curl -v -x http://127.0.0.1:8118 https://check.torproject.org/api/ip

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

# 4. Check status via the local REST API
curl http://127.0.0.1:8080/status

# 5. Optional: Route exit traffic through a specific country (e.g. DE or AT)
TORPROXY_COUNTRY=DE docker compose up -d
# or multiple countries:
TORPROXY_COUNTRY=DE,AT docker compose up -d

# 6. Dynamically switch exit country on reconnect without container restart:
curl -X POST "http://127.0.0.1:8080/reconnect?country=DE"
# or with JSON payload:
curl -X POST http://127.0.0.1:8080/reconnect \
  -H "Content-Type: application/json" \
  -d '{"country": "AT", "strict_nodes": true}'

Security Note: In docker-compose.yml, all ports bind strictly to 127.0.0.1 by default. Neither the proxy listeners nor the management API require authentication; do not expose them to untrusted networks.

🚀 Transparent Tor Gateway

Route any existing Docker container's entire outbound TCP and DNS traffic automatically through Tor — without modifying your applications or adding proxy flags.

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

  # Attach any application container directly to torproxy's network namespace:
  my-app:
    image: curlimages/curl:latest
    network_mode: "service:torproxy"
    depends_on:
      torproxy:
        condition: service_healthy
    command: ["-s", "https://check.torproject.org/api/ip"]

Why use Transparent Gateway mode?

• Zero Application Changes: No need to configure HTTP_PROXY, ALL_PROXY, or browser arguments.

• Tor DNSPort (:9053): All DNS requests on port 53 (UDP & TCP) are automatically resolved via Tor to prevent DNS leaks.

• Fail-Closed Netfilter Kill Switch: All direct clearnet traffic is blocked. If Tor stops or disconnects, connections fail closed immediately.

• Process-Scoped WAN Bypass: Only the dedicated unprivileged tor user may reach the WAN (owner --uid-owner); the API, Privoxy, and attached app containers cannot bypass the kill switch.

• IPv6: Tor may bootstrap over IPv6 (its own exception); every other process remains blocked — no IPv6 clearnet leaks.

• UDP Protection: Unsupported non-DNS UDP traffic (e.g. QUIC/HTTP-3) is blocked with ICMP port-unreachable, ensuring fast fallback to TCP without hangs.

• See the ready-to-run Transparent Gateway Example for details.

🤖 Model Context Protocol (MCP)

torproxy includes a built-in, zero-dependency Model Context Protocol (MCP) server on port 2501 (SSE) and via Stdio (torproxy mcp), allowing AI agents (Claude Desktop, Cursor, Antigravity) to manage Tor circuits and execute anonymized web requests directly.

Claude Desktop Integration (claude_desktop_config.json)

Connect Claude Desktop to your running torproxy container via Stdio without exposing host ports:

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

Cursor & Antigravity Integration (.cursor/mcp.json)

Connect via HTTP/SSE:

{
  "mcpServers": {
    "torproxy": {
      "url": "http://127.0.0.1:2501/sse"
    }
  }
}

Or use the root-level .mcp.json manifest auto-detected by Cursor and cursor.directory on workspace open.

Smithery.ai Integration (smithery.yaml)

Install directly with zero configuration via Smithery.ai:

npx -y @smithery/cli install hapheus/torproxy --client claude

Key Tools Available to Agents

• torproxy_fetch: Zero-config fetch — execute HTTP/HTTPS or .onion requests strictly routed through Tor (no local curl or host proxy setup needed).

• torproxy_status: Retrieve live bootstrap progress, egress IP, and GeoIP metadata.

• torproxy_get_ip: Query the current verified Tor exit IP.

• torproxy_reconnect: Request a new Tor identity (SIGNAL NEWNYM), optionally changing exit country (country="DE").

• torproxy_health & torproxy_diagnostics: Automated operational health and circuit diagnostics.

See docs/mcp.md for full configuration details, authentication options, and tool schemas.

Available Interfaces and Ports

REST API Reference

The lightweight API server on port 8080 manages circuits and monitors health without requiring clients to implement the Tor Control Protocol.

HTTP Methods: POST is recommended for state mutations (/reconnect, /disconnect, /connect). Legacy GET calls remain fully supported for backward compatibility. Mutations presented with a foreign browser Origin/Referer are rejected with 403 Forbidden (CSRF protection); curl/script calls without those headers are unaffected. Authentication (Recommended): Unauthenticated by default for backward compatibility. Setting TORPROXY_API_TOKEN (or TORPROXY_API_KEY) protects all endpoints with Authorization: Bearer <token> or X-API-Key: <token>. Detailed schema definitions are documented in docs/api.md.

Container Health Checks

torproxy includes a ready-aware Docker health check (docker/healthcheck.sh). A container reports healthy only when:

1. Privoxy and Tor daemons are running under non-root user.

2. Tor bootstrap is 100% complete (bootstrapped=done).

3. SOCKS5 listener on port 9050 passes greeting handshake.

4. Egress IP is confirmed through Tor (IsTor: true).

In Docker Compose, dependent services can wait for genuine Tor readiness using service_healthy:

services:
  app:
    image: my-scraper:latest
    depends_on:
      torproxy:
        condition: service_healthy

Configuration

Default settings require no configuration. You can customize listening ports and bindings via environment variables in a .env file or Compose environment section:

All variables are strictly validated at startup. Port conflicts or out-of-range values trigger an immediate diagnostic failure. See docs/configuration.md for full details.

GeoIP Auto-Update

By default torproxy uses the Tor GeoIP database bundled with the Alpine Tor package (/usr/share/tor/geoip{,6}), which is only refreshed when the Docker image is rebuilt. To keep country routing (TORPROXY_COUNTRY=DE) on a fresh IP-to-country mapping, enable the opt-in auto-update:

TORPROXY_GEOIP_AUTO_UPDATE=1 TORPROXY_COUNTRY=DE docker compose up -d

With TORPROXY_GEOIP_AUTO_UPDATE=1 the container downloads geoip/geoip6 from Tor Project GitLab (HTTPS) at startup and then every TORPROXY_GEOIP_UPDATE_INTERVAL seconds (default 86400 = 24h), validates the format, installs the files atomically into TORPROXY_GEOIP_DIR (default /var/lib/tor/geoip), and sends Tor SIGHUP to reload them. If the download or validation fails (e.g. offline or upstream unavailable), the previously installed — or bundled — database keeps working, so an old version never breaks country routing. Each attempt is recorded and exposed additively as geoip in /status, so a silent fallback is visible. The pre-publish Live Image Verification gate checks that the GeoIP URLs are reachable and that a container with auto-update enabled downloads the database; the Daily Live Image Verification workflow repeats this as a drift detector. Additional settings: TORPROXY_GEOIP_URL, TORPROXY_GEOIP6_URL, TORPROXY_GEOIP_MAX_BYTES, TORPROXY_GEOIP6_MAX_BYTES.

Shipped Examples

Ready-to-run use cases with hardened configurations:

Security Model and Trust Boundaries

• Non-Root Execution: The container init starts as root only to drop privileges — every daemon runs as an unprivileged user (tor, privoxy, torproxy). In gateway mode the netfilter WAN bypass is scoped to the dedicated tor UID, so the API/Privoxy cannot reach the WAN directly (ISSUE-03).

• Authenticated ControlPort: Tor's control port (127.0.0.1:9051) requires ephemeral filesystem cookie authentication (CookieAuthentication 1).

• Fail-Closed Guarantee: If Tor disconnects or crashes, Privoxy drops traffic and returns HTTP 503 instead of leaking to clearnet.

• DNS Leak Prevention: To prevent local DNS leaks, always use remote DNS resolution with SOCKS5 (curl --socks5-hostname 127.0.0.1:9050 or socks5h://).

• Threat Model: See SECURITY.md for vulnerability reporting procedures, threat boundaries, and anonymity limitations.

• Hardening Guide: See docs/hardening.md for read-only rootfs and dropped Linux capabilities.

Project Documentation

• docs/compatibility.md — Backward compatibility contract and frozen interfaces.

• docs/api.md — Exhaustive REST API specification and response schemas.

• docs/configuration.md — Configuration guide and startup validation rules.

• docs/hardening.md — Container runtime hardening, read-only rootfs, and security recommendations.

• docs/releases.md — Semantic versioning policy, upgrade paths, and rollback procedures.

Contributing

We welcome contributions! Please review our Contributing Guidelines and Code of Conduct. All PRs must maintain backward compatibility, include hermetic unit tests, and maintain >= 90% test coverage.

License

Released under the MIT License.

💝 Support the Project

If you find this project helpful, consider showing some support:

• ☕ Buy me a coffee: Send a tip via PayPal.

• ❤️ Charity Donation: Donate to Österreichische Krebshilfe (Austrian Cancer Aid) or any local animal welfare organization.

• 🎯 Dream Support: I would love some tickets for the World Darts Championship at Ally Pally (Alexandra Palace) – hopefully, I will make it there one day!