---

📖 Introduction

DNS Worker is a privacy-first protective DNS resolution system with built-in ad & malicious domain blocking, supporting Dual-Engine Architecture:

• ☁️ Edge Serverless Mode: Run on Cloudflare Workers across 300+ edge locations worldwide with D1 database, enjoying zero maintenance and high-availability DoH (HTTP/2 & HTTP/3 compatible).
• 🖥️ Standalone Server Mode (Serverfull): Run completely free of Cloudflare on your own VPS, Linux home server, or Windows machine, with native UDP 53, DoT 853 (DoQ compatible with TLS SNI routing for Android Private DNS), and local SQLite.

📚 User Documentation
👉 https://oppidi.github.io/DNS-Worker/

Quick Start

Deploy to Cloudflare Workers

Standalone Server via npm

# Install globally and run
npm install -g dns-worker
dns-worker config init
dns-worker
# Web Dashboard: http://localhost:10080

Standalone Server via Docker (Beta)

# Run container with HTTPS (443), DoT (853), classic DNS (53), and TLS certificates
docker run -d \
  --name dns-worker \
  --restart unless-stopped \
  -p 53:53/udp \
  -p 853:853/tcp \
  -p 80:80/tcp \
  -p 443:443/tcp \
  -v dns_worker_data:/var/lib/dns-worker \
  -v dns_worker_config:/etc/dns-worker \
  -v /etc/letsencrypt:/etc/ssl/dns-worker:ro \
  hugokoo/dns-worker:latest

# Web Dashboard: https://your-domain-or-ip (HTTP on port 80 auto-redirects to HTTPS 443)

Key Highlights

• ⚡ Full-Stack Protocols: UDP 53, DoT 853 (DoQ RFC 9250 compatible), DoH (HTTP/2 & HTTP/3 compatible), ECH & DDR (RFC 9460).
• 🔀 Multi-Profile & Multi-Access Points: Create separate protection profiles for different users or scenarios, and derive unlimited sub-access points with independent routing tokens for granular per-device identification, filtering, and analytics.
• 🗄️ Multi-Database Engines: Easily switch between D1, Turso, and File backends via the DATABASE_SERVICE environment variable, eliminating D1 free-tier quota limits.
• 🛡️ Post-Quantum Zero-Knowledge E2EE: NIST FIPS 203 P256-MLKEM768 hybrid lattice cryptography + Hardware Passkeys (WebAuthn).
• 🚀 Local-First Architecture: Embedded in-browser WebAssembly SQLite + OPFS for instant 0ms log analytics and charting.
• 🛡️ Tiered Hybrid Protection & Ad Blocking: Native compatibility with AdGuard Home syntax (@@ whitelist hash set exceptions, $dnsrewrite, regex pool), dual-state prefix-encoded Bloom filter for millions of blocklist entries, configurable subdomain matching per rule, on-demand single-list sync, and staggered anti-burst pacing.

---

🔎 Quick Look

Analytics & Insights	Destinations Map

Multi-Access Points & Endpoints	Rules Configuration

Filter Subscriptions	Query Logs

Mobile Responsive	Mobile Logs

💡 For live demonstrations and endpoints setup, visit your Web Dashboard after launch or refer to the Official Documentation.

---

💪 Powered and Dependencies

DNS Worker stands on the shoulders of modern open-source infrastructure and cryptography:

• Compute & Runtime: Node.js (native node:sqlite) / Bun (>= 1.4.0) & Cloudflare Workers + D1 Database / Turso Database (libSQL)
• User Interface: React, Blueprint & Tailwind CSS
• Documentation: Astro & Starlight (lightning-fast, zero-JS static documentation)
• Cryptography & Storage: NIST FIPS 203 (ML-KEM-768) & wa-sqlite (WASM + OPFS Local-First driver)

---

📄 License

Licensed under the AGPL-3.0 License.