# boat

- [Quickstart](https://docs.boat.dev/quickstart.md): Install Boat and start your first cloud sandbox in two minutes.
- [Pricing & Limits](https://docs.boat.dev/pricing.md): What a sandbox costs per hour, what a plan buys, how many sandboxes you can run and start, and how that compares to other sandbox providers.
- [Build a Platform on Boat](https://docs.boat.dev/platform-guide.md): Run your users' agents, previews, and workspaces on Boat: architectures, costs, and provisioning patterns.
- [Integrated agents](https://docs.boat.dev/integrated-agents.md): Boat runs coding-agent harnesses for you: the boilerplate you would otherwise build on a bare cloud computer, with every seam open to customize or replace.
- [Machine Capabilities](https://docs.boat.dev/machines.md): What's pre-installed on every sandbox and what you can do with it.
- [Environments](https://docs.boat.dev/environments.md): Decide what every new Sandbox starts with: repositories, secrets, and which of your credentials it may use.
- [Setup & Scripts](https://docs.boat.dev/setup.md): Run code inside a Sandbox: setup scripts and driving setup from your own program.
- [Snapshots & Copies](https://docs.boat.dev/snapshots.md): How a sandbox persists, and the four ways to bring one back: resume, fork, template, and download.
- [Data retention and deletion](https://docs.boat.dev/data-retention.md): Choose archive or permanent deletion, enable zero data retention, and understand what is retained.
- [Long-Running Tasks](https://docs.boat.dev/long-running-tasks.md): Keep a sandbox running longer and restart processes after resume or fork.
- [SSH Access](https://docs.boat.dev/ssh-access.md): Connect to a sandbox over SSH from your terminal or external tools.
- [Desktop Streaming](https://docs.boat.dev/desktop-streaming.md): How Boat opens a browser-based desktop stream for GUI work, and how its agents drive the same screen.
- [Windows Apps](https://docs.boat.dev/windows-apps.md): Run Windows-only desktop software in a sandbox with Wine, let an agent drive it, and fork the set-up machine.
- [Host with Boat](https://docs.boat.dev/hosting.md): Run a service inside a sandbox and expose it on a stable public HTTPS URL.
- [API Keys](https://docs.boat.dev/api-keys.md): Scoped, expiring Boat API keys. Least privilege for production.
- [Webhooks](https://docs.boat.dev/webhooks.md): Receive signed notifications when a sandbox becomes ready, finishes restoring, errors, or archives.
- [Agent sign-in](https://docs.boat.dev/agent-auth.md): How an agent registers itself with Boat, claims a human, and starts the 7-day free trial.
- [Accounts & sign-in](https://docs.boat.dev/account.md): Sign-in methods, reinstalling or using a second machine, and which surface (CLI, API, SDKs, dashboard) does what.
- [Organizations & teams](https://docs.boat.dev/organizations.md): One shared plan and balance for a team: members and invites, which wallet a sandbox bills, the sandboxes your team shares, per-member caps, and moving a personal plan in.
- [Billing details](https://docs.boat.dev/billing.md): Plan time versus credit packs, per-sandbox usage, and what happens when you run out.
- [FAQ](https://docs.boat.dev/faq.md): Short answers on accounts, regions, billing, snapshots, lifecycle, and running a platform on Boat.
- [Support](https://docs.boat.dev/support.md): How to reach the Boat team, and what to send so we can help on the first reply.
- [Boat SDKs](https://docs.boat.dev/sdks/overview.md): Use Boat from Python and TypeScript/JavaScript services.
- [Python SDK](https://docs.boat.dev/sdks/python.md): Install, configure, and use the boat-sdk Python package.
- [TypeScript and JavaScript SDK](https://docs.boat.dev/sdks/typescript.md): Install, configure, and use the @boatdev/sdk npm package.
- [Eve](https://docs.boat.dev/integrations/eve.md): Run Eve sandboxes on Boat with the @asciidev/eve-box backend: a zero-to-one guide for newcomers to either tool.
- [Harbor](https://docs.boat.dev/integrations/harbor.md): Run Harbor agent trials and evals on Boat with the harbor-box environment adapter: a zero-to-one guide for newcomers to either tool.
- [CLI Reference](https://docs.boat.dev/cli-reference.md): Complete reference for all Boat CLI commands and global flags.
- [Boat Public API v1](https://docs.boat.dev/api/v1.md): Create, manage, prompt, observe, and expose sandboxes from your own products.
- [Get current Boat user](https://docs.boat.dev/api/reference/account/get-current-boat-user.md): Returns GitHub identity for the authenticated Boat account.
- [List organizations](https://docs.boat.dev/api/reference/account/list-organizations.md): The wallets this account can bill: your personal account first, then every organization you belong to, each with its id and name. Either spelling works wherever an org is passed (`org`, `X-Boat-Org`, `teamId`). `active` marks the wallet new sandboxes bill when a request names none; change it with `P…
- [Set the active organization](https://docs.boat.dev/api/reference/account/set-active-organization.md): Set the wallet new sandboxes bill when a request names none, for this account on every client: the API, the CLI (`boat org switch` sets the same value) and the dashboard. Pass an organization id or name you belong to, or `personal` (or `null`) for your own account. `GET /limits` follows it. Sandboxe…
- [Get Boat limits](https://docs.boat.dev/api/reference/account/get-boat-limits.md): Check remaining machine starts, compute time, credits, access readiness, and concurrent-sandbox capacity for the wallet a create would bill: the `org` / `X-Boat-Org` you pass (id or name), else the account's active wallet, else personal. The response carries `teamId` when an organization wallet was…
- [Get account data-retention policy](https://docs.boat.dev/api/reference/account/get-account-data-retention-policy.md): Read the account zero-data-retention setting.
- [Update account data-retention policy](https://docs.boat.dev/api/reference/account/update-account-data-retention-policy.md): Enable or disable account zero data retention using a sandbox session.
- [Get deletion operation](https://docs.boat.dev/api/reference/account/get-deletion-operation.md): Poll an accepted sandbox or snapshot deletion operation.
- [List GitHub repositories available to Boat](https://docs.boat.dev/api/reference/account/list-github-repositories-available-to-sandbox.md): Returns GitHub repositories grouped by installation plus the current selected repositories for new Sandboxes.
- [Select repository for sandboxes](https://docs.boat.dev/api/reference/account/select-repository-for-sandboxes.md): Idempotently selects one repository for the sandbox environment. Use `databaseId` from `GET /repos` as `repositoryId`; selecting an already-selected repository updates its `baseBranch`.
- [List API keys](https://docs.boat.dev/api/reference/account/list-api-keys.md): Lists API key metadata only. Raw key secrets are not returned after creation/rotation. Results include expiry and scope. A restricted API-key caller receives `apiKeys: []`; only an unrestricted account key or browser/CLI session receives the account inventory. Bearer header is unchanged; scope lives…
- [Get API key usage](https://docs.boat.dev/api/reference/account/get-api-key-usage.md): Get the 30-day request total and created sandboxes and Agents for one API key.
- [List webhooks](https://docs.boat.dev/api/reference/account/list-webhooks.md): List account-wide sandbox lifecycle webhook endpoints.
- [Create webhook](https://docs.boat.dev/api/reference/account/create-webhook.md): Create an account-wide sandbox lifecycle webhook endpoint.
- [Get webhook](https://docs.boat.dev/api/reference/account/get-webhook.md): Get one sandbox lifecycle webhook endpoint without its signing secret.
- [Update webhook](https://docs.boat.dev/api/reference/account/update-webhook.md): Update a sandbox lifecycle webhook endpoint.
- [Delete webhook](https://docs.boat.dev/api/reference/account/delete-webhook.md): Delete a sandbox lifecycle webhook endpoint and its queued deliveries.
- [Rotate webhook signing secret](https://docs.boat.dev/api/reference/account/rotate-webhook-signing-secret.md): Replace a webhook signing secret and return the new secret once.
- [Get Boat secrets setup](https://docs.boat.dev/api/reference/account/get-boat-secrets-setup.md): Returns the environment variables and secret files configured for sandboxes.
- [Update Boat secrets setup](https://docs.boat.dev/api/reference/account/update-boat-secrets-setup.md): Save a new version of your account's sandbox environment variables and secret files. Omitted fields stay unchanged. Send an empty value to clear one. Running sandboxes keep their current version until you upgrade them.
- [List Sandbox environments](https://docs.boat.dev/api/reference/environments/list-sandbox-environments.md): Returns every non-deleted sandbox environment with its latest-version flags, contents, and per-version sandbox usage. A default environment named `base` is created on first access if none exists.
- [Create a sandbox environment](https://docs.boat.dev/api/reference/environments/create-sandbox-environment.md): Create a new named environment. It starts on version 1 with all fine-grained flags on and `safeForThirdParties` off.
- [Update a sandbox environment](https://docs.boat.dev/api/reference/environments/update-sandbox-environment.md): Rename, set as default, and/or edit flags and contents. Any flag or content change mints a new immutable version; existing sandboxes stay on their pinned version until you call upgrade.
- [Delete a sandbox environment](https://docs.boat.dev/api/reference/environments/delete-sandbox-environment.md): Soft-deletes an environment. The default environment cannot be deleted, and at least one environment is always kept.
- [Upgrade sandboxes to an environment's latest version](https://docs.boat.dev/api/reference/environments/upgrade-sandbox-environment.md): Repoints the caller's active sandboxes from an older version of this environment to its latest version, scrubbing any owner secrets the new version drops and hot-pushing the new config.
- [Set environment variable](https://docs.boat.dev/api/reference/environments/set-environment-var.md): Sets or replaces a single variable without reading or rewriting the rest. Mints a new immutable version.
- [Remove environment variable](https://docs.boat.dev/api/reference/environments/delete-environment-var.md): Removes a single variable. Mints a new immutable version.
- [Write environment secret file](https://docs.boat.dev/api/reference/environments/set-environment-secret-file.md): Adds or replaces a single secret file by path. Mints a new immutable version.
- [Remove environment secret file](https://docs.boat.dev/api/reference/environments/delete-environment-secret-file.md): Removes the secret file at `path`. Mints a new immutable version.
- [Add environment repository](https://docs.boat.dev/api/reference/environments/add-environment-repo.md): Adds a repository (or updates its base branch) by database id from the repository list. Mints a new immutable version.
- [Remove environment repository](https://docs.boat.dev/api/reference/environments/delete-environment-repo.md): Removes one repository from the environment's selection. Mints a new immutable version.
- [List sandboxes](https://docs.boat.dev/api/reference/sandboxes/list-sandboxes.md): Your sandboxes. In an organization's scope (the active wallet, `org`, or `X-Boat-Org`) the list also holds every sandbox that organization pays for, whoever created it; `createdBy` and `access` say whose it is and what you may do with it.
- [Create sandbox](https://docs.boat.dev/api/reference/sandboxes/create-sandbox.md): Provision a new cloud computer. Store the returned `sandbox.id` with your product job/session record. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable sandbox.
- [Get sandbox](https://docs.boat.dev/api/reference/sandboxes/get-sandbox.md): Poll this endpoint after create, stop, resume, or fork operations.
- [Get sandbox usage](https://docs.boat.dev/api/reference/sandboxes/get-sandbox-usage.md): Machine time one sandbox consumed and its cost, over its life or a billing window, for per-sandbox billing of your own users.
- [Update sandbox](https://docs.boat.dev/api/reference/sandboxes/update-sandbox.md): Update a sandbox's name, time-to-live, or the subdomain it is hosted on.
- [Stop and archive sandbox](https://docs.boat.dev/api/reference/sandboxes/stop-and-archive-sandbox.md): Stop active work and archive/snapshot the sandbox for later resume or fork.
- [Get a stop by id](https://docs.boat.dev/api/reference/sandboxes/get-stop.md): Returns one stop of this sandbox by the id that `POST /sandboxes/{sandboxId}/stop` returned. Old stops stay readable after a resume or a later stop. Returns 404 when the id is unknown or belongs to another sandbox.
- [Permanently delete sandbox data](https://docs.boat.dev/api/reference/sandboxes/permanently-delete-sandbox-data.md): Confirm and accept irreversible background deletion of a sandbox.
- [Resume sandbox](https://docs.boat.dev/api/reference/sandboxes/resume-sandbox.md): Resume a stopped sandbox from its snapshot, optionally with a different environment or time-to-live.
- [Recover sandbox](https://docs.boat.dev/api/reference/sandboxes/recover-sandbox.md): Power-cycle the machine of a sandbox that stopped responding, without touching its disk.
- [Share sandbox with the organization](https://docs.boat.dev/api/reference/sandboxes/share-sandbox.md): Let every member of the organization that pays for this sandbox use it.
- [Fork sandbox](https://docs.boat.dev/api/reference/sandboxes/fork-sandbox.md): Provision a new sandbox from an existing one. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable fork.
- [List snapshots](https://docs.boat.dev/api/reference/snapshots/list-snapshots.md): List visible completed snapshots across all of your sandboxes using immutable ownership attribution. Pinned, deletion-scheduled, and privacy-fenced sandbox snapshots are omitted. Follow `nextCursor` through the complete history; there is no hidden 500-snapshot cap.
- [List boat snapshots](https://docs.boat.dev/api/reference/snapshots/list-sandbox-snapshots.md): List visible completed snapshots for one sandbox with uncapped cursor pagination.
- [Get latest boat snapshot](https://docs.boat.dev/api/reference/snapshots/get-latest-sandbox-snapshot.md): Return the most recent completed snapshot for this sandbox, or `null` if it has none.
- [Get snapshot file tree](https://docs.boat.dev/api/reference/snapshots/get-snapshot-tree.md): List the files and folders captured in a snapshot, with sizes. Returns a flat list of entries you can render as a tree.
- [Download a file or folder from a snapshot](https://docs.boat.dev/api/reference/snapshots/get-snapshot-file.md): Stream a single file's bytes, or a folder subtree as a tar archive, directly out of a snapshot, the sandbox can be stopped or archived; the machine is never contacted. Use `GET /snapshots/{snapshotId}/tree` to list paths, then pass one here. Paths are relative to the snapshot root (same space as `tr…
- [Get snapshot download](https://docs.boat.dev/api/reference/snapshots/get-snapshot-download.md): Return time-limited signed URLs for every chunk needed to reconstruct the sandbox filesystem at this snapshot (the full chain, base through this generation), plus the inventory. Download the chunks and reassemble them as described by `reconstruct`. The `boat snapshot pull` CLI command does this for…
- [Permanently delete snapshot data](https://docs.boat.dev/api/reference/snapshots/permanently-delete-snapshot-data.md): Confirm and accept irreversible background deletion of a snapshot.
- [List named snapshots](https://docs.boat.dev/api/reference/snapshots/list-named-snapshots.md): List your named snapshots, newest first.
- [Save a named snapshot](https://docs.boat.dev/api/reference/snapshots/save-named-snapshot.md): Freeze a sandbox's current state under a name (`boat snapshot <id> <name>` in the CLI). Answers `202` immediately with the snapshot in `saving`; a running sandbox takes a fresh capture first, which can run minutes. Poll `GET /named-snapshots/{name}` until the status settles at `ready` or `failed`. R…
- [Get a named snapshot](https://docs.boat.dev/api/reference/snapshots/get-named-snapshot.md): Get a named snapshot and its status. Poll this after saving one until the status settles at ready or failed.
- [Delete a named snapshot](https://docs.boat.dev/api/reference/snapshots/delete-named-snapshot.md): Remove a named snapshot and release its storage (`boat snapshot rm <name>` in the CLI). Sandboxes already deployed from it are unaffected.
- [Prompt Sandbox](https://docs.boat.dev/api/reference/agent/prompt-sandbox-agent.md): Queue a natural-language work item for an agent harness (Codex, Claude Code, pi, OpenCode, or Prime Agent) inside the sandbox. Observe progress with `GET /sandboxes/{sandboxId}/events`.
- [List boat events](https://docs.boat.dev/api/reference/agent/list-sandbox-events.md): Return Sandbox work, lifecycle, and progress events so product UIs can show what the sandbox is doing. A Sandbox runs many conversations in parallel; this streams **all** of them by default and every event carries a `conversationId`. Filter to one or more with `conversation`. Event payloads are exte…
- [List boat conversations](https://docs.boat.dev/api/reference/agent/list-sandbox-conversations.md): Every conversation on the sandbox, most recently prompted first, with what you need to pick one: how many prompts it holds, whether a turn is running in it right now, the last harness and model it ran on, a preview of its last prompt, and `current`, the one a `POST /prompt` without `new` or `convers…
- [Get prompt run status](https://docs.boat.dev/api/reference/agent/get-prompt-run-status.md): Returns first-class status for a queued/running/finished prompt so clients do not infer completion from sandbox state and events.
- [Read Sandbox file](https://docs.boat.dev/api/reference/agent/read-sandbox-file.md): Read a file from a sandbox by its path, as UTF-8 text by default or base64 for binary content.
- [Write Sandbox file](https://docs.boat.dev/api/reference/agent/write-sandbox-file.md): Write or overwrite a file in a sandbox at a given path, as UTF-8 text or base64-encoded binary content.
- [Execute Sandbox command](https://docs.boat.dev/api/reference/agent/execute-sandbox-command.md): Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output…
- [Get command status](https://docs.boat.dev/api/reference/agent/get-command-status.md): Get the status and recent log output of a detached command running in a sandbox. Use tailBytes to limit how much log is returned.
- [Download Sandbox artifact](https://docs.boat.dev/api/reference/agent/download-sandbox-artifact.md): Download a file from a sandbox by its path, returned as a binary artifact.
- [Steer a running turn](https://docs.boat.dev/api/reference/agent/steer-a-running-turn.md): Send a new message to a turn that is already running, without losing what the agent is doing. This is what typing into a coding agent while it works does: the instruction is taken into account and the work continues.
- [Interrupt running work](https://docs.boat.dev/api/reference/agent/interrupt-running-agent-work.md): Interrupt running agent work. By default this stops **every** conversation on the sandbox. Pass `conversation` to stop just one, leaving the others running. See [Integrated agents](/integrated-agents).
- [Get desktop streaming URL](https://docs.boat.dev/api/reference/agent/get-desktop-streaming-url.md): Create or fetch a secret-bearing desktop/noVNC URL for live computer-use visibility. Use `?vnc=1` for noVNC; a `provisioning: true` response means poll again.
- [Configure sandbox SSH key](https://docs.boat.dev/api/reference/agent/configure-sandbox-ssh-key.md): Adds an OpenSSH public key to the running sandbox so the caller can SSH as user `user`. The response carries `machineIp`, which is the host to connect to on port 22.

## OpenAPI Specs

- [boat-v1](/openapi/boat-v1.yaml)
- [box-v1](/openapi/box-v1.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.