> ## 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.

# Host CLI reference

> Expose, list, print and hide hosted ports with `boat host` and the in-sandbox `host` CLI.

Two commands expose a service from a sandbox on a public HTTPS URL.

| Command | Runs on |
| - | - |
| `boat host` | Your local computer |
| `host` | Inside the sandbox |

<Info>
  A service on `0.0.0.0` needs no flag. For a service that listens only on `localhost`, `127.0.0.1` or `::1`, pass `--localhost`. See [Services that listen on localhost](/hosting/how-it-works#services-that-listen-on-localhost).
</Info>

## `boat host <sandbox-id> <port>`

Expose a running service without an interactive SSH session:

```bash theme={null}
boat host bx_f7k2q9hd 3000
boat host bx_f7k2q9hd 3000 --title "Login preview"
boat host bx_f7k2q9hd 3000 --private
boat host bx_f7k2q9hd 3000 --public
boat host bx_f7k2q9hd 5173 --localhost
```

The command does these steps:

1. It opens the firewall for that port.
2. It registers an HTTPS subdomain.
3. It prints the URL.

If you run it again for the same sandbox and port, you get 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. |
| `--public` | Clear any saved access token and return a URL that does not require `_token`. |
| `--localhost` | The service listens on localhost only. The sandbox relays the URL to it. |

Use `--json` to print a machine-readable object with `sandboxId`, `port`, `url`, `access`, `isProtected` and `localhost`.

It is a single API call. This makes it the fastest way to host a port from a script:

```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/host" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":3000,"title":"Login preview"}'
```

For an ungated URL, pass `{"public":true}`. For a service that listens on localhost only, pass `{"localhost":true}`.

```ts TypeScript theme={null}
await sandbox.hostPort({ sandboxId: "bx_f7k2q9hd", port: 5173, localhost: true });
```

## In-sandbox `host <port>`

Expose a running service on a stable HTTPS URL:

<CodeGroup>
  ```bash CLI theme={null}
  host 3000
  host 3000 --title "Login preview"
  host 3000 --private
  host 3000 --public
  host 5173 --localhost
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"host 3000 --title \"Login preview\""}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host 3000" });
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: 'host 3000 --title "Login preview"' });
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host 3000 --private" });
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host 3000 --public" });
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host 5173 --localhost" });
  ```

  ```python Python theme={null}
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host 3000"))
  sandbox.command("bx_f7k2q9hd", CommandRequest(command='host 3000 --title "Login preview"'))
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host 3000 --private"))
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host 3000 --public"))
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host 5173 --localhost"))
  ```
</CodeGroup>

The command does these steps:

1. It opens the firewall for that port.
2. It registers an HTTPS subdomain.
3. It prints the URL.

If you run it again for the same port, you get the same URL. A sandbox can host up to 50 ports.

| Option | Description |
| - | - |
| `--title <title>` | Set the display title for the hosted port. |
| `--private` | Require the generated `_token` query parameter to access the URL. |
| `--public` | Clear any saved access token and return a URL that does not require `_token`. |
| `--localhost` | The service listens on localhost only. The sandbox relays the URL to it. `host url` takes it too. |

By default, `host <port>` creates a protected URL with a `_token` query parameter. This protection stays. If you host the same port again, the URL has the same `_token`, unless you pass `--public`.

For raw access without HTTPS or a subdomain, open the port yourself with `ufw`. Then use `http://<sandbox-ip>:<port>` directly.

## `host list`

Show the hosted ports of the current sandbox:

<CodeGroup>
  ```bash CLI theme={null}
  host list
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"host list"}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host list" });
  ```

  ```python Python theme={null}
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host list"))
  ```
</CodeGroup>

* `host list` shows protected ports as `(gated)`.
* `host list` shows relayed ports as `(localhost)`.
* `host list` does not print the access token.
* To print the full URL with `_token=...`, use `host url <port>`.

## `host url <port>`

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

<CodeGroup>
  ```bash CLI theme={null}
  host url 3001
  host url 3001 --public
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"host url 3001"}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001" });
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001 --public" });
  ```

  ```python Python theme={null}
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001 --public"))
  ```
</CodeGroup>

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

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

Use it when one service needs the public URL of another service:

<CodeGroup>
  ```bash CLI theme={null}
  BACKEND_URL=$(host url 3001)
  ```

  ```bash curl theme={null}
  BACKEND_URL=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"host url 3001"}' | jq -r '.stdout')
  ```

  ```ts TypeScript theme={null}
  const result = await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001" });
  const backendUrl = result.stdout.trim();
  ```

  ```python Python theme={null}
  result = sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
  backend_url = result.stdout.strip()
  ```
</CodeGroup>

## `host hide <port>`

Take down the public URL:

<CodeGroup>
  ```bash CLI theme={null}
  host hide 3000
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"host hide 3000"}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host hide 3000" });
  ```

  ```python Python theme={null}
  sandbox.command("bx_f7k2q9hd", CommandRequest(command="host hide 3000"))
  ```
</CodeGroup>

* It closes public access, unregisters the HTTPS route and turns off the localhost relay.
* It does not stop the local server process. Stop the server yourself when you are done.
* It keeps the access tokens. If you host the same port again, existing protected links stay valid.

To get an ungated URL after a port became protected, run `host <port> --public`.


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