Skip to content

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:

uvx localghost run --type django
uvx localghost run --type compose

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:

cd my-django-project
uvx localghost run

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:

uvx localghost run --type compose

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:

[run]
type = "django"
name = "my-app"
port = 8080

Or, to run something other than the type's own server:

[run]
name = "my-app"
port = 8080
command = ["./server", "--port", "{port}"]
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:

  1. --project-root PATH — resolved relative to the process working directory.
  2. [run].root in a discovered .localghost.toml — resolved relative to the directory holding that config file.
  3. The directory holding the discovered .localghost.toml, when one is found but sets no root.
  4. 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:

 localghost  ⠹ starting hub  my-django-project.localhost   Ctrl+C to stop  ·  Ctrl+Z to detach

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:

localghost run --no-status-bar

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:

nothing is listening on 5173 yet; api.localhost will serve it once something does

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:

port 5173 is held by ~/dev/other (pid 41022); not routing api

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:

cannot tell which process owns 5173; api.localhost will serve whatever listens there

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:

uvx localghost run --port 9000

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:

uvx localghost run --type vite

--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:

uvx localghost run --port 8080 -- my-custom-server --port 8080

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.

uvx localghost run --port 8000 -- just dev {port}

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:

  1. uv run python if uv.lock is present
  2. poetry run python if poetry.lock
  3. pipenv run python if Pipfile or Pipfile.lock
  4. The active VIRTUAL_ENV python if set
  5. .venv/bin/python if the directory exists
  6. 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:

{
  "scripts": {
    "dev": "./scripts/dev.sh",
    "dev:vite": "vite dev"
  }
}

The wrapper should pass its arguments to the nested package script:

npm run dev:vite -- "$@"

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:

uvx localghost run --isolate

localghost save --isolate keeps it, as isolate = true:

[run]
port = 8000
command = ["just", "dev"]
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 run can relay to it (see Loopback-bound servers).
  • The bridge container uses the pinned caddy:2.11.4-alpine image.
  • Django's ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS may need updating for the .localhost hostname — localghost warns about missing values when possible.