Local Hoster

Local Hoster gives a development project an address such as https://dashboard.localhost. The localhoster command starts your development server and temporarily registers its routes with a local Caddy proxy.

Install

You need Node.js 18 or later, npm and Caddy on macOS or another Unix-like system. After purchase, connect GitHub in Polar, accept the invitation, and clone the customer repository.

From its root, install the command:

npm link
localhoster --help

There are no runtime npm dependencies.

Prepare Caddy

Caddy must be running locally with its admin API at http://localhost:2019. On a Mac using Homebrew, install it:

brew install caddy

If you are starting with a new Homebrew Caddy installation, create its configuration file and start the service:

touch "$(brew --prefix)/etc/Caddyfile"
brew services start caddy

Trust Caddy’s local certificate authority for local HTTPS:

caddy trust

This changes your local certificate trust and may ask for administrator approval. It is for Caddy’s local certificates; the resulting .localhost addresses are for development on your computer.

If you already run Caddy, inspect its configuration first. Local Hoster adds and removes its own tagged routes through the admin API. Keep that API local and under your control.

Give a project its address

Open the package.json of the project you want to run. Add a localhost name and put localhoster before the development command. For an Astro dashboard:

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

Merge those fields into your existing file, keeping the project’s other settings and scripts.

Start the project normally:

npm run dev

Open https://dashboard.localhost. You can also use its HTTP address. There is no /etc/hosts entry to maintain.

When you finish, press Control-C in the terminal running the server. Local Hoster removes its HTTP route, HTTPS route and TLS automation policy when the child exits or it handles a stop signal.

Names and ports

Local Hoster uses the localhost field, falling back to the package name when that field is absent. A dedicated name is useful for scoped npm packages.

Names are lowercased and receive the .localhost suffix. Labels can contain letters, digits and internal hyphens; dots can separate labels. Use a short name such as dashboard or shop-preview.

The same hostname maps to the same port between 10000 and 59999. This is deterministic, but it does not reserve the port. Another service can still occupy it.

Local Hoster appends --port and the selected number to your command. Use it with a development server that accepts that flag. If your server uses another flag, adapt the command or source before wrapping it.

Troubleshooting

If Caddy cannot be reached, check that its service is running and its admin endpoint is enabled locally. An owner-controlled alternative endpoint can be supplied through LOCALHOSTER_CADDY_ADMIN.

If the browser rejects the local certificate, check that caddy trust succeeded for the Caddy instance issuing it. If the server reports a port conflict, identify the existing listener before stopping it or choose another project hostname.

The project name and script live in your own package.json, so Git preserves them. Caddy’s certificate authority and configuration belong to the Caddy installation. Local Hoster does not upload the project or provide a public tunnel.