Host with Boat

Quick path

Enter or target a sandbox. In integrations, use the command endpoint to run the same setup inside the Sandbox:

boat ssh bx_f7k2q9hd
npm run dev -- --host 0.0.0.0 --port 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":"npm run dev -- --host 0.0.0.0 --port 3000","cwd":"my-repo"}'

await sandbox.command({
  sandboxId: "bx_f7k2q9hd",
  command: "npm run dev -- --host 0.0.0.0 --port 3000", cwd: "my-repo",
});

sandbox.command("bx_f7k2q9hd", CommandRequest(
    command="npm run dev -- --host 0.0.0.0 --port 3000",
    cwd="my-repo",
))

Start your app on an explicit port.

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.

Inside the sandbox, run host to start hosting your app. Programmatic integrations can execute the same command in the Sandbox:

host 3000 --title "App preview"

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

await sandbox.command({
  sandboxId: "bx_f7k2q9hd",
  command: 'host 3000 --title "App preview"',
});

sandbox.command("bx_f7k2q9hd", CommandRequest(command='host 3000 --title "App preview"'))

Open the public HTTPS URL printed by host:

https://<sandbox-subdomain>-3000.on.boat.dev

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

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

A fresh host <port> URL is protected by default and includes _token. Pass --public only when you want to clear the access token and return an ungated URL.

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

How HTTPS hosting works

When you run host <port>, the sandbox asks the Boat backend to create a stable public route for that sandbox and port. The backend registers a subdomain using the Boat’s current machine address and the port you asked to expose. The generated hostname is based on the sandbox subdomain plus the port:

https://<sandbox-subdomain>-<port>.on.boat.dev

Boat terminates TLS for on.boat.dev, then proxies each request to the target sandbox over the exposed port. Your application still runs inside the sandbox; the public HTTPS route sits in front of it. This is why your server must listen on 0.0.0.0: the route connects to the sandbox from outside the application process, not through your app’s local loopback interface.

Every hosted address is served under both on.boat.dev and on.ascii.dev (the name from before the rename) with the same label, so SUBDOMAIN-3000.on.ascii.dev and SUBDOMAIN-3000.on.boat.dev are the same route. Links you shared as on.ascii.dev keep working until that suffix is retired (see Migrating from Box); switch what you publish to on.boat.dev whenever convenient.

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

Host CLI reference

The boat host command runs from your local machine. The host CLI runs inside a sandbox. Both expose services from that sandbox on public HTTPS URLs.

The service you expose must listen on 0.0.0.0, not only on localhost or 127.0.0.1.

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

Expose a running service without opening 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

The command opens the firewall for that port, registers an HTTPS subdomain, and prints the URL. Calling it again for the same sandbox and 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.
`--public`	Clear any saved access token and return a URL that does not require `_token`.

Use --json to print a machine-readable object with sandboxId, port, url, access, and isProtected. It is a single API call, so it is also 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"}'

Pass {"public":true} for an ungated URL.

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

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

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

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. A Sandbox can host up to 50 ports. If you only need raw access without HTTPS or a subdomain, you can instead open the port yourself with ufw and use http://<sandbox-ip>:<port> directly.

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

By default, host <port> creates a protected URL with an _token query parameter. That protection is sticky: hosting the same port again returns a URL with the same _token query parameter unless you pass --public.

`host list`

Show hosted ports for 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"))

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:

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, this prints the full token-gated URL:

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

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

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

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, run host <port> --public.

Firewall rules inside a sandbox

You have root, so you can add any firewall rule. Boat reaches the sandbox two ways, and a rule that blocks either one marks the sandbox degraded:

What	Protocol	Runs as
Boat agent (commands, snapshots, health)	TCP port 8911	`user`
Tunnel for HTTPS URLs and the agent	WireGuard, outgoing UDP to the address in `sudo wg show wg0 endpoints`	kernel, but carries packets from `user` processes

Linux tags a tunnel packet with the process that sent the data inside it, so an owner rule on user also hits the tunnel. To block outgoing UDP for user without breaking Boat, allow the tunnel endpoint first:

WG=$(sudo wg show wg0 endpoints | awk '{print $2}' | cut -d: -f1)
sudo iptables -I OUTPUT 1 -m owner --uid-owner user -p udp ! -d 127.0.0.0/8 -j REJECT
sudo iptables -I OUTPUT 1 -p udp -d "$WG" -j ACCEPT

A sandbox that answers on any route is never stopped or marked error for this. It shows "health": "degraded" with a reason, and sends sandbox.degraded.

​Quick path

​How HTTPS hosting works

​Host CLI reference

​boat host <sandbox-id> <port>

​In-sandbox host <port>

​host list

​host url <port>

​host hide <port>

​Firewall rules inside a sandbox

​Related

Quick path

How HTTPS hosting works

Host CLI reference

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

In-sandbox `host <port>`

`host list`

`host url <port>`

`host hide <port>`

Firewall rules inside a sandbox

Related