Running host applications with localghost¶
localghost run serves an application behind the hub straight from its
checkout: a Django, Vite, PHP, or static site needs no Dockerfile or Compose
file, and an existing Compose project is handed to docker compose up with
the hub wired in first. This page covers detection, ports, options, and
background sessions.
Which command do I use?¶
| You want to… | Use | Who starts the app? |
|---|---|---|
| Serve a checkout without writing any config | localghost run |
Localghost |
| Keep that setup for next time | localghost save (or save --run) |
Localghost, on run |
| Give a name to a server you already started | localghost forward NAME PORT |
You |
| Run a Compose project that already has the labels | localghost run (starts the hub and runs docker compose up for you) |
Localghost, through Compose |
| Same, managing Compose yourself | localghost hub up once, then you run docker compose up |
You, through Compose (the hub must already be running) |
run and forward both produce a NAME.localhost route through the same
Caddy bridge. The difference is ownership: run owns the process and the
route, while forward owns only the route and follows whatever listens on the
port. Details for forwards are under
Forwarding a running server.
Project types¶
Every project has a type. Detection runs automatically from the selected
directory; --type resolves ambiguity or skips detection entirely.
| Type | Detection | Default port |
|---|---|---|
| compose | compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml |
— (Compose owns it) |
| django | manage.py in the project directory |
8000 |
| vite | package.json with a dev script and vite dependency |
5173 |
| astro | package.json with a dev script and astro dependency |
4321 |
| cakephp | bin/cake with a cakephp/cakephp Composer dependency, or a legacy app/Config/core.php + app/webroot/index.php root |
8765 |
| laravel | artisan with a laravel/framework Composer dependency |
8000 |
| php | composer.json, or index.php in public/, web/, htdocs/, www/, or the project root |
8080 |
| html | index.html in the project directory |
8080 |
dockerfile is a ninth type, but it is save-only — see
Saving project setup. Running a Dockerfile
project first needs localghost save --type dockerfile to produce a
Compose file; after that the project is compose.
Within PHP, cakephp and laravel are specializations of php rather than
peers: the most specific match wins, and generic php only fires when neither
framework matches. html is the weakest match of all: it defers to any
other type in the same directory or further up, so a Vite project's
index.html or a docs build inside a Django checkout never claims the run.
Pass --type html to serve such a folder anyway, or --project-root . to
stop the search at the current directory. /inner/ serves
inner/index.html, /inner redirects there, and directories without an
index are listed. Dotfiles and anything inside a dot-directory, such as
.env or .git/, are never served.
Open pages update when a file they use changes: an edited stylesheet the page
links is swapped in place, keeping scroll position, form input and script
state, and any other change the page loaded reloads it. Changes to files the
page never loaded, such as another page, are ignored. Each page loads
/__localghost/reload.js, which holds a connection open; the folder is only
checked while one is, skipping dot-directories and node_modules. A
Content-Security-Policy that allows 'self' scripts lets it run, but a
nonce-only policy blocks it, and the page simply does not reload. Over plain
HTTP each open page holds one of the browser's six connections to the site,
so many tabs of one site can stall; trusted HTTPS removes that limit. Every
other type resolves to the nearest match along the
upward search.
If more than one type is detected at the same directory (for example, a
Django project that also has a package.json with Vite, or a directory
holding both a Compose file and a framework), use --type to resolve the
ambiguity:
Localghost searches upward from the selected directory to the nearest project
root, stopping at the search boundary described below. This means it can be
run from directories such as webroot, public, or a nested source package
without naming the application after that directory. The detected root
supplies the default public name and application configuration; a framework
may still use a different working directory for its server process.
Usage¶
Run your app; Localghost starts the hub when needed:
The app is served at NAME.localhost, where NAME is the project folder's
name. A folder whose name says what it holds rather than which project it is
(web, www, site, app, frontend, client, ui, backend,
server, api, apps, packages, src, dist, build, out or
public) takes the name of the folder above it instead, so
cineshelf/web serves at cineshelf.localhost. That only happens inside a
repository, and never past its root or a folder holding .localghost.toml,
so projects/web with nothing above it tying the two together stays web.
A project localghost already remembers under its folder name keeps it.
save writes the name into .localghost.toml for a folder like this, and
--name or [run].name always wins. Compose projects keep Compose's own
naming, so docker compose agrees on the project.
A compose type hands the project straight to docker compose up after
starting the hub. Because Compose owns the application's configuration, the
host-only options (--type for a framework, --port, and a -- command)
are rejected when a compose type is selected or detected:
Before starting anything, a Compose run checks that the project is actually
wired to the hub — the localghost network is present, and at least one
service carries traefik.enable=true on that network. A project that has not
saved its setup is refused with an exact localghost save next action, rather
than starting and printing a URL that would never route. save --run
runs the same check before starting, so a misconfigured save is caught
immediately rather than deferred to the next run. A saved
type = "compose" resolves ambiguity but never bypasses this routing check.
Configured runs¶
Projects may keep repeatable run settings in .localghost.toml:
Or, to run something other than the type's own server:
| Key | Type | Meaning |
|---|---|---|
type |
one of the eight types run --type accepts (not dockerfile, which is save-only) |
Resolves otherwise ambiguous detection, exactly like --type. Detected when omitted. |
name |
string | Public name, serving the app at NAME.localhost. Defaults to the project root's name, or its repository's for a generic folder name like web (see Usage). localghost, trust, and traefik are reserved for the hub. |
root |
path, relative to the config file | Treat this directory as the project root instead of searching. See Project root and configuration discovery. |
port |
integer, 1–65535 | Host HTTP port. The type's default is used when omitted, except alongside command, where it is required. |
command |
array of strings | Argv to run instead of the type's own server. {port} is replaced with the selected port, and lets the run walk past a busy one (see Custom command). |
isolate |
boolean | Run the application in its own network namespace, so it keeps its port whatever else holds it. Linux with pasta only; elsewhere the run warns and goes ahead without. |
Setting command makes the run a custom one: the type is reported as custom,
type has no effect, and port becomes required because there is no framework
default to fall back on. Set one or the other, not both.
Every key is optional, and an unrecognised key is an error rather than being
ignored — a misspelled setting fails loudly instead of silently doing
nothing. Two retired keys are rejected with their migration: [run].framework
(rename it to type) and [run].mode, which has no direct equivalent — the
error names the migration (type = "compose", or remove the key and let
detection choose).
Settings are layered: a command-line option wins over .localghost.toml,
which wins over automatic detection. Use --config PATH to read a different
file.
A .localghost.local.toml beside it adds personal settings without touching
the shared file: each [run] key it sets replaces the shared one, and the rest
are kept. It works on its own too, with no .localghost.toml at all. Under
--config PATH, the overlay is the same name with .local before the
extension. save --local writes it (see
Personal settings).
localghost save writes this file without running, while save --run writes
the same setup and then starts it:
uvx localghost save --port 8080 -- ./server --port 8080
uvx localghost save --port 8080 --run -- ./server --port 8080
It refuses to overwrite an existing .localghost.toml unless --extend is
given, keeps a .bak copy when it does rewrite one, and prints the
configuration without writing anything under --dry-run.
Project root and configuration discovery¶
The project root supplies the hostname and anchors configuration. Resolution tries each of the following in order, and the first match wins:
--project-root PATH— resolved relative to the process working directory.[run].rootin a discovered.localghost.toml— resolved relative to the directory holding that config file.- The directory holding the discovered
.localghost.toml, when one is found but sets noroot. - The nearest ancestor of
-C/--directory(inclusive) at which a type is detected — the default, unbounded-by-config search.
Both --project-root and [run].root accept .., so a config file at
myrepo/tools/.localghost.toml can set root = ".." to point at myrepo.
When the root is pinned by one of the first three rules, type detection runs
only at that directory rather than walking upward; a pinned root with no
detectable type is an error naming the available types.
.localghost.toml itself is discovered by the same upward search --type
detection uses, but only once that search has found a VCS marker. Without
one, config discovery does not walk at all: only the invocation directory
(-C) is a candidate, because [run].command is arbitrary argv that run
executes, so a config file must be inside a project boundary to be trusted.
--config PATH overrides discovery entirely, and that file's directory then
anchors the root under rule 3.
Search boundary. Type detection walks upward from -C, stopping after
the first directory containing .git, .hg, or .svn — that directory is
itself included as a candidate — and never reaches $HOME or above: even
when $HOME holds a VCS marker, $HOME itself and everything above it,
including the filesystem root, are never candidates. Config discovery uses
that same bounded walk when a VCS marker is present, but — as above —
does not walk at all without one. A stray ~/package.json therefore cannot
be adopted as a project's type, and a forgotten ~/.localghost.toml cannot
be adopted as its config.
The status bar¶
A foreground localghost run pins the public URL to the bottom row of the
terminal, so it stays visible while the application's own output scrolls
above it:
The bar shows each URL as its bare host to save room. In a terminal that
supports hyperlinks (OSC 8), the host is a link to the full https://
address. The full URLs are also printed above the bar before the application
starts, and those are hyperlinks too.
The bar appears immediately, before the hub is reconciled, and names the step
it is waiting on — starting hub while the hub comes up, then starting once
the application's own process has been launched.
The spinner and the dimmed URL mean the application is not answering yet. Localghost probes it — a host application on its port, a Compose project through the route itself — and the bar switches to a solid URL once the first probe succeeds, so the bar doubles as the readiness signal rather than inviting a click that would return a gateway error.
The probe resolves localhost and tries every address it yields, so a server
that bound only the IPv6 loopback is seen. On a native Linux daemon an
application answering only on loopback is not reported ready until the relay
that makes it reachable is up (see
Loopback-bound servers).
If something is already serving on the application's port when the run
starts, Localghost refuses to start rather than launching an application onto
a URL that would serve whatever was already there. On Linux the error names
the process holding the port and its working directory, and it always says
how to get past it: stop that process, or choose another port with --port.
When that process is in your project (a dev server you started yourself), it
also suggests localghost forward NAME PORT to give the running server its
hostname instead; see Forwarding a running server.
The bar is drawn with a terminal scrolling region that covers every row except
the last, which leaves the terminal's own scrollback intact: scrolling up
still reaches everything the application printed. This holds inside terminal
multiplexers as well — it has been checked against VTE-based terminals, tmux,
and zellij, in each case reaching the first line the application printed. It is skipped when output is
not a terminal, when TERM is unset or dumb, when the window is narrower
than 40 columns or shorter than 3 rows, and on --detach and --dry-run
runs. Pass --no-status-bar to turn it off:
Turning the bar off, or piping the output, does not turn off the watching. Whether the application came up somewhere the hub can reach is a fact about the run, so the relay and the unreachable-application diagnosis below happen either way.
Detached runs and sessions¶
--detach records the process outside the project directory and keeps its
output in Localghost's state directory:
localghost run --detach
localghost sessions list
localghost sessions list --running
localghost sessions list --json
localghost sessions logs NAME
localghost sessions logs NAME -f
localghost sessions attach NAME
localghost restart NAME
localghost sessions stop NAME
localghost sessions stop --all
Press Ctrl+Z in a foreground run to leave the application running and get your
shell back. Closing the terminal does the same. The application never notices,
because a run started from a terminal lives in a small background process with
the application on a pseudo-terminal, and your terminal is only connected to it.
localghost sessions attach NAME, or plain localghost run in the project,
brings it back. A foreground run is recorded and logged like any other, so
sessions, sessions logs, sessions stop, and restart work on it from
another terminal.
Ctrl+C and Ctrl+Z are not passed to the application, and everything else you
type is. Attaching to an application started with --detach shows its output
and honours both keys, but it has no terminal to type into; use
restart NAME --foreground when you need one. restart brings a project back
the way you last left it, so a run you detached comes back with --detach.
A run with no terminal, such as one in a script or with its output piped, stays
in its own process and ends with it, so it cannot be left behind by accident.
Set LOCALGHOST_LEGACY_RUN=1 to run that way from a terminal too, if an
application misbehaves on a pseudo-terminal.
Sessions are addressed by project name; a session ID works too, and wins
when both match. sessions list shows every remembered project, running
or not; --running or --stopped narrows it to one state. --json gives
each project's registry entry with its state and its newest session record
under session.
Starting a project removes that name's stopped records. A hostname can only
be served once, so run refuses to start a project whose name is already
served from another directory — a second worktree of the same repository,
say — and suggests --name.
Session records live in ${XDG_STATE_HOME:-$HOME/.local/state}/localghost/sessions
(or $LOCALGHOST_STATE_DIR when set). A host session's liveness is probed by
its recorded process ID and a Compose session's by docker compose ps.
sessions logs reads a host run's captured file and delegates Compose runs to
docker compose logs; add -f to keep following either kind of session.
sessions stop asks a host process to exit with SIGTERM, then force-quits it
with SIGKILL after a ten second grace period, returning as soon as it exits;
it reports an error and keeps
the record if the process somehow survives. A session that exits on its own
loses its bridge the next time localghost runs, and its record (with its log)
stays until the project runs again or is forgotten. localghost hub down
continues to control only the hub.
The app is available at https://my-django-project.localhost. Press Ctrl+C to
stop it.
Forwarding a running server¶
run starts the application itself. When something else has to own the process,
such as a debugger, an IDE run configuration, a process manager or a plain
docker run, give its port a hostname instead:
localghost forward api 5173 # api.localhost -> this host's port 5173
localghost forward api 5173 --detach # leave it running in the background
localghost forward api # a forward Localghost remembers: its last port
Both the name and the port are required the first time, because nothing ties a
listening port to the current directory. forward NAME alone reuses the port of
a forward Localghost remembers. --no-status-bar turns the status bar off, as
for run. A forward has no directory and starts nothing: Localghost owns only
its own small background process and the bridge, and never signals your server.
In a terminal, forward follows the forward's log under the same status bar as
run, showing the URL and the port it reaches. Ctrl+C stops the forward and
leaves your server alone. Ctrl+Z, or closing the terminal, disconnects and the
forward keeps running; localghost sessions attach NAME, or plain
localghost forward NAME, reconnects. Without a terminal, such as in a script,
forward behaves as --detach. If the forward's background process ends
without being asked to, the following terminal says it ended unexpectedly and
points at localghost sessions logs NAME.
The route is up while a matching server listens on the port, and the forward lasts until you stop it. Five seconds after nothing is listening the route goes down and the hostname shows its ghost page ("is waiting"), then comes back on its own when a server returns, so stopping and restarting a debugger needs nothing from you. If nothing is listening when the forward starts, it says so:
On Linux the forward pins the working directory of the first process it sees holding the port, so a different project that later takes the port is not served under this name:
Where the holder cannot be read (another user's process, docker run -p, or a
platform without /proc), it follows the port instead and says so:
A loopback-only server is reached through the same relay a host run uses; see Loopback-bound servers.
forward refuses ports Localghost already routes: the hub's own HTTP and HTTPS
ports, the port of a running run
(5173 is blog's port; it is already at blog.localhost) or of another forward
(5173 is already forwarded as web.localhost), and any port published
by a container on the localghost network. It also refuses a name that a
remembered project already uses; pick another name, or drop the project with
localghost sessions forget NAME. A running forward asked for a different port
refuses too; restart keeps a forward's port, so to change it run
localghost sessions stop NAME and then localghost forward NAME PORT.
The name works the other way too. localghost run refuses a name that a running
forward serves (blog.localhost is forwarded to port 5173; stop it with:
localghost sessions stop blog). It takes over the name of a stopped forward,
saying Replacing the stopped forward blog (port 5173)., and the project's entry
replaces the forward's, so forward blog then needs a port again.
localghost restart NAME restarts a forward, and sessions list shows it with
mode forward and → port N in place of a directory. While the route is down
it reads running (waiting), or running (failing) when no route can be made,
for example because the server listens only on loopback and no relay is
possible. In sessions list --json a forward has mode: "forward",
type: "forward" and directory: null, and its session's route field says
where the route stands: up (or up: DIRECTORY once a holder is pinned),
waiting: REASON, failing: REASON, or stopped once the forward was asked to
stop; it is empty for the moment before the forward first checks the port.
sessions stop NAME signals only the forward's own process.
Custom port¶
Override the detected port when the default is already in use:
A port counts as free only when it can be bound over both IPv4 and IPv6. If
it is free it is used directly. If it is occupied and --port was given
explicitly, an error is raised naming what holds it. Without --port, the
next free port is chosen automatically, and a warning says which port was
passed over and, on Linux, which process and working directory hold it. That
matters because an application that ignores the port it is given starts from
its own default, meets the same squatter, and picks its own replacement.
Explicit type¶
Skip auto-detection and specify the type:
--framework is no longer accepted as a CLI option, nor [run].framework in
.localghost.toml; use --type and [run].type.
Custom command¶
Run an arbitrary process with a custom port:
Write {port} where the command takes its port and the port becomes flexible:
if it is busy, the run walks to the next free one, substitutes that, and warns
about the one it skipped, whether the port came from --port or
.localghost.toml. A command that names its port itself, as above, cannot be
moved, so a busy port is an error instead. save keeps the port you asked for,
not the one a busy run walked to.
How it works¶
For host types, localghost run creates an ephemeral Caddy bridge container
on the localghost network. The Caddy container forwards requests from the
hub to the host process via host.docker.internal, handing on the client
address and scheme Traefik recorded in X-Forwarded-For and
X-Forwarded-Proto rather than its own view of that internal hop. When the
foreground process exits, the bridge is removed automatically.
If a previous localghost run was interrupted and left a stale bridge
container, it is detected and removed automatically before the new one
starts.
For the compose type, the bridge is not a container: it is the routing
labels and localghost network membership on the application's own service,
which localghost save writes.
Django runner detection¶
For Django projects, localghost selects the Python runner in this order:
uv run pythonifuv.lockis presentpoetry run pythonifpoetry.lockpipenv run pythonifPipfileorPipfile.lock- The active
VIRTUAL_ENVpython if set .venv/bin/pythonif the directory exists- Errors if none of the above are found
JavaScript package-manager detection¶
For Vite and Astro projects, localghost run first uses the packageManager
field in package.json when it is present. Otherwise, lockfiles are checked in
this priority order: bun.lock/bun.lockb, pnpm-lock.yaml, yarn.lock, then
package-lock.json/npm-shrinkwrap.json; the first detected manager whose
executable is installed is used. More specific lockfiles are preferred because
they are stronger signals of intentional package-manager use. This makes
projects with more than one lockfile deterministic while allowing an
unavailable higher-priority manager to fall back to another detected manager.
Declare packageManager in
package.json when a specific manager must be used; a declared manager is not
silently replaced if its executable is missing. Localghost does not inspect
lockfile contents or timestamps, so the priority is a fallback heuristic rather
than proof of which lockfile is current.
PHP runner detection¶
Modern CakePHP applications run bin/cake server from the application root.
When bin/cake is not executable, Localghost uses php bin/cake.php if that
entry point is present. Legacy CakePHP 2 applications run PHP's development
server from app/webroot, while their hostname remains derived from the
application root. Laravel applications run php artisan serve from the
application root. Plain php projects run PHP's built-in server
(php -S 0.0.0.0:{port}) from their docroot — the first of public/,
web/, htdocs/, www/ containing index.php, otherwise the project root
itself.
PHP framework detection requires both framework-specific files and Composer
dependency metadata where modern projects provide it. A generic
composer.json, public, or webroot directory alone selects the generic
php type, not a specific framework runner.
A bare index.php at a directory with nothing else is treated as a probable
docroot rather than a project root: the search continues upward, and that
directory is used only if nothing stronger is found above it. This keeps
app/webroot from shadowing a CakePHP root one level up, while a
self-contained services/billing/composer.json inside a monorepo still stays
at billing rather than climbing to an unrelated top-level manifest.
Wrapper scripts¶
Localghost passes --port through the package manager, with --strictPort for
Vite, so the dev server takes the port the bridge points at rather than
wandering off it. Where no relay is available it also passes --host 0.0.0.0
(see Loopback-bound servers). If the dev script
calls another script, that wrapper must forward the arguments or they are
silently discarded, and localghost warns when it can see a dev script that
does not invoke the tool itself.
For example:
The wrapper should pass its arguments to the nested package script:
The "$@" passes Localghost's arguments through to Vite. Without it the server
starts on its own default port, and binds loopback where localghost would have
asked for a wider interface.
A server that comes up on another port anyway is not left behind a URL that cannot resolve. On a native Linux Docker daemon the run relays the planned port to it when it can tell which listener is the application; otherwise it stops with an error naming every address the application is listening on (see troubleshooting).
Loopback-bound servers¶
The bridge reaches the host over the Docker gateway address, which a server
bound to 127.0.0.1 or [::1] does not accept. On Linux, run notices when the
application comes up on loopback alone and relays to it from the gateway address
only, on the same port, so the bridge reaches it while the LAN does not. Because
that relay can stand in for a wider bind, localghost does not ask Vite or Astro
for --host 0.0.0.0 where one is available.
When a relay starts, the run says so: Application bound 127.0.0.1:5173;
relaying from 172.17.0.1:5173 so the hub can reach it.
A detached run relays too: a small localghost process leads the session's process group, raises the relay, and notes it in the session log.
Where no relay can be raised, localghost passes --host 0.0.0.0 instead. On
Linux with a native Docker daemon, an application that still comes up on
loopback is then stopped, and the run ends with an explanation rather than
leaving it waiting behind a URL that cannot resolve.
A relay needs the Docker gateway to be an address of the host itself, which it
is only for a native daemon. Docker Desktop for Linux and rootless Docker report
a gateway that lives inside a VM or a user namespace, so no relay is raised
there and Vite and Astro are still asked for --host 0.0.0.0. Those
installations proxy the bridge's route to the host through a process that
reaches loopback, so a loopback bind is left alone rather than refused.
Isolated runs¶
Two projects that both want port 8000 cannot share the host's loopback, and a
project made of several servers -- Django talking to a Vite dev server, say --
breaks if one of them is moved to a free port the others do not know about.
--isolate gives the whole run its own network namespace instead:
localghost save --isolate keeps it, as isolate = true:
Everything the command starts shares the namespace's own 127.0.0.1, so each
server keeps its usual port and they find each other as they always do. Only
port comes out, on host loopback at a port the kernel picks from its
ephemeral range (32768–60999 on Linux by default), so an isolated run never
takes a port such as 8000 or 5173 that another application might want. The
route points there, and the run lists it as the host port beside the isolated
one; it changes from run to run, so use the public URL rather than the number. The application still reaches the
internet; services on the host's loopback, such as a local database, are
reached over the namespace's gateway address rather than 127.0.0.1.
When a port is already taken, the error or warning says so and, where
isolation is available, suggests retrying with --isolate.
Isolation needs Linux and pasta (the passt package),
which provides the namespace's networking without root. Where either is missing
the run warns and continues with the host's ports, so a shared
.localghost.toml keeps working on every machine.
Notes¶
- The host process must be reachable from the Caddy bridge: on a Docker-reachable
interface, or on loopback where
runcan relay to it (see Loopback-bound servers). - The bridge container uses the pinned
caddy:2.11.4-alpineimage. - Django's
ALLOWED_HOSTSandCSRF_TRUSTED_ORIGINSmay need updating for the.localhosthostname — localghost warns about missing values when possible.