Quickstart - boat

Install the CLI

curl -fsSL https://boat.dev/install | sh

irm https://boat.dev/install.ps1 | iex

curl -fsSL https://boat.dev/install | sh

Onboarding starts automatically after installation and is short:

Sign in through your browser with GitHub, Google, or a code sent to your email. The CLI asks which one; boat onboard --google and boat onboard --email you@example.com answer it up front.
Say what the sandboxes are for: your own work, or a platform of yours driven by third-party users. The second is the default, and it marks your environment safe for third parties so none of your credentials reach those sandboxes. You can change it later.
Choose a Boat plan in Stripe Checkout. It includes a free-of-charge 7-day trial.
Return to the terminal while the CLI waits for billing to become active.

Repositories are not asked for at this point. A Sandbox is useful with none, and you add them whenever you like from Environments.

Reinstalling, or a second machine

Your plan, environment, sandboxes and settings live on your account, not on the machine. Reinstalling Boat, or installing it on a new computer, only needs that machine signed in:

boat onboard   # or: boat login

Sign in the same way you did the first time and boat onboard picks up the account you already have: it skips every step that account has finished, and does not open Stripe Checkout when your plan is active.

Use the same sign-in method as before. A method that has never been connected to your account opens a separate one, with its own empty plan, which is the usual reason a reinstall looks like it is asking you to subscribe again. See Sign-in methods.

GitHub, Google and an emailed 6-digit code are three ways in, on both the CLI and the dashboard. None of them is the “real” one: pick whichever you like, and you can add the others later.

boat login                          # asks: github, google, or email
boat login --google
boat login --email you@example.com

Each method you use is a connection on your account, listed under Dashboard > Account. They all open the same account, with the same sandboxes, settings and billing. Add or remove them at any time, as long as one remains. The connection marked primary decides which address receives account notifications, so making another one primary is how you change that address.

Signing in with a method that is not yet connected creates a separate account, even when the email address matches. To use a second method on an account you already have, sign in the way you always do and add the connection from the Account tab. Moving a connection between two existing accounts is a merge, which is support-side only.

Signing in with Google or email does not give Boat any access to your code. Cloning repositories needs a GitHub connection, which you can add whenever you first want one.

Create your first sandbox

Create a one-hour Boat from whichever surface fits your workflow:

boat new

curl -sS -X POST "https://boat.dev/api/v1/sandboxes" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600}'

import { BoatApi, Configuration } from "@boatdev/sdk";

const sandbox = new BoatApi(new Configuration({
  basePath: "https://boat.dev/api/v1",
  accessToken: process.env.BOAT_API_KEY!,
}));

const created = await sandbox.create({ createSandboxRequest: { ttlSeconds: 3600 } });
console.log(created.sandbox.id);

import os
from boat_sdk import ApiClient, Configuration
from boat_sdk.api.boat_api import BoatApi
from boat_sdk.models.create_sandbox_request import CreateSandboxRequest

config = Configuration(host="https://boat.dev/api/v1", access_token=os.environ["BOAT_API_KEY"])
with ApiClient(config) as client:
    sandbox = BoatApi(client)
    created = sandbox.create(CreateSandboxRequest(ttl_seconds=3600))
    print(created.sandbox.id)

In the CLI flow, follow the instructions printed.

Programmatic use

Building Boat into a product, CI system, hosted worker, or agent platform? Use the HTTP API or an SDK to create or resume a sandbox, prompt it, observe events, return a desktop or app preview URL, then stop, resume, fork, or delete the sandbox according to your product lifecycle.

API guide

Learn auth, response envelopes, errors, lifecycle loops, agent prompts, desktop links, and OpenAPI reference usage.

SDKs

Typed Python and TypeScript/JavaScript clients for the Boat API.

OpenAPI reference

Explore generated endpoint docs for creating, prompting, observing, stopping, resuming, and forking sandboxes.

Use in Code

Script the CLI with JSON output when a shell integration is the fastest path.

Agent sign-in

Let an agent register itself, claim a human, and start the 7-day free trial via auth.md.

For API keys, app credentials, .env files, and other runtime secrets, configure Dashboard > Environment before running setup scripts in a sandbox. For a long uninterrupted workflow, disable auto-stop when creating the Sandbox:

boat new --no-auto-stop

curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":null}'

await sandbox.create({ createSandboxRequest: { ttlSeconds: null } });

sandbox.create(CreateSandboxRequest(ttl_seconds=None))

See Long-Running Tasks for timed extension and resume/fork behavior.

Four ways to drive Boat

Everything below is the same platform behind four front doors. Code examples across these docs come as CLI, curl, TypeScript and Python tabs; pick your tab once and the rest of the page follows it.

	Use it for	Auth
CLI (`boat`)	your terminal, CI jobs, shell scripts, and from inside a sandbox	browser sign-in or `BOAT_API_KEY`
REST API	any language, webhooks, anything the SDKs do not cover yet	`BOAT_API_KEY`
SDKs (Python, TypeScript)	typed calls from your own service	`BOAT_API_KEY`
Dashboard	one-off work, and the things that must not be automatable	browser sign-in

They are not identical, and the differences are deliberate:

Only in the dashboard	Only in the CLI	Only in the API and SDKs
Webhook delivery history, organization membership and invites, sign-in connections, per-sandbox metrics, closing your account	interactive SSH, SCP, port forwarding, `boat snapshot pull`	editing a webhook in place (`PATCH /webhooks/{webhookId}`), reading and writing files in a sandbox without SSH

Creating, rotating and revoking API keys and turning on zero data retention need a browser sign-in on either the CLI or the dashboard, and are refused to an API key on purpose.

Next steps

Machine Capabilities

See the runtimes, tools, desktop, and machine specs included in each sandbox.

Environments

Choose the repositories, secrets, and credentials every new Sandbox starts with.

Setup & Scripts

Run setup scripts, or drive setup from your own code.

Long-Running Tasks

Keep a sandbox running longer and restart runtime processes after resume or fork.

SSH Access

Connect to a sandbox over SSH from your terminal or external tools.

Desktop Streaming

Open the sandbox desktop, and let the sandbox’s agents drive it with the computer tools.

Hosting

Expose a service running inside a sandbox on a public HTTPS URL.

SDKs

Use the typed Python and TypeScript/JavaScript clients for the Boat API.

​Install the CLI

​Reinstalling, or a second machine

​Sign-in methods

​Create your first sandbox

​Programmatic use

API guide

SDKs

OpenAPI reference

Use in Code

Agent sign-in

​Four ways to drive Boat

​Next steps

Machine Capabilities

Environments

Setup & Scripts

Long-Running Tasks

SSH Access

Desktop Streaming

Hosting

SDKs

Install the CLI

Reinstalling, or a second machine

Sign-in methods

Create your first sandbox

Programmatic use

Four ways to drive Boat

Next steps