Skip to main content

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

​
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:
  • 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.
Some dev servers reject requests for host names they do not know. For Vite, add .on.boat.dev to server.allowedHosts.

​
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

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). Change the links that you publish to on.boat.dev when convenient.