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

# Host with box

> Run a service inside a Box and expose it on a stable public HTTPS URL.

## Quick path

1. Enter a Box:

```bash theme={null}
box ssh <box-id>
```

2. Inside the Box, start your app on an explicit port.

<Warning>
  Your app must bind to `0.0.0.0`. If it only listens on `localhost` or `127.0.0.1`,
  the hosted HTTPS URL will not be able to reach it.
</Warning>

3. Inside the Box, run this command to start hosting your app:

```bash theme={null}
host 3000 --title "App preview"
```

4. Open the public HTTPS URL printed by `host`:

```text theme={null}
https://<box-subdomain>-3000.on.ascii.dev
```

If the port is protected, the usable URL includes a `_token` query parameter:

```text theme={null}
https://<box-subdomain>-3000.on.ascii.dev?_token=<access-token>
```

<Info>
  A fresh `host <port>` URL is public unless you pass `--private`. If the same Box port
  was already hosted with protected access, it stays protected and the URL keeps its
  existing `_token`.
</Info>

<Info>
  If you want the process to survive after your SSH command exits, start it as a
  detached process before hosting the port.
</Info>

## Host CLI reference

The `host` CLI runs inside a Box and exposes services from that Box on public HTTPS URLs.

<Warning>
  The service you expose must listen on `0.0.0.0`, not only on `localhost` or `127.0.0.1`.
</Warning>

### `host <port>`

Expose a running service on a stable HTTPS URL:

```bash theme={null}
host 3000
host 3000 --title "Login preview"
host 3000 --private
```

The command opens the firewall for that port, registers an HTTPS subdomain, and prints
the URL. Calling it again for the same port returns the same URL.

| Option            | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `--title <title>` | Set the display title for the hosted port.                        |
| `--private`       | Require the generated `_token` query parameter to access the URL. |

By default, a fresh `host <port>` command creates a public URL. Protected access starts
when you pass `--private`, or when the same Box port already has a saved access token.
That protection is sticky: hosting the same port again returns a URL with the same
`_token` query parameter.

### `host list`

Show hosted ports for the current Box:

```bash theme={null}
host list
```

Protected ports are shown as `(gated)`. `host list` does not print the access token.
Use `host url <port>` to print the full URL with `_token=...`.

### `host url <port>`

Wait until the HTTPS URL is ready, then print it:

```bash theme={null}
host url 3001
```

For a protected port, this prints the full token-gated URL:

```text theme={null}
https://<box-subdomain>-3001.on.ascii.dev?_token=<access-token>
```

This is useful when one service needs another service's public URL:

```bash theme={null}
BACKEND_URL=$(host url 3001)
```

### `host hide <port>`

Take down the public URL:

```bash theme={null}
host hide 3000
```

This closes public access and unregisters the HTTPS route. It does not stop the local
server process. Stop the server separately when you are done. Access tokens are preserved,
so hosting the same port again keeps existing protected links valid.

To get an ungated URL after a port has become protected, host a different port that does
not already have a saved access token.