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

# Quickstart

> Install Boat, finish onboarding, and start your first cloud sandbox.

## Install the CLI

<CodeGroup>
  ```bash macOS theme={null}
  curl -fsSL https://boat.dev/install | sh
  ```

  ```powershell Windows theme={null}
  irm https://boat.dev/install.ps1 | iex
  ```

  ```bash Linux theme={null}
  curl -fsSL https://boat.dev/install | sh
  ```
</CodeGroup>

Onboarding starts automatically after installation and is short:

1. 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.
2. 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](/environments#safe-for-third-parties) so none of your credentials reach those sandboxes. You can change it later.
3. Choose a Boat plan in Stripe Checkout. It includes a free-of-charge 7-day trial.
4. 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](/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:

```bash theme={null}
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.

<Note>
  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](#sign-in-methods).
</Note>

### Sign-in methods

GitHub, Google and an emailed 6-digit code are three ways in, on both the CLI and the [dashboard](https://boat.dev/dashboard). None of them is the "real" one: pick whichever you like, and you can add the others later.

```bash theme={null}
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](https://boat.dev/dashboard?tab=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.

<Note>
  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.
</Note>

Signing in with Google or email does not give Boat any access to your code. Cloning [repositories](/environments#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:

<CodeGroup>
  ```bash CLI theme={null}
  boat new
  ```

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

  ```ts TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

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.

<CardGroup cols={2}>
  <Card title="API guide" icon="brackets-curly" href="/api/v1">
    Learn auth, response envelopes, errors, lifecycle loops, agent prompts, desktop links, and OpenAPI reference usage.
  </Card>

  <Card title="SDKs" icon="cubes" href="/sdks/overview">
    Typed Python and TypeScript/JavaScript clients for the Boat API.
  </Card>

  <Card title="OpenAPI reference" icon="book-open" href="/api/reference/sandboxes/create-sandbox">
    Explore generated endpoint docs for creating, prompting, observing, stopping, resuming, and forking sandboxes.
  </Card>

  <Card title="Use in Code" icon="code" href="/use-in-code">
    Script the CLI with JSON output when a shell integration is the fastest path.
  </Card>

  <Card title="Agent sign-in" icon="robot" href="/agent-auth">
    Let an agent register itself, claim a human, and start the 7-day free trial via auth.md.
  </Card>
</CardGroup>

For API keys, app credentials, `.env` files, and other runtime secrets, configure [Dashboard > Environment](https://boat.dev/dashboard?tab=environment) before running setup scripts in a sandbox.

For a long uninterrupted workflow, disable auto-stop when creating the Sandbox:

<CodeGroup>
  ```bash CLI theme={null}
  boat new --no-auto-stop
  ```

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

  ```ts TypeScript theme={null}
  await sandbox.create({ createSandboxRequest: { ttlSeconds: null } });
  ```

  ```python Python theme={null}
  sandbox.create(CreateSandboxRequest(ttl_seconds=None))
  ```
</CodeGroup>

See [Long-Running Tasks](/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](/sdks/python), [TypeScript](/sdks/typescript)) | typed calls from your own service                                | `BOAT_API_KEY`                    |
| **[Dashboard](https://boat.dev/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](/webhooks), [organization membership and invites](/billing#organizations), [sign-in connections](#sign-in-methods), per-sandbox metrics, [closing your account](/data-retention#close-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](/api-keys) and turning on [zero data retention](/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

<CardGroup cols={2}>
  <Card title="Machine Capabilities" icon="microchip" href="/machines">
    See the runtimes, tools, desktop, and machine specs included in each sandbox.
  </Card>

  <Card title="Environments" icon="key" href="/environments">
    Choose the repositories, secrets, and credentials every new Sandbox starts with.
  </Card>

  <Card title="Setup & Scripts" icon="terminal" href="/setup">
    Run setup scripts, or drive setup from your own code.
  </Card>

  <Card title="Long-Running Tasks" icon="clock" href="/long-running-tasks">
    Keep a sandbox running longer and restart runtime processes after resume or fork.
  </Card>

  <Card title="SSH Access" icon="terminal" href="/ssh-access">
    Connect to a sandbox over SSH from your terminal or external tools.
  </Card>

  <Card title="Desktop Streaming" icon="desktop" href="/desktop-streaming">
    Open the sandbox desktop, and let the sandbox's agents drive it with the `computer` tools.
  </Card>

  <Card title="Hosting" icon="globe" href="/hosting">
    Expose a service running inside a sandbox on a public HTTPS URL.
  </Card>

  <Card title="SDKs" icon="cubes" href="/sdks/overview">
    Use the typed Python and TypeScript/JavaScript clients for the Boat API.
  </Card>
</CardGroup>