Local Hoster

Local Hoster is a small Node.js command-line tool that gives local development projects stable URLs such as https://dashboard.localhost. It registers temporary HTTP and HTTPS reverse-proxy routes through Caddy, starts the chosen development command on a deterministic port, and removes its routes when the command exits.

Current release: 1.0 (1.0.0 in package metadata). See CHANGELOG.md for release notes.

Features

• Memorable *.localhost URLs without editing /etc/hosts
• Local HTTPS through Caddy's internal certificate authority
• Stable project-to-port mapping across restarts
• Runtime route registration through Caddy's local admin API
• Automatic route and TLS-policy cleanup
• Hostname validation and clear setup errors
• Zero runtime npm dependencies
• Automated tests for hostname, port, route, and cleanup behavior

Requirements

• macOS or another Unix-like system supported by Caddy
• Node.js 18 or newer
• Caddy installed and running with its admin API on localhost:2019

Quick start

From code/:

npm link
brew install caddy
touch /opt/homebrew/etc/Caddyfile
brew services start caddy
caddy trust

In the project you want to run, add a hostname and wrap its development command:

{
  "localhost": "myapp",
  "scripts": {
    "dev": "localhoster astro dev"
  }
}

Then run npm run dev and open https://myapp.localhost.

Verify the source

npm run check
npm test

Project structure

├── code/
│   ├── index.mjs
│   ├── package.json
│   └── test/localhoster.test.mjs
├── AGENTS.md
├── ARCHITECTURE.md
├── BUILDING.md
├── CHANGELOG.md
├── CONFIGURATION.md
├── CUSTOMIZATION.md
├── DECISIONS.md
├── DEPLOYMENT.md
└── SECURITY.md

Start with ARCHITECTURE.md to understand the Caddy configuration flow and SECURITY.md before changing the admin endpoint or process behavior.

License

MIT. Keep the included license notice with substantial copies of the source.

Local Hoster is a zero-runtime-dependency Node.js CLI that coordinates a project command and a local Caddy reverse proxy. The executable is localhoster; the public product name is Local Hoster.

System flow

flowchart TD
  project["package.json<br/>localhost: myapp"] --> cli["Local Hoster"]
  command["Development command"] --> cli

  cli --> validate["Validate hostname"] --> port["Choose stable port"]
  port --> child["Start child process<br/>localhost:PORT"]
  port --> caddy["Configure Caddy"]
  caddy --> http["HTTP route"]
  caddy --> https["HTTPS route"]
  caddy --> tls["Local TLS certificate"]

  browser["Browser"] --> url["https://myapp.localhost"]
  url --> caddy --> child

  stopped["Ctrl+C or child exit"] --> cleanup["Remove HTTP, HTTPS,<br/>and TLS objects"] --> status["Exit with child status"]
  child -. lifecycle .-> stopped

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef service fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef output fill:#211f1c,stroke:#5b5143,color:#d2c4aa

  class project,command,browser,stopped entry
  class cli core
  class validate,port,caddy,cleanup service
  class child,http,https,tls,url,status output

Components

Command entry point

code/index.mjs parses help and version flags, reads the current project's package.json, validates its localhost field or name, computes a stable port, and starts the requested development command.

Hostname and port rules

Names are normalized to lowercase and suffixed with .localhost. Each label must contain letters, numbers, or internal hyphens. A deterministic string hash maps the hostname into ports 10000–59999. This makes the same project choose the same port after restarts; it does not reserve the port globally, so ordinary port-conflict handling still applies.

Caddy adapter

The CLI reads Caddy's JSON configuration from the local admin API, ensures HTTP and HTTPS servers exist, adds tagged reverse-proxy routes, and installs a tagged internal-TLS automation policy. It then loads the updated configuration in one request.

Every object receives a stable @id. Cleanup deletes all three objects by ID, avoiding stale routes and certificate policies after the development command exits.

Child process lifecycle

The requested command is spawned directly, without a shell, with --port <stable-port> appended. Standard input and output are inherited. When the child exits, Local Hoster removes its Caddy configuration and returns the child's exit status. On SIGINT or SIGTERM, it cleans up before forwarding the signal to the child.

Tests

code/test/localhoster.test.mjs uses Node's built-in test runner. It covers hostname validation, deterministic ports, command arguments, generated Caddy configuration, and cleanup requests without requiring a live Caddy process.

Trust boundaries

• The project directory controls the hostname and command.
• Caddy's admin API is assumed to be local and owner-controlled.
• The spawned command is supplied by the user and is never passed through a shell.
• Local HTTPS uses a local certificate authority; it is not public TLS.

Replaceable pieces

The hostname validator, port strategy, Caddy adapter, and child-process runner are explicit functions. You can replace Caddy with another proxy, add a port-availability check, support commands with different port flags, or port the workflow to another language while preserving the product behavior.