hapheus/torproxy repository overview

⁠torproxy

A minimal HTTP and SOCKS5 proxy that routes traffic through the Tor network. It is designed for simple, reliable Docker deployments and includes a small REST API plus a readiness-aware health check for automation.

⁠Features

• HTTP proxy via Privoxy on port 8118
• SOCKS5 proxy via Tor on port 9050
• JSON API for connection status and Tor circuit control on port 8080
• Docker health check reports healthy only after Tor is connected and the proxy works
• Runs as an unprivileged user with no persistent state

⁠Quick start

Run the proxy with all services limited to the local machine:

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

Wait until the container is healthy, then verify the Tor exit IP:

docker inspect --format '{{.State.Health.Status}}' torproxy
curl -x http://127.0.0.1:8118 https://check.torproject.org/api/ip
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip

Tor bootstrap can take a little time after the container starts.

⁠Ports

For another container on the same Docker network, use torproxy:8118, torproxy:9050, or torproxy:8080 instead of 127.0.0.1.

⁠REST API

The API returns JSON and accepts GET and POST where noted.

curl http://127.0.0.1:8080/status
curl -X POST http://127.0.0.1:8080/reconnect

A new circuit does not guarantee a different exit IP: Tor can rate-limit circuit changes.

⁠Configuration

Example with a different published HTTP port:

docker run -d --name torproxy \\
  -e TORPROXY_LISTEN_PORT=8118 \\
  -p 127.0.0.1:18118:8118 \\
  hapheus/torproxy:latest

⁠Security and responsible use

Neither proxy endpoint nor the API has authentication. Keep ports 8118, 9050, and 8080 on a trusted local or private Docker network; do not expose them publicly.

Tor is not a guarantee of anonymity and does not encrypt traffic beyond the destination. Prefer https://, and use the image only for lawful, authorised activity that respects applicable terms, rate limits, and law.

⁠More information

Source code, Docker Compose example, and complete usage documentation: github.com/hapheus/torproxy⁠

License: MIT⁠