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:
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:
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:
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:
To reach the same routes from your Tailscale devices, run:
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
savewrites, 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.