Complete installation and configuration guide for LocalDNS.wtf on macOS and Linux.

Setup Guide

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. Register Dashboard Domain

localdns add dns.local --port 1111 --cmd "cd apps/dash && pnpm dev"
localdns start dns.local

4. Access Dashboard

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

macOS Service Installation

Install as Launch Agent (User)

localdns install

This creates a plist at ~/Library/LaunchAgents/com.localdns.daemon.plist and loads it.

Install System-Wide (Requires sudo)

sudo localdns install --system

Service Management

Using launchctl:

# Start
launchctl start com.localdns.daemon

# Stop
launchctl stop com.localdns.daemon

# Unload (remove from auto-start)
launchctl unload ~/Library/LaunchAgents/com.localdns.daemon.plist

# Check status
launchctl list | grep com.localdns.daemon

Using LocalDNS CLI:

localdns start   # Start daemon
localdns stop    # Stop daemon
localdns status  # Check status
localdns doctor  # Run diagnostics

Development Workflow

Running Locally

Terminal 1: Start Daemon
```
localdns start
```
Terminal 2: Start Dashboard (if not auto-started)
```
cd apps/dash
pnpm dev
```

Terminal 3: Use CLI

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

Production Setup

Build everything:
```
pnpm build
```
Install as service:
```
localdns install
```

Register domains:

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

Verify:
```
localdns doctor
localdns status
```

Architecture

┌─────────────────┐
│   Browser        │
│  dns.local       │
└────────┬─────────┘
         │
         ▼
┌─────────────────┐
│  Daemon (80)    │  ← Proxy server
│  Express.js     │
└────────┬─────────┘
         │
         ├──► API (1111) ──► Registry, Config
         │
         └──► Proxy ──► localhost:3001 ──► Next.js Dashboard

Next Steps

Run localdns doctor to verify setup
Check localdns status for current state
See the Troubleshooting Guide for common issues

Setup Guide

On this page