Metadata-Version: 2.4
Name: localghost
Version: 3.2.1
Summary: Localghost serves local applications at friendly .localhost URLs
Keywords: localghost,localhost,docker,compose,traefik,development,proxy
Author: SmileyChris
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Dist: click>=8.2,<9
Requires-Dist: keyring>=25.6,<26
Requires-Dist: rich>=13.9,<16
Requires-Dist: ruamel-yaml>=0.18.10,<0.20
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/SmileyChris/localghost
Project-URL: Documentation, https://smileychris.github.io/localghost/
Project-URL: Repository, https://github.com/SmileyChris/localghost
Project-URL: Issues, https://github.com/SmileyChris/localghost/issues
Description-Content-Type: text/markdown

# localghost

Localghost gives local servers friendly `.localhost` URLs instead of port
numbers:

- `https://storefront.localhost`
- `https://admin.storefront.localhost`
- `https://blog.localhost`

Just a single local hub routing all your development apps by hostname.

```
          ▒█████████████▒
        ███▒           ▒███░
      ▓██░               ░███           ██                          ██
     ██▒                   ▒██          ██░                         ██░
    ▓█▒                     ░██         ██░ ░█████░  ▒█████  █████▓ ██░
   ░██    ███▓       ████    ▓█▒        ██░░██   ██░▒█▓     ██░ ░█▓ ██░
   ██░    ███▓       ▓███    ░██        ██░░██░  ██░▒██     ██▒ ░█▓ ██░
   ██░         █   █          ██        ██░ ░█████░  ░█████  █████▓ ██░
   ██░         ▒███▒          ██░
   ██                         ██░            ░▒▒                       ░
   ██                 ▓█████████▒            ░▒▒                      ▒▒
   ██              ▓██▒▒▒▒▒▒▒▒██▒    ░▒▒▒▒▒▒ ░▒▒▒▒▒▒░  ▒▒▒▒▒░ ░▒▒▒▒░ ▒▒▒▒▒
  ░██░          ░██▓▒▒▒▒▒▒▒▒▒▒▒██   ░▒▒   ▒▒ ░▒▒  ░▒░ ▒▒░  ░▒░ ░▒░    ▒▒
  ▒████▓     ▒███▒▒▒▒▒▒▒▒▒▒▒▒▒▒██   ░▒▒   ▒▒ ░▒▒  ░▒▒ ▒▒░  ░▒░    ░▒░ ▒▒░
  ██▒▒▒▒▓▓█▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██░    ▒▒▒▒▒▒ ░▒▒  ░▒▒  ░▒▒▒▒░ ░▒▒▒▒░  ░▒▒▒
 ░██▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██  ░▒   ░▒▒
 ░██▒▒▒▒███████▓▒▒▒▒███████▒▒▒▒▒██    ░▒▒▒
  ▒█████▓     ▒█████▓     ▒██████
```

This is local-development infrastructure, not a production proxy. It runs the
hub — a single, loopback-only [Traefik](https://traefik.io/traefik/) container
— as the `localghost` Compose project on the `localghost` Docker network.

## Quick start

You need Docker Engine or Docker Desktop, Docker Compose 5.x+,
[uv](https://docs.astral.sh/uv/getting-started/installation/), and
port 80 available. From an application directory, run:

```sh
uvx localghost run
```

Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, and Docker
Compose projects, starts the shared hub when needed, and keeps the local URL
visible while the application runs. Press Ctrl+C to stop the application.

An unconfigured Compose project asks you to save its routing setup first:

```sh
uvx localghost save --run
```

Save a custom command the same way:

```sh
uvx localghost save --port 8080 --run -- ./server --port 8080
```

Use `save` when you want to persist setup without starting anything:

```sh
uvx localghost save
```

## Hub and background runs

Start or reconcile only the shared hub with:

```sh
uvx localghost hub up
```

Open [http://traefik.localhost](http://traefik.localhost) for its dashboard,
inspect it with `uvx localghost status`, and remove it with
`uvx localghost hub down`.

Run it in the background with `--detach` and manage it afterwards:

```sh
uvx localghost run --detach
uvx localghost sessions list
uvx localghost sessions logs SESSION_ID -f
uvx localghost sessions stop SESSION_ID
```

See [Saving project setup](docs/saving-setup.md) for `.localghost.toml`, Compose
overrides, custom commands, explicit type selection, and safe updates.

To make the same project and secondary-service hostnames available inside a
Tailscale tailnet, see [Tailnet hosting](docs/tailscale.md). It uses an opt-in
tagged gateway and split DNS; the ordinary `.localhost` routes stay local.

## Documentation

The [localghost documentation](docs/index.md) covers application integration,
saving setup, host-native servers, HTTPS, operations, troubleshooting, security,
architecture, and development.

For a local documentation preview, install the development dependencies and run
`uv run zensical serve`.
