CLI · version 1.0

Local Hoster

A zero-runtime-dependency Node.js CLI that gives every local project one stable URL such as https://dashboard.localhost. Even when the framework’s usual port is already occupied, you keep opening the same memorable address instead of chasing 3001, 3002, or another port.

Node.jsCLICaddy.localhostNode test runner

View on GitHub Download ZIP Read the docs

The full source, tests, and documentation live in the public repository. MIT licensed. Issues and pull requests are off: fork it and make it yours.

Why I built this

I was tired of remembering whether a project was running on 3000, 4321, 5173, or something else. If the usual port was already occupied, the framework would jump to another number and the browser history became even less useful. I wanted the project URL to stay the same regardless.

Local Hoster makes the project name the address. Add one package.json field, put localhoster before the development command, and Caddy gives the project a stable HTTP and HTTPS URL. The implementation stays intentionally small, readable, tested, and free of runtime npm dependencies.

From project name to stable local origin

One command connects the whole local route.

Read and validate the project hostname.
Choose its stable development port.
Register HTTP, HTTPS, and local TLS.
Run the server and clean up on exit.

Features

The same URL every time

When a framework’s usual port is busy, keep opening dashboard.localhost instead of hunting for whichever numbered localhost address it chose.

Local HTTPS

Use Caddy’s internal certificate authority for secure cookies, service workers, WebAuthn, and other HTTPS-only browser behavior.

One-command workflow

Run localhoster astro dev—or another compatible command—and keep the normal development output in the same terminal.

Deterministic ports

Map each validated hostname to the same preferred port across restarts for predictable local origins.

Temporary Caddy config

Zero runtime dependencies

Use Node.js built-ins for files, processes, HTTP requests, validation, and the automated test suite.

Use cases

Daily web development

Give every Astro, Vite, Next.js, or compatible project a short address that remains memorable.

HTTPS feature testing

Exercise secure cookies, service workers, browser credentials, and callback flows on a trusted local origin.

Multi-project workspaces

Run a frontend, API, documentation site, and admin interface behind distinct local hostnames.

Team conventions

Standardize predictable development URLs across repositories and onboarding documentation.

Proxy-learning reference

Study a compact implementation of Caddy’s JSON admin API, internal TLS, and process cleanup.

Local platform foundation

Extend the command into a project registry, dashboard, request inspector, or container-aware development router.

Tech stack

Runtime

Node.js

Reads project metadata, validates hostnames, computes ports, talks to Caddy, and manages the child process.

Reverse proxy

Caddy

Accepts local HTTP and HTTPS traffic and forwards each hostname to its assigned development port.

Dynamic configuration

Caddy admin API

Adds and removes tagged routes and TLS policies without rewriting a shared Caddyfile.

Local addressing

.localhost

Uses the browser-reserved loopback domain so projects need no hosts-file entries or custom DNS server.

Local certificates

Internal CA

Issues development certificates locally after the owner deliberately trusts the Caddy installation.

Verification

Node test runner

Covers hostname rules, stable ports, command arguments, generated Caddy configuration, and cleanup.

CLI

The repository contains the complete command source and tests. Link it locally, add a hostname to any compatible project, and place localhoster before the normal development command.

localhoster astro dev

Run an Astro project behind its configured .localhost hostname.

localhoster vite

Run a Vite project on its stable Local Hoster port.

localhoster --help

Show the compact command guide and package configuration example.

npm test

Verify hostname, port, Caddy configuration, and cleanup behavior.

Screenshots and demos

Local Hoster terminal showing stable HTTP and HTTPS URLs for an Astro project. Open the full-size image.

What’s included

Local Hoster version 1.0 with complete reviewed Node.js source and the localhoster executable
Stable hostname and deterministic-port behavior
HTTP, HTTPS, internal-TLS registration, and symmetric cleanup
Direct process spawning with child exit-status preservation
Automated tests using only Node.js built-ins
A README with the build story, architecture, decisions, customization, configuration, security, and distribution guides, plus AGENTS.md for coding agents
No credentials, personal paths, databases, telemetry, dependencies, or build output

Documentation

The documentation lives in the repository, in one README: setup and usage, why I built it, how it was built, architecture, configuration, deployment, customization, security, the technical decisions, and the changelog. AGENTS.md gives coding agents the project context and operating rules.

Read the README on GitHub →

Why use this

Stop rebuilding the same local-proxy glue for every development machine
Start with a working Caddy configuration lifecycle instead of a fragile shell script
Give an AI coding agent explicit architecture, invariants, tests, and customization guidance
Keep the runtime understandable and free of dependency churn
Own and adapt the complete source for personal, client, or commercial projects
Use the complete source with no subscription or hosted service attached

Customize it

Use the working source as a foundation. Keep it small, change it for your own workflow, or turn it into a different product.

Turn it into the local-dev router your whole team standardizes on: aliases, auto-open links, and a live map of every project URL.
Ship an internal npm or Homebrew package so new hires get pretty local domains on day one.
Add request logging and a small web dashboard that shows which apps are up without digging through terminals.
Support custom port flags and env vars so frameworks that are picky still fit the same workflow.
Replace Caddy behind an adapter and port the idea to another OS or reverse-proxy stack.
Grow it into a companion for Port Pilot: one tool finds ports, the other gives them human names.

MIT license

The repository includes an MIT LICENSE file. You can use, copy, change, publish, distribute, sublicense, or sell the code, including as part of a commercial product.

Keep the copyright and license notice with copies or substantial portions of the code. Third-party dependencies and assets keep their own licenses.

Keep learning

Bootcamp

Use a predictable local setup while you learn to build and ship complete web applications.

Explore Bootcamp →