localdomain

Local reverse proxy with domain management, TLS certificates, and automatic /etc/hosts editing.

Installation

npm install -g localdomain
# or
npx localdomain init

Quick start

# Initialize config (interactive onboarding)
localdomain init

# Start the proxy (ports 80 and 443)
localdomain start

# HTTP-only mode (no TLS)
localdomain start --http-only

# Skip /etc/hosts modification
localdomain start --no-hosts

Commands

| Command | Description | |--------|-------------| | localdomain init | Create config with quick onboarding (-y for defaults) | | localdomain start | Start proxy (80/443) | | localdomain add <pattern> <target> | Add a route (regex → URL) | | localdomain remove <pattern> | Remove a route | | localdomain list | List configured routes |

Configuration: localdomain.config.json

Searched from the project root or parent directories.

{
  "routes": [
    { "pattern": "^app\\.local$", "target": "http://127.0.0.1:3000" },
    { "pattern": "^api\\.local$", "target": "http://127.0.0.1:3002" }
  ],
  "defaultTarget": "http://127.0.0.1:3004",
  "domains": ["app.local", "api.local"],
  "certificates": {
    "dir": "./certs",
    "domains": ["*.local", "localhost"],
    "autoGenerate": true
  }
}

• routes: Regex patterns tested in order (first match wins)
• domains: Domains added to /etc/hosts
• certificates.autoGenerate: Generate certificates when missing

Cross-platform

• macOS: Auto-generated certificates, HTTPS recommended.
• Linux / Windows: A warning is shown. Certificates are not in the system trust store. Use --http-only or manually accept the certificate in your browser.

/etc/hosts

On startup, a dedicated section is added. It is removed automatically on exit (Ctrl+C). On Unix, root may be required: sudo localdomain start.