diff --git a/CHANGELOG.md b/CHANGELOG.md
index 558b7d8..c80c85e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [2.7.6] โ 2026-11-12
+
+### Changed
+- **docs**: Restructure README.md and DOCKERHUB.md with developer psychology, progressive disclosure, and 2-step quickstarts (#144, #145)
+- **docs**: Add quick-reference endpoint matrix to `docs/api.md` and key variables callout to `docs/configuration.md` (#145)
+- **docs**: Relocate MCP quickstart ahead of architecture details in `docs/mcp.md` (#145)
+- **chore**: Synchronize version 2.7.6 across pyproject.toml, Dockerfile, server.json, and documentation contracts (#145)
+
## [2.7.5] โ 2026-11-11
### Added
@@ -240,7 +248,8 @@ Sprint 1 security & contract correctness release.
---
-[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.5...HEAD
+[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.6...HEAD
+[2.7.6]: https://github.com/hapheus/torproxy/compare/v2.7.5...v2.7.6
[2.7.5]: https://github.com/hapheus/torproxy/compare/v2.7.4...v2.7.5
[2.7.4]: https://github.com/hapheus/torproxy/compare/v2.7.3...v2.7.4
[2.7.3]: https://github.com/hapheus/torproxy/compare/v2.7.2...v2.7.3
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
index a2a3ec8..ca26aaf 100644
--- a/DOCKERHUB.md
+++ b/DOCKERHUB.md
@@ -3,43 +3,34 @@
[](https://opensource.org/licenses/MIT)
[](https://hub.docker.com/r/hapheus/torproxy)
[](https://hub.docker.com/r/hapheus/torproxy)
+[](https://github.com/hapheus/torproxy)
+[](https://github.com/hapheus/torproxy)
+[](https://www.bestpractices.dev/projects/15828)
-A lightweight, secure, and production-ready Docker container combining **Tor**, **Privoxy** (HTTP/HTTPS proxy), **SOCKS5**, and a local **REST control API**.
+**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](https://github.com/hapheus/torproxy)
---
-## Key Features
+## โก Core Value & Features
-- **Transparent Tor Gateway**: Route any Docker container's entire TCP and DNS traffic automatically through Tor using `network_mode: "service:torproxy"` โ zero app proxy configuration, fail-closed netfilter kill switch.
-- **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.
+- **๐ก๏ธ 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
+## ๐ Quick Start
-### Option 1: Docker Run
+### Recommended: Docker Compose
-```bash
-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
+Create a `docker-compose.yml`:
```yaml
services:
@@ -48,25 +39,74 @@ services:
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"
+ - "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
```
-### Option 3: Country-Specific Exit Proxy (e.g. Germany or Austria)
+Launch the proxy:
+```bash
+docker compose up -d
+```
+
+### Alternative: Docker Run (Single Command)
```bash
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
```
-### Option 4: Transparent Tor Gateway (Zero-Config Routing)
+---
+
+## ๐งช Verifying Tor Connectivity
+
+Wait a few seconds for Tor to finish bootstrapping, then test:
+
+```bash
+# 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"
+```
+
+> [!IMPORTANT]
+> **Leak-Proof Guarantee (Fail-Closed):** If Tor fails or disconnects, `torproxy` fails closed immediately. It will **never** fall back to direct clearnet routing.
+
+---
+
+## ๐ฏ 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:
```yaml
services:
@@ -79,7 +119,8 @@ services:
TORPROXY_GATEWAY_MODE: "true"
restart: unless-stopped
- my-app:
+ # Any container attached to torproxy's network stack is automatically anonymized:
+ scraper:
image: curlimages/curl:latest
network_mode: "service:torproxy"
depends_on:
@@ -88,27 +129,36 @@ services:
command: ["-s", "https://check.torproject.org/api/ip"]
```
----
-
-## Verifying Tor Connectivity
+### 2. AI Coding Assistants (Model Context Protocol / MCP)
-Wait a few seconds for Tor to bootstrap, then test:
+Connect **Claude Desktop** directly via Docker Stdio without exposing host ports:
-```bash
-# 1. Check REST API status
-curl -s http://127.0.0.1:8080/status | jq .
+```json
+{
+ "mcpServers": {
+ "torproxy": {
+ "command": "docker",
+ "args": ["exec", "-i", "torproxy", "torproxy", "mcp"]
+ }
+ }
+}
+```
-# 2. Test HTTP proxy via Privoxy
-curl --proxy http://127.0.0.1:8118 https://check.torproject.org/api/ip
+Or connect **Cursor** / **Antigravity** via HTTP/SSE (`http://127.0.0.1:2501/sse`).
-# 3. Test SOCKS5 proxy (using remote DNS to prevent leaks)
-curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
+### 3. Country-Specific Exit Proxy
-# 4. Request a new Tor identity / circuit
-curl -X POST http://127.0.0.1:8080/reconnect
+Route traffic exclusively through specific countries:
-# 5. Dynamically switch exit country without restart
-curl -X POST "http://127.0.0.1:8080/reconnect?country=DE"
+```bash
+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
```
---
@@ -137,12 +187,14 @@ The management API listens on port `8080` (HTTP):
| Variable | Default | Description |
| -------- | ------- | ----------- |
-| `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | Bind address for Privoxy and Tor inside the container. |
-| `TORPROXY_LISTEN_PORT` | `8118` | Privoxy HTTP proxy port. |
-| `TORPROXY_SOCKS_PORT` | `9050` | Tor SOCKS5 proxy port. |
-| `TORPROXY_API_PORT` | `8080` | REST API port. |
| `TORPROXY_COUNTRY` | *(unset)* | Comma-separated ISO 3166-1 alpha-2 codes (e.g. `DE`, `AT`, `US`, `DE,AT`) to restrict exit nodes. |
| `TORPROXY_STRICT_NODES` | `0` | If `1`/`true`, refuse circuits if nodes in the requested country/countries are unavailable. |
+| `TORPROXY_GATEWAY_MODE` | `0` | Enable Transparent Tor Gateway mode (`cap_add: [NET_ADMIN]` required). |
+| `TORPROXY_API_TOKEN` | *(unset)* | Optional Bearer token / API key securing REST API port 8080. |
+| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | Opt-in: periodically download fresh GeoIP database from Tor Project GitLab. |
+| `TORPROXY_LISTEN_PORT` | `8118` | Privoxy HTTP proxy port inside container. |
+| `TORPROXY_SOCKS_PORT` | `9050` | Tor SOCKS5 proxy port inside container. |
+| `TORPROXY_API_PORT` | `8080` | REST API port inside container. |
---
diff --git a/README.md b/README.md
index 6371c91..1a4cdbc 100644
--- a/README.md
+++ b/README.md
@@ -15,11 +15,90 @@
[](https://scorecard.dev/viewer/?uri=github.com/hapheus/torproxy)
[](https://www.bestpractices.dev/projects/15828)
-[Quick Start](#quick-start) ยท [Model Context Protocol (MCP)](#-model-context-protocol-mcp) ยท [Transparent Gateway](#transparent-tor-gateway) ยท [Architecture](#architecture) ยท [REST API](docs/api.md) ยท [Configuration](docs/configuration.md) ยท [Examples](examples/) ยท [Contributing](CONTRIBUTING.md)
+[Quick Start](#quick-start) ยท [Transparent Gateway](#transparent-tor-gateway) ยท [Model Context Protocol (MCP)](#-model-context-protocol-mcp) ยท [Use Cases](#-when-to-use-torproxy) ยท [Architecture](#architecture) ยท [REST API](docs/api.md) ยท [Configuration](docs/configuration.md) ยท [Examples](examples/) ยท [Contributing](CONTRIBUTING.md)
-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.
+**A production-grade, leak-proof Tor HTTP and SOCKS5 proxy packaged for Docker.**
+Route entire container stacks without touching application code, equip AI coding assistants (Claude Desktop, Cursor) with native Tor tools via MCP, and rotate circuits dynamically with a single REST call.
+
+- ๐ก๏ธ **Zero Clearnet Leaks:** Fail-closed netfilter kill-switch & Privoxy fail-safe โ never leaks your real IP on connection drops.
+- ๐ **Transparent Tor Gateway:** Tunnel any container's TCP & DNS via `network_mode: "service:torproxy"` โ zero app config changes.
+- ๐ค **Native AI Agent MCP Server:** Built-in Model Context Protocol server (SSE & Stdio) for Claude Desktop, Cursor, and Antigravity.
+- ๐ **Dynamic Circuit & Country Control:** Switch identities (`SIGNAL NEWNYM`) and select exit node countries on the fly via REST.
+- ๐ **Defense in Depth:** Runs strictly as an unprivileged user (`torproxy`), with ephemeral cookie authentication for Tor control.
+
+---
+
+## Quick Start
+
+Get up and running with a verified Tor circuit in seconds:
+
+### 1. Launch torproxy
+
+Clone and run via Docker Compose:
+```sh
+docker compose up -d
+```
+*Or launch directly via Docker Run without cloning:*
+```sh
+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
+```
+
+### 2. Verify Tor connectivity
+```sh
+# Verify HTTP proxy (returns {"IsTor": true, "IP": "..."})
+curl -x http://127.0.0.1:8118 https://check.torproject.org/api/ip
+
+# Verify SOCKS5 proxy with remote DNS resolution
+curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
+
+# Check live connection status via REST API
+curl -s http://127.0.0.1:8080/status | jq .
+```
+
+> [!IMPORTANT]
+> **Leak-Proof Guarantee (Fail-Closed):** If Tor disconnects or crashes, Privoxy immediately returns `503 Service Unavailable` and the Netfilter kill switch drops outgoing packets. Your real IP will **never** silently leak to clearnet under network failures.
+
+> **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.
+
+
+โก Advanced: Dynamic Identity Rotation & Country Routing (click to expand)
+
+```sh
+# Request a fresh Tor identity without restarting the container:
+curl -X POST http://127.0.0.1:8080/reconnect
+
+# Switch exit country dynamically on reconnect:
+curl -X POST "http://127.0.0.1:8080/reconnect?country=DE"
+
+# Switch with strict exit country enforcement via JSON payload:
+curl -X POST http://127.0.0.1:8080/reconnect \
+ -H "Content-Type: application/json" \
+ -d '{"country": "AT", "strict_nodes": true}'
+
+# Or launch with a default country at startup:
+TORPROXY_COUNTRY=DE docker compose up -d
+```
+
+
+---
+
+## ๐ฏ When to Use torproxy
+
+Understanding where `torproxy` excels helps you pick the right tool for the job:
+
+- โ
**Ideal For:**
+ - **Automated Web Scraping & Data Extraction:** Distribute requests and bypass IP rate limits with dynamic circuit rotation.
+ - **AI Agent Automation (MCP):** Allow Claude Desktop, Cursor, and agent frameworks to fetch web and `.onion` pages safely.
+ - **Zero-Friction Container Privacy:** Tunnel third-party containers (crawlers, search engines, microservices) with zero code modifications.
+ - **Geolocation Verification:** Test localized web experiences and CDN geo-routing across different exit countries (`TORPROXY_COUNTRY=DE,AT,US`).
+ - **Self-Hosted Privacy Stacks:** Route upstream search queries (e.g. SearXNG) privately.
+- โ ๏ธ **Not Designed For:**
+ - **High-Bandwidth / Latency-Critical Traffic:** Tor is not designed for 4K video streaming, voice calls, or real-time gaming.
+ - **Bypassing Dedicated Anti-Bot Protection:** Major CDNs (e.g., Cloudflare, Akamai) often challenge or block known public Tor exit nodes.
---
@@ -44,38 +123,7 @@ Host Client / Dependent Containers
---
-## Quick Start
-
-```sh
-# 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**.
@@ -218,35 +266,17 @@ services:
## Configuration
-Default settings require no configuration. You can customize listening ports and bindings via environment variables in a `.env` file or Compose `environment` section:
-
-| Variable | Default | Allowed Values | Description |
-| -------- | ------- | -------------- | ----------- |
-| `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | Valid IPv4 | Bind address for Privoxy inside the container. |
-| `TORPROXY_LISTEN_PORT` | `8118` | `1024`โ`65535` | HTTP proxy listening port inside the container. |
-| `TORPROXY_HOST_PORT` | `8118` | `1`โ`65535` | Host port mapped to HTTP proxy in `docker-compose.yml`. |
-| `TORPROXY_API_PORT` | `8080` | `1024`โ`65535` | REST API listening port (host and container). |
-| `TORPROXY_SOCKS_PORT` | `9050` | `1024`โ`65535` | Tor SOCKS5 proxy port (host and container). |
-| `TORPROXY_COUNTRY` | *(unset)* | ISO 3166-1 alpha-2 (e.g. `DE`, `AT`, `US`, `DE,AT`) | Route Tor exit circuits through specific countries using `tor-geoipdb`. |
-| `TORPROXY_STRICT_NODES` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | When `1`/`true`, reject circuits if configured country exit nodes are unavailable. |
-| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | Opt-in: periodically download Tor's GeoIP database (`geoip`/`geoip6`) from Tor Project GitLab and reload Tor. On failure the bundled/previous database keeps working. See [GeoIP auto-update](#geoip-auto-update). |
-| `TORPROXY_API_TOKEN` | *(unset)* | String | Optional: Bearer token / API key securing REST API port 8080. Recommended for production. |
-| `TORPROXY_API_ALLOW_ANONYMOUS_HEALTH` | `0` | `0`, `1`, `true`, `false` | Optional: Allow unauthenticated `/health` probing when `TORPROXY_API_TOKEN` is set. |
-| `TORPROXY_GATEWAY_MODE` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | Enable Transparent Tor Gateway mode (`TransPort`, `DNSPort`, netfilter kill switch). Requires `cap_add: [NET_ADMIN]`. |
-| `TORPROXY_TRANS_PORT` | `9040` | `1024`โ`65535` | Listening port for Tor TransPort when gateway mode is enabled. |
-| `TORPROXY_DNS_PORT` | `9053` | `1024`โ`65535` | Listening port for Tor DNSPort when gateway mode is enabled. |
-
-All variables are strictly validated at startup. Port conflicts or out-of-range values trigger an immediate diagnostic failure. See [docs/configuration.md](docs/configuration.md) for full details.
+Default settings work out-of-the-box with zero configuration. You can customize runtime behavior using environment variables in `.env` or Docker Compose:
-### 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:
-
-```sh
-TORPROXY_GEOIP_AUTO_UPDATE=1 TORPROXY_COUNTRY=DE docker compose up -d
-```
+| Variable | Default | Purpose |
+| -------- | ------- | ------- |
+| `TORPROXY_COUNTRY` | *(unset)* | Restrict exit nodes to specific countries (e.g. `DE`, `AT`, `US`, `DE,AT`). |
+| `TORPROXY_STRICT_NODES` | `0` | When `1`/`true`, reject circuits if configured country exit nodes are unavailable. |
+| `TORPROXY_GATEWAY_MODE` | `0` | Enable Transparent Tor Gateway mode (`TransPort`, `DNSPort`, netfilter kill switch). Requires `cap_add: [NET_ADMIN]`. |
+| `TORPROXY_API_TOKEN` | *(unset)* | Bearer token / API key securing REST API port `8080`. Recommended for production. |
+| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | Opt-in: periodically download and refresh Tor's GeoIP database from Tor Project GitLab. |
-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`.
+> ๐ **Full Configuration Reference:** See [docs/configuration.md](docs/configuration.md) for custom listening ports (`TORPROXY_LISTEN_PORT`, `TORPROXY_SOCKS_PORT`, `TORPROXY_API_PORT`), address binding rules, and GeoIP update parameters.
---
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 93ac9ae..fbd43c1 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -7,7 +7,7 @@ ARG PYTHON_VERSION=3.14
LABEL org.opencontainers.image.title="torproxy" \
org.opencontainers.image.description="A minimal HTTP proxy routed through Tor" \
- org.opencontainers.image.version="2.7.5" \
+ org.opencontainers.image.version="2.7.6" \
org.opencontainers.image.licenses="MIT" \
org.opencontainers.image.source="https://github.com/hapheus/torproxy" \
org.opencontainers.image.url="https://github.com/hapheus/torproxy" \
diff --git a/docs/api.md b/docs/api.md
index 9a9d283..f244623 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -22,6 +22,21 @@ The `torproxy` container includes an internal REST API server written in Python.
## 2. Endpoints
+### Quick Reference
+
+| Endpoint | Methods | Status Codes | Description |
+|---|---|---|---|
+| [`/status`, `/`](#get--post-status-or-) | `GET`, `POST` | `200`, `500` | Connection status and current verified exit IP. |
+| [`/ip`](#get--post-ip) | `GET`, `POST` | `200`, `503` | Current Tor egress IP (returns 503 while bootstrapping). |
+| [`/health`](#get--post-health-or-v1health) | `GET`, `POST` | `200`, `503` | Diagnostic health state across Tor, proxies, and egress. |
+| [`/reconnect`](#post--get-reconnect) | `POST`, `GET` | `200`, `400` | Request new circuit (`SIGNAL NEWNYM`); optional country change. |
+| [`/disconnect`](#post--get-disconnect) | `POST`, `GET` | `200` | Pause Tor network traffic (`DisableNetwork=1`). |
+| [`/connect`](#post--get-connect) | `POST`, `GET` | `200`, `400` | Resume Tor network traffic (`DisableNetwork=0`). |
+| [`/diagnostics`](#get--post-diagnostics-or-v1diagnostics) | `GET`, `POST` | `200` | Telemetry (uptime, reconnect counts, bootstrap progress). |
+| [`/metrics`](#get--post-metrics-or-v1metrics) | `GET`, `POST` | `200` | Prometheus exposition format metrics for scrapers. |
+
+---
+
### GET | POST `/status` (or `/`)
Returns the current connection state and verified egress IP.
diff --git a/docs/configuration.md b/docs/configuration.md
index 6da43cd..a0e426a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -6,6 +6,16 @@ This guide provides the complete configuration reference for `torproxy`, includi
All settings have sensible defaults that allow running `torproxy` with zero configuration. When running via Docker Compose or `docker run`, settings can be customized using environment variables.
+> ๐ก **Quick Reference โ Frequently Used Variables:**
+> - **Route through country:** `TORPROXY_COUNTRY=DE` (or `DE,AT`)
+> - **Enforce country strictly:** `TORPROXY_STRICT_NODES=1`
+> - **Enable Transparent Gateway:** `TORPROXY_GATEWAY_MODE=1`
+> - **Secure API with Bearer token:** `TORPROXY_API_TOKEN=your-token`
+> - **Automatic GeoIP database updates:** `TORPROXY_GEOIP_AUTO_UPDATE=1`
+> - **Enable AI Agent MCP (SSE):** `TORPROXY_MCP_ENABLED=1` (port `2501`)
+
+### Complete Settings Reference
+
| Variable | Default | Type | Description |
|---|---|---|---|
| `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | IP address (IPv4 or IPv6, e.g. `::1`) | Address inside the container that Privoxy binds to. Set to `0.0.0.0` to permit container-to-container connections. |
diff --git a/docs/mcp.md b/docs/mcp.md
index 6956ab5..c1b31ae 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -4,25 +4,7 @@
---
-## 1. Architecture & Dual-Transport Support
-
-The MCP server adheres strictly to the `torproxy` zero-dependency standard (using pure Python standard library: `http.server`, `json`, `threading`, `queue`).
-
-It supports two distinct transport protocols:
-
-1. **Stdio Transport (`torproxy mcp`):**
- - Designed for local processes and container execution: `docker exec -i torproxy torproxy mcp`.
- - Communicates using newline-delimited JSON-RPC 2.0 frames over `stdin` and `stdout`.
- - All internal diagnostics and operational warnings are directed to `stderr` to maintain clean protocol isolation.
- - Recommended for **Claude Desktop**.
-2. **HTTP/SSE & Streamable HTTP Transport (Port 2501):**
- - Runs as a non-blocking daemon thread on port `2501` (`TORPROXY_MCP_PORT=2501`).
- - Supports both **HTTP/SSE** (`GET /sse` or `GET /mcp` for Server-Sent Events stream initialization + `POST /messages?sessionId=...` for JSON-RPC dispatch) and **Streamable HTTP** (direct JSON-RPC `POST` to `/mcp`, `/sse`, or `/`).
- - Recommended for **Cursor**, **Antigravity**, and remote container orchestrators.
-
----
-
-## 2. Quickstart Configuration Examples
+## 1. Quickstart Configuration Examples
### Claude Desktop (`claude_desktop_config.json`)
@@ -156,6 +138,24 @@ services:
---
+## 2. Architecture & Dual-Transport Support
+
+The MCP server adheres strictly to the `torproxy` zero-dependency standard (using pure Python standard library: `http.server`, `json`, `threading`, `queue`).
+
+It supports two distinct transport protocols:
+
+1. **Stdio Transport (`torproxy mcp`):**
+ - Designed for local processes and container execution: `docker exec -i torproxy torproxy mcp`.
+ - Communicates using newline-delimited JSON-RPC 2.0 frames over `stdin` and `stdout`.
+ - All internal diagnostics and operational warnings are directed to `stderr` to maintain clean protocol isolation.
+ - Recommended for **Claude Desktop**.
+2. **HTTP/SSE & Streamable HTTP Transport (Port 2501):**
+ - Runs as a non-blocking daemon thread on port `2501` (`TORPROXY_MCP_PORT=2501`).
+ - Supports both **HTTP/SSE** (`GET /sse` or `GET /mcp` for Server-Sent Events stream initialization + `POST /messages?sessionId=...` for JSON-RPC dispatch) and **Streamable HTTP** (direct JSON-RPC `POST` to `/mcp`, `/sse`, or `/`).
+ - Recommended for **Cursor**, **Antigravity**, and remote container orchestrators.
+
+---
+
## 3. Available Tools
| Tool | Parameters | Description |
diff --git a/docs/releases.md b/docs/releases.md
index 289683e..679443c 100644
--- a/docs/releases.md
+++ b/docs/releases.md
@@ -91,6 +91,11 @@ If an upgraded image exhibits unexpected behavior in your environment:
## 6. Release Notes
+### 2.7.6 (Developer Experience, Behavioral Psychology & Documentation Optimization)
+
+- **Documentation & DX Optimization (#144, #145):** Restructured `README.md`, `DOCKERHUB.md`, and `/docs` using developer psychology, cognitive load reduction (Hick's Law), and progressive disclosure. Added instant 2-step verification, zero-clone `docker run` quickstarts, honest boundaries ("When to use / when not to use"), explicit fail-closed guarantees, and rapid-navigation matrices across `docs/api.md` and `docs/configuration.md`.
+- **Single Source of Truth Synchronization:** Synchronized version 2.7.6 across `pyproject.toml`, `docker/Dockerfile`, `server.json`, `docs/releases.md`, and `CHANGELOG.md`.
+
### 2.7.5 (MCP Auto-Discovery Manifests for Cursor and Smithery.ai)
- **Cursor & Smithery.ai Manifests (#143):** Added root-level auto-discovery manifest files `.mcp.json` and `smithery.yaml`, enabling zero-config integration in Cursor / cursor.directory and automated live-healthcheck evaluation on Smithery.ai.
diff --git a/pyproject.toml b/pyproject.toml
index 66004fc..06b4a8b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "torproxy"
-version = "2.7.5"
+version = "2.7.6"
description = "A minimal HTTP and SOCKS5 proxy routed through the Tor network with local REST control API"
readme = "README.md"
requires-python = ">=3.10"
diff --git a/server.json b/server.json
index 64de9ff..515d6f7 100644
--- a/server.json
+++ b/server.json
@@ -3,7 +3,7 @@
"name": "io.github.hapheus/torproxy",
"title": "torproxy",
"description": "Tor HTTP and SOCKS5 proxy with REST API and built-in MCP server.",
- "version": "2.7.5",
+ "version": "2.7.6",
"repository": {
"url": "https://github.com/hapheus/torproxy",
"source": "github"
@@ -11,7 +11,7 @@
"packages": [
{
"registryType": "oci",
- "identifier": "docker.io/hapheus/torproxy:2.7.5",
+ "identifier": "docker.io/hapheus/torproxy:2.7.6",
"transport": {
"type": "stdio"
},
diff --git a/uv.lock b/uv.lock
index 380bc10..46fc4dc 100644
--- a/uv.lock
+++ b/uv.lock
@@ -842,7 +842,7 @@ wheels = [
[[package]]
name = "torproxy"
-version = "2.7.5"
+version = "2.7.6"
source = { editable = "." }
[package.optional-dependencies]