Skip to content

localghost

Localghost is a loopback-only Docker Compose hub that gives local applications friendly .localhost URLs.

Quick start

Requirements: Docker Engine or Docker Desktop, Docker Compose 5.x (CI tests 5.1.4), uv, and loopback port 80 available.

From an application directory, run:

uvx localghost run

Localghost detects the project, starts the shared hub when needed, and reports the application's .localhost URL. An unconfigured Compose project tells you to save its routing setup and continue with:

uvx localghost save --run

Run, save, or do both

run starts an application without touching project files. save persists the detected setup (.localghost.toml for host apps, a Compose override for Compose projects) and save --run does both. See Save project setup.

Already running the server?

If you start the server yourself, from a debugger, an IDE, or another tool, give its port a hostname instead of letting localghost launch it:

uvx localghost forward api 5173   # http://api.localhost -> this host's port 5173

Localghost only routes to the port; it never starts or stops the server. See Forwarding a running server.

Optional extras

HTTP is always available. For trusted HTTPS, install mkcert and run:

uvx localghost trust install

To reach the same routes from your Tailscale devices, run:

uvx localghost tailscale share

Both are opt-in; the ordinary .localhost routes stay loopback-only.

Where to go next

Use localghost

  • Run host applications: the project types localghost detects, default ports, --type, detached sessions, forwarding a server you started yourself, and .localghost.toml.
  • Save project setup: what save writes, custom commands, and updating a saved setup safely.
  • Integrate applications: the Compose contract behind it all, for hand-written labels and secondary services.
  • Host on a tailnet: the same routes on your Tailscale devices through an opt-in gateway and split DNS.

Operate localghost

  • Operations: hub lifecycle, status, ports, trusted HTTPS, and upgrades.
  • Troubleshooting: symptoms and fixes, starting with the hub status and logs.
  • Security and trust: what the loopback-only design does and does not protect, and how certificates are handled.
  • Architecture: how the hub, bridges, and request path fit together.

Develop localghost

  • Development: repository layout, checks, and releases.