Torhole

A self-hosted DNS privacy gateway that blocks unwanted domains, encrypts resolver traffic, routes it through Tor, and proves the protected path live.

Comment

Inspiration

Most network privacy tools ask users to trust a green badge. Pi-hole can block unwanted domains, but blocking alone does not hide where allowed DNS queries originate. A full-tunnel VPN changes the path of all application traffic and transfers trust to a VPN operator.

Torhole takes a narrower, verifiable approach: protect the DNS path while leaving ordinary web and application traffic alone. The goal is not to promise anonymity. It is to make one precise guarantee visible and testable: DNS handled by Torhole is filtered locally, encrypted to the resolver, and sent through Tor so the resolver sees a Tor exit rather than the household or office public IP.

What it does

Every protected lookup follows this path:

device -> Pi-hole -> dnscrypt-proxy -> Tor -> upstream resolver

Torhole ships as one product with two capability profiles:

  • Home gives households and first-time self-hosters a guided installer, a lightweight privacy dashboard, live verification, and safe everyday controls.
  • Advanced uses the same privacy core and adds single-LAN or Trusted/IoT VLAN operation, live Tor circuit and control-port telemetry, SSO, recovery, backups, metrics, logs, alerts, and container operations.

The UI does not treat missing data as success. It distinguishes a confirmed Tor exit, a confirmed failure, and an inconclusive external-verifier outage. Operators can see the Tor version, bootstrap state, live traffic counters, per-plane circuit identity, query activity, and the latest external leak test.

Torhole is explicit about its boundary: it protects DNS requests that actually use Torhole. It is not a VPN, does not hide normal browser traffic, and cannot control applications that bypass network DNS.

How we built it

Torhole is a Docker Compose platform with Pi-hole, dnscrypt-proxy, and Tor forming the enforced privacy path. A guided web installer generates deployment-specific configuration for Home, Advanced single-LAN, or Advanced VLAN mode. The Advanced workspace combines a React/TypeScript interface with a Python control and recovery service, Prometheus, Grafana, Loki, Alertmanager, Caddy, and Authelia.

Privacy is enforced structurally. The DNS resolver containers reach upstream resolvers through Tor, while firewall and container-network rules reject unintended direct egress. Runtime checks verify DNS resolution, blocking, Tor bootstrap, control-port authentication, and external Tor egress. The dashboards and alerts are aligned to the active topology rather than pretending that inactive VLAN planes are broken.

How Codex and GPT-5.6 accelerated the work

Codex with GPT-5.6 was used as an engineering partner across the repository during Build Week. It traced the existing installer and network topology, implemented the unified Home/Advanced product flow, refactored the operational UI, audited Grafana queries and alert semantics, wrote characterization and browser tests, reviewed privacy claims against implementation, deployed disposable staging VMs, and validated the finished product against live telemetry.

The human retained product direction, privacy boundaries, infrastructure ownership, and release decisions. Codex accelerated repository-wide changes and repeated verification that would otherwise have required moving manually between Docker, React, Python, Prometheus, Grafana, SSH, and browser tooling.

A live staging run exposed an important edge case: a transient TLS failure from the external Tor verifier was being displayed as a privacy leak. Codex traced the backend and UI state, added a distinct inconclusive result, excluded unavailable checks from conclusive pass rates, added regression coverage, redeployed the fix, and recorded the successful recovery. That finding captures the project's philosophy: uncertainty must never be painted green—or falsely presented as a confirmed leak.

Challenges

The hardest problem was making the privacy claim both honest and operationally useful. Container health is not proof of privacy, a missing metric is not zero, and a third-party verifier can fail independently of the enforced path. Home, Advanced single-LAN, and VLAN deployments also expose different components, so one universal dashboard can easily become noisy or misleading.

We addressed those problems with topology-aware state, three-state verification, actionable remediation text, bounded local telemetry, and live validation on clean disposable VMs rather than JSON inspection alone.

Accomplishments

  • One guided installer and one privacy core across Home and Advanced
  • A working live privacy proof instead of a static health badge
  • Safe distinction between confirmed failure and verifier unavailability
  • Fresh Home and Advanced staging deployments validated end to end
  • Automated backend characterization, TypeScript build/typecheck, shell/config CI, and focused Playwright privacy tests
  • Public documentation that states exactly what Torhole protects—and what it does not

What we learned

Privacy software earns trust by exposing evidence, limits, and uncertainty. The strongest operational UI is not the one with the most green panels; it is the one that helps a non-expert understand what is protected, what is unknown, and what to do next.

What's next

Next steps are broader Raspberry Pi hardware validation, signed release artifacts, additional router-specific setup guides, longer soak testing across Tor circuit changes, and a public read-only demo environment that lets judges explore the UI without exposing a real household network.

Built With

Share this project:

Updates