Repository navigation
Releases
ESPHole v1.0.0
ESPHole v1.0.0
A Pi-hole–style DNS sinkhole for the ESP32-S3. Every DNS query on your LAN passes through
it: blocklisted domains die with a black-hole answer (0.0.0.0 / ::), everything else is
forwarded to an upstream resolver and cached — and above all, the network never loses DNS even if
blocking fails (fail-open by design).
Built spec-by-spec with strict test-driven development and on-hardware verification.
⚡ Install in ~60 seconds — no toolchain
From your browser (recommended). Plug an ESP32-S3 in over USB and click Install on the live
page — no ESP-IDF, no drivers, no build. Desktop Chrome or Edge required (Web Serial):
👉 https://aguilerasmiguel.github.io/esphole/#install
From the command line. Grab esphole-factory-esp32s3.bin below and flash it at offset 0:
esptool --chip esp32s3 write-flash 0x0 esphole-factory-esp32s3.binOn first boot the device starts the ESPHole-XXXX Wi-Fi AP (the WPA2 key is printed on the serial
console). Join it, set your home Wi-Fi at http://192.168.4.1/, then point a client's DNS at the
device and create your admin password on first visit. Full guide in the
README.
Highlights
- DNS core (RFC 1035 + EDNS0): UDP + TCP on :53, A/AAAA suffix blocking, upstream failover,
cache, per-IP rate-limiting, fail-open. - Encrypted upstream (DoT, RFC 7858): forward over DNS-over-TLS with a fail-closed
guarantee — it never silently falls back to plaintext. - Blocklists from URL: download a HOSTS list over HTTPS and rebuild in place, no reboot.
- OTA updates with automatic rollback if a new build doesn't boot.
- Web admin + HTTP API: challenge-response login (the password never travels the wire),
bilingual EN/ES UI, light/dark themed redesign, per-client stats. - Wi-Fi provisioning: captive AP portal on first boot with a per-device WPA2 key.
Capacity & limits
The blocklist is a sorted, deduplicated PSRAM store: up to ~200,000 domains or ~5.44 MB of
domain text, whichever fills first (~6.2 MB of the 8 MB PSRAM). That covers the big curated HOSTS
lists (e.g. StevenBlack ≈ 150 k) with headroom — deliberately not server-scale. On overflow the
extra entry is dropped and a truncated counter increments (bounded and observable, never a crash).
Known limitations
- The optional DHCP server is NOT yet verified end-to-end on a live LAN. Its wire/lease logic is
unit-tested and the API/UI exist, but a rogue DHCP server can hand out IPs and disrupt a real
network. Leave it off unless you are testing on an isolated segment with the router's own DHCP
disabled.
Hardware & verification
- Target: ESP32-S3-N16R8 (16 MB flash, 8 MB octal PSRAM). Other S3 variants may work with
partition tweaks. - Built with ESP-IDF v6.0.1. Pure-logic modules are unit-tested on the host under ASan/UBSan;
specs 001–010 were verified on hardware (DHCP excepted, see above).
Assets
esphole-factory-esp32s3.bin— full merged image (bootloader + partition table + app + web UI),
flash at offset0x0. This is the file the command-line install above uses. The browser installer
serves its own split app/UI images from the site.
License: MIT.