> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How HTTPS hosting works

> How Boat routes a public HTTPS request to a port in your sandbox.

## What `host <port>` does

1. The sandbox asks the Boat backend for a stable public route for that sandbox and port.
2. The backend registers a subdomain. It uses the current machine address of the sandbox and the port that you asked for.
3. Boat prints the URL.

The hostname is the sandbox subdomain plus the port.

```text theme={null}
https://<sandbox-subdomain>-<port>.on.boat.dev
```

## How a request reaches your app

1. Boat terminates TLS for `on.boat.dev`.
2. Boat proxies the request to the sandbox, on the port that you exposed.
3. Your app answers from inside the sandbox.

The public HTTPS route sits in front of your app. It connects to the sandbox address, not to the loopback interface. An app on `0.0.0.0` answers there directly.

## Services that listen on localhost

An app on `localhost`, `127.0.0.1` or `::1` only does not answer on the sandbox address. Declare it with `--localhost`:

```text theme={null}
browser -> route -> sandbox address:<port> -> Boat relay -> 127.0.0.1:<port> or [::1]:<port>
```

* The sandbox relays the port to `127.0.0.1`, then to `::1` if nothing answers on `127.0.0.1`.
* The relay passes raw TCP, so HTTP, WebSockets and hot reload work.
* The relay stays on after a stop, a resume and an agent upgrade. A fork does not keep it.
* Every host call sets the value again. Hosting the same port without `--localhost` turns the relay off and closes its open connections.
* `host hide <port>` and making the port private also turn the relay off.
* Do not use `--localhost` for an app on `0.0.0.0`. The relay then holds the port, and the app cannot start again on it.

```bash theme={null}
npm run dev -- --port 5173          # Vite listens on localhost by default
host 5173 --localhost
```

<Note>
  Some dev servers reject requests for host names they do not know. For Vite, add `.on.boat.dev` to `server.allowedHosts`.
</Note>

## Credentials

The sandbox authenticates to the Boat backend with its machine token. The backend registers the route. This keeps routing credentials out of the sandbox environment. The `host` CLI can still create, list and remove routes.

## The `on.ascii.dev` domain

<Note>
  Boat serves every hosted address under `on.boat.dev` and `on.ascii.dev`, with the same label. `on.ascii.dev` is the name from before the rename. So `SUBDOMAIN-3000.on.ascii.dev` and `SUBDOMAIN-3000.on.boat.dev` are the same route. Links that you shared as `on.ascii.dev` keep working until that suffix is retired (see [Migrating from Box](/migrating-from-box)). Change the links that you publish to `on.boat.dev` when convenient.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.