Getting Started with LocalDNS.wtf

LocalDNS.wtf is a local development DNS + reverse proxy + process manager for macOS/Linux. It maps custom .local domains to local ports, manages service lifecycles, and provides a web dashboard.

How It Works

1. A DNS server listens on 127.0.0.1:5354 for all .local queries
2. macOS resolver at /etc/resolver/local points .local lookups to that DNS server
3. An HTTP reverse proxy on port 80 routes requests by Host header to the correct local port
4. A process manager starts/stops/monitors the actual app processes
5. A REST API on port 1111 lets the CLI, dashboard, and external tools control everything
6. The web dashboard at http://dns.local provides a visual management UI

Quick Start

1. Install Dependencies

pnpm install
pnpm build

2. Start the Daemon

# Option A: Manual start (for development)
localdns start

# Option B: Install as macOS service (auto-start on boot)
localdns install

3. Add Your First Domain

localdns add myapp.local --cmd "npm start" --port 3000
localdns start myapp.local

4. Browse

Open http://myapp.local in your browser.

Architecture

Browser → .local DNS (port 5354) → 127.0.0.1
Browser → HTTP Proxy (port 80)  → routes by Host → localhost:{port}
CLI     → REST API (port 1111)   → Registry + Process Manager
Dashboard (dns.local)            → REST API (port 1111)

Storage

Port Ranges

Next Steps

• Setup Guide - Detailed installation and configuration
• CLI Reference - All available commands
• Services - Managing local services
• Troubleshooting - Common issues and fixes