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 resolves and starts an application; it never writes project files. Use
save to persist the detected setup without starting anything:
Add --run to persist and then start in one step:
The three forms share the same detection and planning:
localghost runresolves and executes;localghost saveresolves and persists; andlocalghost save --runpersists and then executes.
save takes the same --type as run. Detection fills it in when omitted;
an explicit --type is remembered so later runs need no flag.
The project type is auto-detected, searching upward to the nearest project
root. --detach runs the application in the background and
localghost sessions inspects, follows, and stops those sessions. See
Running host applications for the full workflow, custom
ports, explicit type selection, .localghost.toml settings, detached
sessions, and Django runner resolution.
For the complete Compose contract, project naming, secondary services, and saved setup, see Integrate applications and Save project setup.
Optional trusted HTTPS¶
HTTP is always available. To install Localghost's local development root and
enable HTTPS, first install mkcert, then run:
See Security and trust for certificate handling and Operations for lifecycle, status, ports, and upgrades.
Optional tailnet hosting¶
To make the same routes available inside a Tailscale tailnet, enable the
opt-in tagged gateway and split DNS with uvx localghost tailscale enable.
The ordinary .localhost routes stay local. See
Host on a tailnet for setup, trust, and scope.