Host CLI reference

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

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.

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

Expose a running service without an interactive SSH session:

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:

It opens the firewall for that port.
It registers an HTTPS subdomain.
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:

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

TypeScript

await sandbox.hostPort({ sandboxId: "bx_f7k2q9hd", port: 5173, localhost: true });

In-sandbox `host <port>`

Expose a running service on a stable HTTPS URL:

host 3000
host 3000 --title "Login preview"
host 3000 --private
host 3000 --public
host 5173 --localhost

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\""}'

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" });

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"))

The command does these steps:

It opens the firewall for that port.
It registers an HTTPS subdomain.
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:

host list

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"}'

await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host list" });

sandbox.command("bx_f7k2q9hd", CommandRequest(command="host list"))

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:

host url 3001
host url 3001 --public

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"}'

await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001" });
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001 --public" });

sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001 --public"))

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

https://<sandbox-subdomain>-3001.on.boat.dev?_token=<access-token>

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

BACKEND_URL=$(host url 3001)

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')

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

result = sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
backend_url = result.stdout.strip()

`host hide <port>`

Take down the public URL:

host hide 3000

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"}'

await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host hide 3000" });

sandbox.command("bx_f7k2q9hd", CommandRequest(command="host hide 3000"))

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.

​boat host <sandbox-id> <port>

​In-sandbox host <port>

​host list

​host url <port>

​host hide <port>

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

In-sandbox `host <port>`

`host list`

`host url <port>`

`host hide <port>`