letstool/http2tor repository overview

⁠http2tor

Lightweight HTTP gateway that checks IP addresses against the Tor network through a JSON REST API.

Send a POST /api/v1/istor request with one or more IPs, get back structured JSON telling you whether each address belongs to the Tor network — and if so, which type of node it is (guard, exit, middle, authority), along with its flags, nickname, fingerprint, country, AS, and consensus weight.

The database is built automatically from a gzipped CSV served by the letstool CDN and refreshed every 4 hours. No MaxMind license, no Onionoo polling, no manual setup.

The binary embeds a web UI (dark/light mode, 15 languages, RTL support) and an OpenAPI 3.1 spec — no external files, no runtime dependencies.

⁠Quick start

docker run -p 8080:8080 letstool/http2tor:latest

Open http://localhost:8080⁠ to use the web UI, or query the API directly:

# Check a single IP
curl -s -X POST http://localhost:8080/api/v1/istor \
  -H "Content-Type: application/json" \
  -d '{"ip":"185.220.101.1"}' | jq

# Check multiple IPs at once
curl -s -X POST http://localhost:8080/api/v1/istor \
  -H "Content-Type: application/json" \
  -d '{"ips":["185.220.101.1","78.109.18.140","8.8.8.8"]}' | jq

Example response:

{
  "status": "SUCCESS",
  "answers": [
    {
      "ip": "185.220.101.1",
      "is_tor": true,
      "node_type": "exit",
      "flags": ["Exit", "Fast", "Running", "Stable", "Valid"],
      "nickname": "TorExitRelay",
      "fingerprint": "ABCDEF1234567890ABCDEF1234567890ABCDEF12",
      "country": "DE",
      "as": "AS24940",
      "as_name": "Hetzner Online GmbH",
      "first_seen": "2022-03-15 00:00:00",
      "consensus_weight": 48210,
      "is_guard": false,
      "is_exit": true,
      "is_middle": false,
      "is_authority": false,
      "is_hsdir": false
    },
    {
      "ip": "8.8.8.8",
      "is_tor": false
    }
  ]
}

⁠Configuration

CLI flags take priority over environment variables.

Proxy is supported via the standard HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables (same behaviour as curl).

docker run -p 8080:8080 \
  -v ./db:/data:rw \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  letstool/http2tor:latest

⁠Peer sync mode

Set TOR_DB_URL to another running http2tor instance to download the database directly from its /db/tor endpoint instead of fetching from the CDN. Useful for air-gapped environments or clusters where only one node hits the CDN.

docker run -p 8080:8080 \
  -e TOR_DB_URL=http://upstream-host:8080 \
  -v ./db:/data:rw \
  letstool/http2tor:latest

⁠Persistent storage

Mount a volume to /data to cache the database across container restarts:

docker run -p 8080:8080 \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  -v ./db:/data:rw \
  letstool/http2tor:latest

On restart, if the cached tor.mmdb is recent enough, it is reloaded immediately without refetching.

⁠Repo

https://github.com/letstool/http2tor⁠

⁠License

This project is licensed under the Apache License, Version 2.0⁠.

Copyright (c) 2026 letstool.net

⁠See also

Data sourced from the Tor Project Onionoo API⁠. This project is not affiliated with or endorsed by the Tor Project.