# Accounts & sign-in
Source: https://docs.boat.dev/account
Sign-in methods, reinstalling or using a second machine, and which surface (CLI, API, SDKs, dashboard) does what.
## Sign-in methods
There are three ways to sign in, on the CLI and on the [dashboard](https://boat.dev/dashboard):
* GitHub
* Google
* A 6-digit code sent by email
No method is more correct than the others. Use the one you like. 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 that you use is a **connection** on your account. [Dashboard > Account](https://boat.dev/dashboard?tab=account) lists them.
* All connections open the same account, with the same sandboxes, settings and billing.
* You can add or remove connections at any time. One connection must remain.
* The **primary** connection sets the address that gets account notifications. To change that address, make a different connection primary.
A sign-in with a method that is not connected yet makes a **separate** account. This is true also when the email address is the same. To add a second method to your account, do these steps:
1. Sign in with your usual method.
2. Add the connection from the Account tab.
To move a connection between two existing accounts, you must merge the accounts. Only support can do a merge.
A sign-in with Google or email does not give Boat access to your code. To clone [repositories](/environments/repositories), you need a GitHub connection. You can add it when you first need it.
## Reinstalling, or a second machine
Your plan, environment, sandboxes and settings are on your account, not on your computer. To reinstall Boat, or to install it on a new computer, sign in on that computer:
```bash theme={null}
boat onboard # or: boat login
```
Sign in with the same method as the first time. `boat onboard` then finds your account:
* It skips each step that your account has already done.
* It does **not** open Stripe Checkout when your plan is active.
Use the same sign-in method as before. A method that was never connected to your account opens a **separate** account, with its own empty plan. This is the usual cause when a reinstall asks you to subscribe again.
## What the sandboxes are for
Onboarding asks what the sandboxes are for. There are two answers:
* Your own work.
* A platform of yours, used by third-party users. This is the default.
The second answer marks your environment [safe for third parties](/environments#safe-for-third-parties). Then none of your credentials go to those sandboxes.
You can change this at any time in [Dashboard > Environment](https://boat.dev/dashboard?tab=environment).
## Four ways to drive Boat
The four ways use the same platform. The code examples in these docs have **CLI**, **curl**, **TypeScript** and **Python** tabs. Select a tab one time, and the rest of the page uses 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 |
The four ways are not identical. The differences are intentional:
| Only in the dashboard | Only in the CLI | Only in the API and SDKs |
| - | - | - |
| [Webhook delivery history](/webhooks), [organization membership and invites](/organizations#members-and-invites), sign-in connections, per-sandbox metrics, [closing your account](/data-retention/close-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 |
Some actions need a browser sign-in, on the CLI or on the dashboard. Boat refuses them to an API key on purpose:
* Create, rotate and revoke [API keys](/api-keys).
* Turn on [zero data retention](/data-retention).
An agent can also sign itself in and claim a human. See [Agent sign-in](/agent-auth).
# Agent sign-in
Source: https://docs.boat.dev/agent-auth
How an agent registers itself with Boat, claims a human, and starts the 7-day free trial.
An agent can join Boat without a human who pastes an API key. Boat implements [auth.md](https://workos.com/blog/agent-registration-with-auth-md), the WorkOS agentic registration protocol.
The contract is a machine-readable file at [ascii.dev/auth.md](https://boat.dev/auth.md). This page is a human-readable copy of it.
If you are an agent, fetch that file and follow it. Do not work from this page. Do not answer from search results about it.
## Start
Give the agent this instruction:
```
Follow https://boat.dev/auth.md and start a sandbox free trial for me.
```
The agent then does these steps:
1. It finds the endpoints from `/.well-known/oauth-protected-resource`.
2. It registers.
3. Only after that, it calls the Boat API.
## What the agent does
```mermaid theme={null}
sequenceDiagram
participant Agent
participant Boat
participant Human
Agent->>Boat: GET /auth.md and well-known metadata
Agent->>Boat: POST /agent/identity (anonymous or email)
alt anonymous
Boat-->>Agent: identity assertion (read-only)
else email
Boat-->>Agent: user_code + verification URL
end
Agent->>Human: Open this link and type this 6-digit code
Human->>Boat: Sign in, enter the code
Boat-->>Agent: access_token (Boat API key)
Agent->>Boat: POST /api/boat/billing/checkout
Agent->>Human: Open Stripe Checkout to start the 7-day trial
Human->>Boat: Card + trial
Agent->>Boat: POST /api/v1/sandboxes
```
There are two ways to register.
| Method | Token | What the agent can do |
| - | - | - |
| **Anonymous** | Immediately | Only `GET /me` and `GET /limits`. A sandbox create returns `claim_required` until a human claims the agent. |
| **Email (`service_auth`)** | After the person signs in and types the code | The agent must already know the user's email. |
Boat does not accept ID-JAG or provider-attested identity yet. The agent must not send `identity_assertion` registration bodies.
## Expect approval prompts
Almost every step sends a credential or an email address to a new host. Agent harnesses ask for approval before these actions. So the agent stops for approval more than once. This is correct behavior, not a failure.
You can retry each step by itself. When an approval stops the agent, it does these steps:
1. It says what it is about to send.
2. It waits for approval.
3. It continues from the step where it stopped.
## Trial
The trial uses the same Stripe Checkout that a human uses from the dashboard.
1. The agent calls `POST /api/boat/billing/checkout` with the claimed token.
2. The agent shows the URL that Boat returns.
3. The human enters a card and starts the trial.
These rules still apply:
* A card is necessary.
* Boat runs trial-abuse checks.
* There is one trial per identity.
* An anonymous token cannot start a trial.
## Prices
An agent must never give a price from memory or from a web search.
* `GET /api/v1/limits` returns the live plans, trial inclusions and caps. Read them there when necessary.
* To estimate usage cost, send the human to [boat.dev](https://boat.dev). It has the calculator.
* Search results and cached marketing pages are not a price source. Some of them describe different Ascii products.
## Endpoints
The endpoints are on `https://ascii.dev`. They are also under `/api/boat/...`, so they work behind the existing `/api` proxy.
| Path | Purpose |
| - | - |
| `/auth.md` | Agent-readable walkthrough |
| `/.well-known/oauth-protected-resource` | RFC 9728 discovery |
| `/.well-known/oauth-authorization-server` | RFC 8414 + `agent_auth` block |
| `POST /agent/identity` | Register |
| `POST /agent/identity/claim` | Start or refresh the claim ceremony |
| `GET /agent/identity/claim` | Human claim page |
| `POST /oauth2/token` | Exchange assertion or poll claim |
| `POST /oauth2/revoke` | Revoke one access token |
A 401 from the Boat API includes this header. An agent that only calls the API can use it to find the other endpoints.
```
WWW-Authenticate: Bearer resource_metadata="https://boat.dev/api/boat/.well-known/oauth-protected-resource"
```
# AI credentials
Source: https://docs.boat.dev/ai-credentials
Credential profiles, switching to another Claude or ChatGPT account when one runs out of credits, custom APIs, and the AI credentials proxy that keeps real keys out of your sandboxes.
Your sandboxes get the AI credentials of a **credential profile**: Claude and ChatGPT sign-ins, API keys, and custom APIs. With the **AI credentials proxy** on, a sandbox gets placeholder keys, and the real keys stay with Boat.
| | CLI | API | SDKs |
| - | - | - | - |
| List profiles | `boat ai profiles` | `GET /credential-profiles` | `listCredentialProfiles` |
| Create a profile | `boat ai profile new ` | `POST /credential-profiles` | `createCredentialProfile` |
| Rename, make default | `boat ai profile rename` / `default` | `PUT /credential-profiles/{profile}` | `updateCredentialProfile` |
| Delete a profile | `boat ai profile rm ` | `DELETE /credential-profiles/{profile}` | `deleteCredentialProfile` |
| Set, remove an API key | `boat ai profile set-key` / `rm-key` | `PUT`, `DELETE /credential-profiles/{profile}/keys/{credential}` | `setCredentialProfileKey`, `deleteCredentialProfileKey` |
| Switch a credential to another account | `boat ai accounts` / `switch` | `GET /credential-profiles/{profile}/accounts/{credential}`, `PUT …/{account}/active` | `listCredentialAccounts`, `switchCredentialAccount` |
| Add, forget an account | `boat ai add-account` / `forget-account` | `POST /credential-profiles/{profile}/accounts/{credential}`, `DELETE …/{account}` | `addCredentialAccount`, `deleteCredentialAccount` |
| Set, remove a custom API | `boat ai profile set-api` / `rm-api` | `PUT`, `DELETE /credential-profiles/{profile}/custom-apis/{name}` | `setCredentialProfileCustomApi`, `deleteCredentialProfileCustomApi` |
| Proxy on or off | `boat ai proxy [on\|off]` | `GET`, `PUT /ai-proxy` | `getAiProxy`, `updateAiProxy` |
| Usage | `boat ai usage [id]` | `GET /ai-usage`, `GET /sandboxes/{id}/ai-usage` | `getAiUsage`, `getSandboxAiUsage` |
| Block, unblock a sandbox | `boat ai block` / `unblock` | `PUT /sandboxes/{id}/ai-access` | `setSandboxAiAccess` |
The profile and proxy calls need an API key with `account.admin`. Account usage needs `account.read`. Sandbox usage needs `box.read` on that sandbox.
## Credential profiles
A credential profile is a named set of AI credentials. Boat encrypts it at rest. The API never returns a secret value: it lists which credentials a profile holds (`connected`) and the names of its custom APIs.
Each account has one **default** profile. A sandbox gets the default profile of its owner, unless its environment names another profile. The credentials you had before profiles existed are now the profile named `default`. On the dashboard **Agents & Proxying** page, pick a profile at the top. Both tabs then show and edit only that profile: its sign-ins and keys, its proxy switch, its custom APIs and its usage.
| Credential | Kind | Set it with |
| - | - | - |
| `anthropic-api-key`, `openai-api-key`, `openrouter-api-key`, `llmgateway-api-key`, `deepseek-api-key`, `moonshot-api-key`, `mistral-api-key` | API key | `set-key`, or the Agents & Proxying page |
| `claude-subscription`, `chatgpt-subscription`, `kimi-subscription`, `mistral-vibe-subscription` | Sign-in | The Agents & Proxying page |
| `claude-bedrock`, `codex-bedrock` | AWS Bedrock | The Agents & Proxying page |
You can remove any credential with `rm-key`. A sign-in sent to `set-key` returns `400 not_an_api_key`.
### Out of credits? Switch to another account
A credential can hold several accounts: two ChatGPT sign-ins, two Claude sign-ins, two OpenAI keys. One account is in use. When it runs out of credits, switch the credential to another account. Every sandbox that uses the profile gets the other account at once, running sandboxes included. Nothing restarts, and the other credentials do not change.
On the dashboard **Agents & Proxying** page, the account in use shows next to each credential. Click it to:
* **switch** to another account,
* **add another account**: sign in again, or paste another key. The current account stays, ready to switch back to,
* **forget** an account. Forgetting the one in use switches to another account first.
Sign-ins renew only while in use. An account set aside keeps its sign-in as it was, and renews when you switch back to it.
```bash CLI theme={null}
boat ai accounts chatgpt-subscription
# # ACCOUNT
# 1 you@work.dev in use
# 2 you@home.dev
boat ai switch chatgpt-subscription 2
# API keys: add a second key, then switch by number, or by its last characters
echo "$OPENAI_API_KEY_2" | boat ai add-account openai-api-key
boat ai switch openai-api-key …7f3a
boat ai forget-account openai-api-key 2
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/credential-profiles/default/accounts/chatgpt-subscription" \
-H "Authorization: Bearer $BOAT_API_KEY"
# use the id of the account to switch to, from the list
curl -sS -X PUT "$BOAT_API_BASE/credential-profiles/default/accounts/chatgpt-subscription/$ACCOUNT_ID/active" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X POST "$BOAT_API_BASE/credential-profiles/default/accounts/openai-api-key" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"value":"'"$OPENAI_API_KEY_2"'"}'
```
```ts TypeScript theme={null}
const { accounts } = await sandbox.listCredentialAccounts({ profile: "default", credential: "chatgpt-subscription" });
const other = accounts.find((a) => !a.active)!;
await sandbox.switchCredentialAccount({ profile: "default", credential: "chatgpt-subscription", account: other.id });
```
```python Python theme={null}
accounts = sandbox.list_credential_accounts("default", "chatgpt-subscription").accounts
other = next(a for a in accounts if not a.active)
sandbox.switch_credential_account("default", "chatgpt-subscription", other.id)
```
`--profile` picks another profile; the default is your default profile. The account list never shows a secret: a sign-in shows its email when the provider gives it, a key shows its last characters.
To give different sandboxes different accounts at the same time, use one profile per account and name the profile on an environment (see [Environments](#environments)).
### Set and remove API keys
`--copy-from` starts a new profile with a copy of the API keys and custom APIs of a profile you manage. Sign-ins are not copied: one sign-in in two profiles would sign itself out at the first renewal. Sign in again on the new profile. The CLI reads a key from stdin when you omit the value, so the key stays out of your shell history. A key is one token of up to 8192 printable characters, without spaces or line breaks; anything else returns `400`.
```bash CLI theme={null}
boat ai profile new ci --copy-from default
echo "$ANTHROPIC_API_KEY" | boat ai profile set-key ci anthropic-api-key
boat ai profile rm-key ci claude-subscription
boat ai profile rename ci ci-bots
boat ai profile rm ci-bots
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/credential-profiles" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"ci","copyFrom":"default"}'
curl -sS -X PUT "$BOAT_API_BASE/credential-profiles/ci/keys/anthropic-api-key" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"value":"'"$ANTHROPIC_API_KEY"'"}'
curl -sS -X DELETE "$BOAT_API_BASE/credential-profiles/ci/keys/claude-subscription" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X DELETE "$BOAT_API_BASE/credential-profiles/ci" -H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.createCredentialProfile({ name: "ci", copyFrom: "default" });
await sandbox.setCredentialProfileKey({
profile: "ci",
credential: "anthropic-api-key",
value: process.env.ANTHROPIC_API_KEY!,
});
await sandbox.deleteCredentialProfileKey({ profile: "ci", credential: "claude-subscription" });
await sandbox.deleteCredentialProfile({ profile: "ci" });
```
```python Python theme={null}
import os
from boat_sdk.models.create_credential_profile_request import CreateCredentialProfileRequest
from boat_sdk.models.set_credential_key_request import SetCredentialKeyRequest
sandbox.create_credential_profile(CreateCredentialProfileRequest(name="ci", copy_from="default"))
sandbox.set_credential_profile_key("ci", "anthropic-api-key", SetCredentialKeyRequest(value=os.environ["ANTHROPIC_API_KEY"]))
sandbox.delete_credential_profile_key("ci", "claude-subscription")
sandbox.delete_credential_profile("ci")
```
Running sandboxes that use the profile get a changed key. You cannot delete a default profile (`409 is_default`) or a profile that an environment names (`409 in_use`).
### Organization profiles
An organization can own profiles too. Every active member can use them. Only organization owners create and change them, and only they see the account list. In a profile list, `owner.kind` is `org` and `canManage` tells you if you can change it.
```bash CLI theme={null}
boat --org acme ai profile new team-claude
echo "$ANTHROPIC_API_KEY" | boat ai profile set-key team-claude anthropic-api-key
boat ai profiles --org-only
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/credential-profiles" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"team-claude","org":"acme"}'
```
```ts TypeScript theme={null}
await sandbox.createCredentialProfile({ name: "team-claude", org: "acme" });
```
```python Python theme={null}
sandbox.create_credential_profile(CreateCredentialProfileRequest(name="team-claude", org="acme"))
```
To give a team's sandboxes the organization profile, name it on an organization environment. See [Organizations & teams](/organizations/shared-sandboxes#shared-environments-and-ai-credentials).
## Custom APIs
A custom API is a secret for any HTTPS API, such as Stripe or your own service. You give it a name, a value and a base URL. The sandbox gets two variables:
| Variable | Value |
| - | - |
| `` | The secret. A placeholder when the proxy is on |
| `_BASE_URL` | The base URL. The proxy URL when the proxy is on |
The name is an environment variable name: `A-Z`, `0-9` and `_`, up to 64 characters. Provider names (`ANTHROPIC_*`, `OPENAI_*`, `AWS_*`, and so on) and names that end in `_BASE_URL` are reserved. The base URL must use HTTPS on the default port, with a public DNS name.
```bash CLI theme={null}
echo "$STRIPE_KEY" | boat ai profile set-api default STRIPE_KEY --base-url https://api.stripe.com/v1
boat ai profile rm-api default STRIPE_KEY
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/credential-profiles/default/custom-apis/STRIPE_KEY" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"value":"'"$STRIPE_KEY"'","baseUrl":"https://api.stripe.com/v1"}'
curl -sS -X DELETE "$BOAT_API_BASE/credential-profiles/default/custom-apis/STRIPE_KEY" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.setCredentialProfileCustomApi({
profile: "default",
name: "STRIPE_KEY",
value: process.env.STRIPE_KEY!,
baseUrl: "https://api.stripe.com/v1",
});
await sandbox.deleteCredentialProfileCustomApi({ profile: "default", name: "STRIPE_KEY" });
```
```python Python theme={null}
from boat_sdk.models.set_custom_api_request import SetCustomApiRequest
sandbox.set_credential_profile_custom_api("default", "STRIPE_KEY", SetCustomApiRequest(
value=os.environ["STRIPE_KEY"],
base_url="https://api.stripe.com/v1",
))
sandbox.delete_credential_profile_custom_api("default", "STRIPE_KEY")
```
Code in the sandbox must send its requests to `$_BASE_URL`. With the proxy on, a request sent straight to the API with the placeholder fails.
## The AI credentials proxy
Without the proxy, a sandbox holds your real keys and sign-ins. Anyone with a shell in it can copy them. With the proxy on, the real keys never enter the sandbox.
```
sandbox Boat provider
ANTHROPIC_API_KEY=
ANTHROPIC_BASE_URL=
agent ── request + placeholder ──▶ proxy: placeholder valid?
sandbox blocked?
swap in the real key ── request + real key ──▶ api.anthropic.com
◀──────── reply ───────────── count tokens ◀─────────── reply ──────────────
```
| | The sandbox holds | Boat holds |
| - | - | - |
| Proxy off | The real keys and sign-ins | The real keys and sign-ins |
| Proxy on | Placeholders and the proxy URL | The real keys and sign-ins, and renews the sign-ins |
* A placeholder is worthless outside Boat. It does not contain the real key.
* A copied placeholder stops working when the sandbox stops. Each start gives the sandbox new placeholders.
* The proxy sends each credential only to its own provider. An Anthropic key never goes to another host.
* The proxy puts a provider key only in the `Authorization` or `x-api-key` header. A placeholder in another header or in the URL stays a placeholder, so a provider that echoes it cannot return the real key.
* A custom API gets its secret in any request header and in the query string, never in the path. Pick a base URL you trust: a host that echoes requests shows the secret to the sandbox.
* Boat renews Claude and ChatGPT sign-ins behind the proxy. The sandbox never sees a renew token.
### What the proxy covers
| Proxied | Not proxied |
| - | - |
| Claude sign-in and Anthropic API key (Claude Code) | AWS Bedrock (`claude-bedrock`, `codex-bedrock`) |
| ChatGPT sign-in and OpenAI API key (Codex) | Kimi Code sign-in (`kimi-subscription`) |
| OpenRouter, LLM Gateway, DeepSeek, Moonshot API keys | |
| Mistral API key and Mistral Vibe sign-in | |
| Custom APIs | |
Bedrock signs each request with AWS keys, so there is nothing to swap. The Kimi Code CLI renews its sign-in itself. While the proxy is on, Boat withholds these credentials from sandboxes. Use a Moonshot API key in place of the Kimi sign-in.
### Turn it on
The switch is per account: one for you, one for each organization. Only an organization owner can change the organization switch. On the dashboard, open **Agents & Proxying**, then the **Proxying** tab. It holds the switch, the custom APIs and the AI usage, for the account in view: you, or the organization you selected.
A sandbox goes through the proxy when either switch is on:
* the switch of the account that owns its credential profile, or
* the switch of the organization that pays for the sandbox. An organization can make sure that no real key enters its sandboxes, whoever's profile they use.
Running sandboxes switch at their next start. Stop and resume a sandbox to switch it now.
```bash CLI theme={null}
boat ai proxy # state and price
boat ai proxy on
boat --org acme ai proxy on
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/ai-proxy" -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X PUT "$BOAT_API_BASE/ai-proxy" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled":true}'
curl -sS -X PUT "$BOAT_API_BASE/ai-proxy?org=acme" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled":true}'
```
```ts TypeScript theme={null}
const proxy = await sandbox.getAiProxy();
console.log(proxy.enabled, proxy.pricing);
await sandbox.updateAiProxy({ enabled: true });
await sandbox.updateAiProxy({ org: "acme", enabled: true });
```
```python Python theme={null}
from boat_sdk.models.update_ai_proxy_request import UpdateAiProxyRequest
proxy = sandbox.get_ai_proxy()
print(proxy.enabled, proxy.pricing)
sandbox.update_ai_proxy(UpdateAiProxyRequest(enabled=True))
sandbox.update_ai_proxy(UpdateAiProxyRequest(enabled=True), org="acme")
```
The proxy applies to sandboxes that use a profile of an account with the switch on. A sandbox that uses an organization profile follows the organization switch.
## Safe for third parties, with AI credentials
An environment marked [safe for third parties](/environments#safe-for-third-parties) passes nothing of yours. Turn on `proxyAiCredentials` on that environment to still pass AI credentials, as placeholders. The sandbox user can run the agents, but cannot take your keys. You can block the sandbox at any time.
`proxyAiCredentials` needs the proxy on for the account that owns the profile. If it is off, the call returns `400 ai_proxy_off`.
```bash CLI theme={null}
boat ai proxy on
boat env set customers --safe-for-third-parties true --proxy-ai-credentials true --credential-profile ci
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"safeForThirdParties":true,"proxyAiCredentials":true,"credentialProfileId":"ci"}'
```
```ts TypeScript theme={null}
await sandbox.updateEnvironment({
environmentId: envId,
safeForThirdParties: true,
proxyAiCredentials: true,
credentialProfileId: "ci",
});
```
```python Python theme={null}
from boat_sdk.models.update_sandbox_environment_request import UpdateSandboxEnvironmentRequest
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
safe_for_third_parties=True,
proxy_ai_credentials=True,
credential_profile_id="ci",
))
```
## Environments
An environment can name the profile its sandboxes get, with `credentialProfileId` (an id or a name). `null`, or `--credential-profile default` in the CLI, means the default profile of the sandbox owner. Like every environment change, this makes a new version. Running sandboxes move at `boat env upgrade`. See [Environments](/environments/access#ai-credentials).
## Usage
For each proxied sandbox, Boat counts requests and errors, and the tokens per UTC day, credential and model. The token counts are the numbers the provider reports in its replies: input, output, cache read and cache write. A sandbox that holds real keys has no usage here, because its requests do not go through Boat.
```bash CLI theme={null}
boat ai usage # every sandbox of the account in scope
boat ai usage bx_23456789 --days 7 # one sandbox, per day and model
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/ai-usage?days=30" -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/sandboxes/bx_23456789/ai-usage?days=7" -H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const account = await sandbox.getAiUsage({ days: 30 });
for (const s of account.sandboxes) console.log(s.sandboxId, s.totals.requests, s.dollars);
const one = await sandbox.getSandboxAiUsage({ sandboxId: "bx_23456789", days: 7 });
console.log(one.blocked, one.totals.inputTokens, one.totals.outputTokens);
```
```python Python theme={null}
account = sandbox.get_ai_usage(days=30)
for s in account.sandboxes:
print(s.sandbox_id, s.totals.requests, s.dollars)
one = sandbox.get_sandbox_ai_usage("bx_23456789", days=7)
print(one.blocked, one.totals.input_tokens, one.totals.output_tokens)
```
The account view covers the wallet in scope: your own, or an organization with `--org`, `org` or `X-Boat-Org`.
### Block a sandbox
Block a sandbox to stop its AI requests at once, running or stopped. The proxy refuses its placeholders with `403`. Unblock it to accept them again. Blocking has no effect on a sandbox that holds real keys (proxy off). The sandbox creator and the managers of its profile can block it.
```bash CLI theme={null}
boat ai block bx_23456789
boat ai unblock bx_23456789
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/sandboxes/bx_23456789/ai-access" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"blocked":true}'
```
```ts TypeScript theme={null}
await sandbox.setSandboxAiAccess({ sandboxId: "bx_23456789", blocked: true });
await sandbox.setSandboxAiAccess({ sandboxId: "bx_23456789", blocked: false });
```
```python Python theme={null}
from boat_sdk.models.set_sandbox_ai_access_request import SetSandboxAiAccessRequest
sandbox.set_sandbox_ai_access("bx_23456789", SetSandboxAiAccessRequest(blocked=True))
sandbox.set_sandbox_ai_access("bx_23456789", SetSandboxAiAccessRequest(blocked=False))
```
## Pricing
Profiles, custom APIs and usage tracking are free. The proxy costs money, paid in Boat time like named snapshots:
| Charge | Price | Paid by |
| - | - | - |
| Each UTC day the proxy is on | \$1 | The account with the switch on |
| Proxied requests | \$1 per 1,000 | The wallet each sandbox bills |
`dollars` in the usage responses is the request charge for the period. The provider bills your tokens as usual, on your own provider account.
## Related
* [Environments](/environments)
* [Organizations & teams](/organizations)
* [Integrated agents](/integrated-agents)
* [Pricing](/pricing)
* [CLI reference](/cli-reference#boat-ai)
# API Keys
Source: https://docs.boat.dev/api-keys
Scoped, expiring Boat API keys. Least privilege for production.
A Boat API key authenticates servers, CI and the in-sandbox CLI.
* Every **new** key expires.
* Every **new** key has an explicit scope. The scope is on the key, and the Boat API enforces it.
* The bearer header does not change.
Treat API keys as secrets. Store them as `BOAT_API_KEY`. Do not commit them, print them in logs or bake them into images.
Existing keys stay account-wide until you reissue them. Reissue every key that still has no expiry.
## Main task
1. [Create a key](/api-keys/create-and-list#create-a-key) with the smallest scope that does the job.
2. [Store it](/api-keys/store-rotate-revoke#store-a-key) as `BOAT_API_KEY` in your platform secret manager.
3. [Use it](/api-keys/create-and-list#use-the-key) from the CLI, the API or an SDK.
4. [Rotate or revoke it](/api-keys/store-rotate-revoke) when you need to.
## Production guidance
* Use one key per job.
* Use the shortest TTL that works for you.
* Use `read-only` or `ci` unless you truly need `admin`.
* Reissue legacy keys.
## Learn more
Actions, presets, the in-sandbox key and scope errors.
Create a key, use it, list your keys and see the usage of one key.
Where to keep a key, how to replace its secret and how to turn it off.
# Create and list keys
Source: https://docs.boat.dev/api-keys/create-and-list
Create a scoped Boat API key, use it, list your keys and see the usage of one key.
## Create a key
To create a key, you need one of these:
* A browser session: `boat login` with no key, or the dashboard.
* A token that is already admin-scoped.
The create endpoint is `POST /api/v1/api-keys/scoped`.
During a credential rollout, Boat can turn off key creation for a short time. `GET /api/v1/api-keys` reports this in `catalog.scopedCreationEnabled`. While creation is off, the create endpoint returns a typed 503.
```bash theme={null}
boat api-key create my-project --ttl 90d --preset ci --sandbox bx_123
boat api-key create readonly --ttl 30d --preset read-only
boat api-key create admin --ttl 7d --preset admin
boat api-key create custom --ttl 24h --actions sandbox.read,exec,file.read
```
| Flag | Rule |
| - | - |
| `--ttl` | The maximum is 365 days. |
| `--sandbox`, `--env` | You can give each one more than one time. |
| `--actions`, `--preset` | Use one or the other, not both. |
| No `--actions` and no `--preset` | The key is admin-scoped with a 90-day TTL. |
For the actions and presets, read [Scopes](/api-keys/scopes).
Boat shows the secret one time only. In scripts, capture it like this:
```bash theme={null}
BOAT_API_KEY="$(boat api-key create my-project --preset ci --ttl 90d --json | jq -r '.secret')"
```
You can also use the **API Keys** tab in the dashboard. It has expiry presets, action presets, a raw action picker, and sandbox and environment selectors.
## Use the key
```bash CLI theme={null}
boat login --key-stdin --json <<< "$BOAT_API_KEY"
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/me" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```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 me = await sandbox.me();
console.log(me.user.login);
```
```python Python theme={null}
import os
from boat_sdk import ApiClient, Configuration
from boat_sdk.api.boat_api import BoatApi
config = Configuration(host="https://boat.dev/api/v1", access_token=os.environ["BOAT_API_KEY"])
with ApiClient(config) as client:
sandbox = BoatApi(client)
me = sandbox.me()
print(me.user.login)
```
## What a key cannot do
* Rotate and revoke need a browser session.
* Create needs a browser session or an admin-scoped token. A credential that can make more credentials defeats least privilege.
* To approve an agent claim, you need a browser session. API keys cannot approve agent claims. This includes admin keys and legacy keys.
Use `boat api-key create|rotate|revoke` after a browser sign-in, or use the [API Keys](https://boat.dev/dashboard?tab=api-keys) tab.
## List
Every surface can list keys. This is the only key operation that every surface can do. Boat never returns the secrets.
Each row shows:
* The id, the name, the prefix and the last four characters
* The scope and the expiry
* The last use
* The request total for the last 30 days
* How many sandboxes and Agents the key created that still exist
Boat labels expired keys and keys that expire soon.
Restricted API keys get an empty `apiKeys` list. Only a browser or CLI session, or an unrestricted account key, gets the account-wide list.
```bash theme={null}
boat api-key list
boat api-key list --all # include per-sandbox machine keys
```
```ts TypeScript theme={null}
const keys = await sandbox.apiKeys();
for (const key of keys.apiKeys) {
console.log(key.id, key.name, key.usage.requests, key.resources.total);
}
```
```python Python theme={null}
keys = sandbox.api_keys()
for key in keys.api_keys:
print(key.id, key.name, key.usage.requests, key.resources.total)
```
## See usage for one key
`boat api-key usage ` prints the 30-day request total and the count of live resources. These are the same numbers as in the list.
* Add `--verbose` to see the split between sandboxes and Agents, and the list of created resources.
* The matching API is `GET /api-keys/{id}/usage`.
* Usage still works after you revoke the key, if you still have the id.
Revoke stops the secret. It does not delete the sandboxes or Agents that the key created.
```bash theme={null}
boat api-key usage sak_123
boat api-key usage sak_123 --verbose
```
# Scopes
Source: https://docs.boat.dev/api-keys/scopes
What a scoped Boat API key can do: actions, presets, the in-sandbox key and scope errors.
## How Boat checks a request
Boat grants a request only when **both** of these are true:
1. The action is in the action set of the key.
2. The target sandbox is in the sandbox set of the key, or in one of its environments.
The default is deny. Boat refuses unknown routes for scoped keys.
## Snapshots and environments
| You want to | The key needs |
| - | - |
| Create a sandbox from a named snapshot | `sandbox.create` for the destination, and `snapshot.read` access to the source |
| Replace a named snapshot | Access to its existing source, and access to the sandbox that you save |
A destination environment does not give access to snapshots from other environments.
## Actions
| Action | What it unlocks |
| - | - |
| `sandbox.create` | Create a sandbox |
| `sandbox.read` | List and inspect sandboxes |
| `sandbox.update` | Rename, recover, and other sandbox writes |
| `sandbox.stop` | Stop |
| `sandbox.resume` | Resume |
| `sandbox.fork` | Fork |
| `sandbox.delete` | Delete |
| `sandbox.delete-own` | Delete only the sandboxes this key created |
| `agent.prompt` | Prompt the sandbox agent |
| `exec` | Run a command |
| `file.read` / `file.write` | Read or write files |
| `ssh` | SSH, scp, and port forward |
| `desktop` | Desktop stream |
| `host` | Host a port |
| `snapshot.read` / `snapshot.write` | Snapshots |
| `environment.read` / `environment.write` | Environments |
| `account.read` | `/me`, limits, list keys, organization discovery |
| `account.admin` | Billing, teams, webhooks, identities, account writes |
| `*` | Admin wildcard |
## Presets
| Preset | Use |
| - | - |
| `read-only` | Inspect sandboxes, files, snapshots, environments |
| `full-sandbox` | Operate a sandbox without create / resume / fork / delete / account writes |
| `ci` | Everything in `full-sandbox`, plus create, resume, fork, and delete the sandboxes this key created. No account admin |
| `admin` | `*` |
A key keeps the actions that it had when you created it. Resume, SSH and `sandbox.delete-own` joined the `ci` preset later. An older `ci` key does not get them. To get them, create a new `ci` key.
## In-sandbox key
Boat writes a credential into each sandbox. This credential is scoped to **that sandbox** only.
| It can | It cannot |
| - | - |
| Prompt, exec, read and write files | Create, resume, fork or delete sandboxes |
| SSH, desktop, host | Write environments |
| Snapshot its own sandbox | Administer the account |
If an attacker takes control of a sandbox, they get access to that one sandbox only.
## Errors
Scoped keys return typed 403 errors:
| `error` | Meaning |
| - | - |
| `api_key_expired` | The TTL elapsed |
| `api_key_action_forbidden` | The action is not on the key |
| `api_key_sandbox_forbidden` | The sandbox or the environment is not on the key |
The bearer header and the SDK configuration do not change.
# Store, rotate and revoke
Source: https://docs.boat.dev/api-keys/store-rotate-revoke
Where to store a Boat API key, how to replace its secret and how to turn it off.
## Store a key
| Platform | Store as |
| - | - |
| Railway | Variable named `BOAT_API_KEY` |
| GitHub Actions | Repository or environment secret named `BOAT_API_KEY` |
| Docker Compose | Environment variable or secret named `BOAT_API_KEY` |
| Kubernetes | Secret mounted or exposed as `BOAT_API_KEY` |
Do not put API keys in:
* Dockerfiles
* Images
* Source code
* Shell history
* Public CI logs
## Rotate a key
Rotate does these things:
* It revokes the old secret immediately.
* It keeps the id, the scope and the expiry date of the key.
* It replaces the secret and shows the new secret one time only.
Rotate does not extend the lifetime of the key. It does not change a legacy key into a scoped key.
You cannot rotate an expired scoped key. The API returns `409 api_key_expired`. Create a replacement key instead.
Rotate needs a browser session. Read [What a key cannot do](/api-keys/create-and-list#what-a-key-cannot-do).
### Rotate with downtime
Use **Rotate** only when you can update the deployed secret immediately.
1. Rotate the key. Run `boat api-key rotate `, or use the dashboard. To find the id, run `boat api-key list`.
2. Copy the new secret.
3. Update `BOAT_API_KEY` in your platform secret manager.
4. Redeploy or restart the workers that use the key.
### Replace without downtime
1. Create a new key.
2. Update the platform secret to the new key.
3. Redeploy or restart the workers.
4. When the new deployment is live, revoke the old key.
## Revoke a key
Run `boat api-key revoke `, or click **Revoke** in the dashboard. Revoke needs a browser session.
* Revoke turns off the key immediately.
* The next Boat API request with that secret fails with an auth error. This includes existing CLI configs and running processes.
* The sandboxes and Agents that the key created stay.
* `boat api-key usage ` still shows their totals.
# Create webhook
Source: https://docs.boat.dev/api/reference/account/create-webhook
openapi/boat-v1.yaml POST /webhooks
Create an account-wide sandbox lifecycle webhook endpoint.
# Delete webhook
Source: https://docs.boat.dev/api/reference/account/delete-webhook
openapi/boat-v1.yaml DELETE /webhooks/{webhookId}
Delete a sandbox lifecycle webhook endpoint and its queued deliveries.
# Get account data-retention policy
Source: https://docs.boat.dev/api/reference/account/get-account-data-retention-policy
openapi/boat-v1.yaml GET /account/data-retention
Read the account zero-data-retention setting.
# Get API key usage
Source: https://docs.boat.dev/api/reference/account/get-api-key-usage
openapi/boat-v1.yaml GET /api-keys/{apiKeyId}/usage
Get the 30-day request total and created sandboxes and Agents for one API key.
# Get Boat limits
Source: https://docs.boat.dev/api/reference/account/get-boat-limits
openapi/boat-v1.yaml GET /limits
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 read.
# Get Boat secrets setup
Source: https://docs.boat.dev/api/reference/account/get-boat-secrets-setup
openapi/boat-v1.yaml GET /secrets
Returns the environment variables and secret files configured for sandboxes.
# Get current Boat user
Source: https://docs.boat.dev/api/reference/account/get-current-boat-user
openapi/boat-v1.yaml GET /me
Returns GitHub identity for the authenticated Boat account.
# Get deletion operation
Source: https://docs.boat.dev/api/reference/account/get-deletion-operation
openapi/boat-v1.yaml GET /deletion-operations/{operationId}
Poll an accepted sandbox or snapshot deletion operation.
# Get OpenTelemetry export
Source: https://docs.boat.dev/api/reference/account/get-opentelemetry-export
openapi/boat-v1.yaml GET /telemetry
Read the account's OTLP endpoint, header names, and last export result.
# Get webhook
Source: https://docs.boat.dev/api/reference/account/get-webhook
openapi/boat-v1.yaml GET /webhooks/{webhookId}
Get one sandbox lifecycle webhook endpoint without its signing secret.
# List API keys
Source: https://docs.boat.dev/api/reference/account/list-api-keys
openapi/boat-v1.yaml GET /api-keys
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 on the key.
# List GitHub repositories available to Boat
Source: https://docs.boat.dev/api/reference/account/list-github-repositories-available-to-sandbox
openapi/boat-v1.yaml GET /repos
Returns GitHub repositories grouped by installation plus the current selected repositories for new Sandboxes.
# List organizations
Source: https://docs.boat.dev/api/reference/account/list-organizations
openapi/boat-v1.yaml GET /orgs
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 `PATCH /orgs/active`.
# List webhooks
Source: https://docs.boat.dev/api/reference/account/list-webhooks
openapi/boat-v1.yaml GET /webhooks
List account-wide sandbox lifecycle webhook endpoints.
# Remove OpenTelemetry export
Source: https://docs.boat.dev/api/reference/account/remove-opentelemetry-export
openapi/boat-v1.yaml DELETE /telemetry
Stop the export and remove the account's OTLP endpoint.
# Rotate webhook signing secret
Source: https://docs.boat.dev/api/reference/account/rotate-webhook-signing-secret
openapi/boat-v1.yaml POST /webhooks/{webhookId}/rotate
Replace a webhook signing secret and return the new secret once.
# Select repository for sandboxes
Source: https://docs.boat.dev/api/reference/account/select-repository-for-sandboxes
openapi/boat-v1.yaml POST /repos
Idempotently selects one repository for the sandbox environment. Use `databaseId` from `GET /repos` as `repositoryId`; selecting an already-selected repository updates its `baseBranch`.
# Set the active organization
Source: https://docs.boat.dev/api/reference/account/set-active-organization
openapi/boat-v1.yaml PATCH /orgs/active
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. Sandboxes already running keep the wallet they were created with; leaving or deleting the organization resets the account to personal.
# Set OpenTelemetry export
Source: https://docs.boat.dev/api/reference/account/set-opentelemetry-export
openapi/boat-v1.yaml PUT /telemetry
Set or replace the account's OTLP endpoint and send a test export.
# Update account data-retention policy
Source: https://docs.boat.dev/api/reference/account/update-account-data-retention-policy
openapi/boat-v1.yaml PATCH /account/data-retention
Enable or disable account zero data retention using a sandbox session.
# Update Boat secrets setup
Source: https://docs.boat.dev/api/reference/account/update-boat-secrets-setup
openapi/boat-v1.yaml POST /secrets
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.
# Update webhook
Source: https://docs.boat.dev/api/reference/account/update-webhook
openapi/boat-v1.yaml PATCH /webhooks/{webhookId}
Update a sandbox lifecycle webhook endpoint.
# Attach to a detached command
Source: https://docs.boat.dev/api/reference/agent/attach-command
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/commands/{processId}/stream
Stream the output of a command started with detached: true as it writes it, until it ends. Reconnect with the offsets every 10 minutes to follow it with no time limit.
# Configure sandbox SSH key
Source: https://docs.boat.dev/api/reference/agent/configure-sandbox-ssh-key
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/sshkey
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.
This is also how you reach your own machine from inside a sandbox without the CLI: authorize the key, then open a reverse tunnel with stock OpenSSH, and a port on your machine answers at `127.0.0.1:` inside the sandbox for as long as the ssh process runs.
```bash
ssh -o ExitOnForwardFailure=yes -i ~/.ssh/id_ed25519 -N -R 7777:127.0.0.1:7777 user@
```
`boat forward --reverse --local 7777` is the same tunnel with the key handling and redial done for you.
# Get a download URL for a sandbox file
Source: https://docs.boat.dev/api/reference/agent/create-download-url
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/files/download-url
A short-lived signed URL the sandbox serves itself. GET it to download a file of any size.
# Get an upload URL for a sandbox file
Source: https://docs.boat.dev/api/reference/agent/create-upload-url
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/files/upload-url
A short-lived signed URL the sandbox serves itself. PUT a file of any size to it.
# Download Sandbox artifact
Source: https://docs.boat.dev/api/reference/agent/download-sandbox-artifact
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/artifacts
Download a file from a sandbox by its path, returned as a binary artifact.
# Execute Sandbox command
Source: https://docs.boat.dev/api/reference/agent/execute-sandbox-command
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/commands
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 arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{"type":"started"}`, then `{"type":"stdout"|"stderr","data":"..."}` per chunk, and last `{"type":"exit",...}` (the synchronous result without stdout/stderr) or `{"type":"error","error":"...","message":"..."}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. A sandbox that is not starting (`error`, `stopped`) returns 409 sandbox_not_ready with `retryable: false` and its `state` at once: resume or recover it first. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox. Every command and its output are kept 90 days in the command history (`/sandboxes/{sandboxId}/command-history`), readable while the sandbox is stopped.
# Get a command from the history
Source: https://docs.boat.dev/api/reference/agent/get-command
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/command-history/{commandId}
Get one command's record: its text, mode, status, exit code and output size.
# Get command status
Source: https://docs.boat.dev/api/reference/agent/get-command-status
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/commands/{processId}
Get the status and recent log output of a detached command running in a sandbox. Use tailBytes to limit how much log is returned.
# Get desktop streaming URL
Source: https://docs.boat.dev/api/reference/agent/get-desktop-streaming-url
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/desktop
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.
# Get prompt run status
Source: https://docs.boat.dev/api/reference/agent/get-prompt-run-status
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/prompts/{promptId}
Returns first-class status for a queued/running/finished prompt so clients do not infer completion from sandbox state and events.
# Interrupt running work
Source: https://docs.boat.dev/api/reference/agent/interrupt-running-agent-work
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/interrupt
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).
# List the command history
Source: https://docs.boat.dev/api/reference/agent/list-command-history
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/command-history
List the commands run in a sandbox in the last 90 days, newest first. Works while the sandbox is stopped.
# List boat conversations
Source: https://docs.boat.dev/api/reference/agent/list-sandbox-conversations
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/conversations
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 `conversationId` would continue. Pass an `id` back as `conversationId` on `POST /prompt` to resume that thread, or as `conversation` on `POST /steer`, `POST /interrupt` and `GET /events` to scope those. See [Integrated agents](/integrated-agents).
# List boat events
Source: https://docs.boat.dev/api/reference/agent/list-sandbox-events
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/events
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 extensible. Clients can long-poll this endpoint with `sort=asc` and a cursor to stream responses. Response events expose agent text, streaming partials via `data.is_streaming`, and tool calls/results via `data.tools`.
# List sandbox processes
Source: https://docs.boat.dev/api/reference/agent/list-sandbox-processes
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/processes
List the processes in a running sandbox, or the last stored sample of a stopped one.
# Prompt Sandbox
Source: https://docs.boat.dev/api/reference/agent/prompt-sandbox-agent
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/prompt
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`.
A Sandbox runs many conversations in parallel. Set `new: true` to start a fresh one, `conversationId` to continue a specific one, or omit both to continue the most-recently-active conversation; the response returns the `conversationId`. See [Integrated agents](/integrated-agents).
# Read a command's output
Source: https://docs.boat.dev/api/reference/agent/read-command-logs
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/command-history/{commandId}/logs
Read the stored stdout or stderr of a command from a byte offset. Works while the sandbox is stopped.
# Read Sandbox file
Source: https://docs.boat.dev/api/reference/agent/read-sandbox-file
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/files
Read a file from a sandbox by its path, as UTF-8 text by default or base64 for binary content.
# Steer a running turn
Source: https://docs.boat.dev/api/reference/agent/steer-a-running-turn
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/steer
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.
Where the harness has a native mid-turn primitive (Claude Code, Codex, pi, Prime Agent) nothing is interrupted and the response has `native: true`. Where it does not (OpenCode), Boat interrupts that turn and immediately continues the SAME conversation with the instruction, keeping the session and its memory, and the response has `native: false`.
Refused with **409 `no_running_turn`** when the conversation has nothing in flight; queue work with `POST /prompt` instead. `error.details.reason` says why: `turn_ended` (with `error.details.lastTurn.status` and `.error` of the newest turn), `turn_not_started` (the turn is starting; retry in a moment), `no_turn`, `not_running` (the sandbox is not running) or `delivery_failed` (the sandbox did not accept the steer; check the turn before sending more work). The steer shows up in `GET /events` as a `steer` event. See [Integrated agents](/integrated-agents).
# Stop a detached command
Source: https://docs.boat.dev/api/reference/agent/stop-command
openapi/boat-v1.yaml DELETE /sandboxes/{sandboxId}/commands/{processId}
Stop a command started with detached: true, and every process it started. The response holds its final history record.
# Write Sandbox file
Source: https://docs.boat.dev/api/reference/agent/write-sandbox-file
openapi/boat-v1.yaml PUT /sandboxes/{sandboxId}/files
Write or overwrite a file in a sandbox at a given path, as UTF-8 text or base64-encoded binary content.
# Add another API key to a credential
Source: https://docs.boat.dev/api/reference/ai-credentials/add-credential-account
openapi/boat-v1.yaml POST /credential-profiles/{profile}/accounts/{credential}
Keep a second key ready to switch to.
# Block or unblock sandbox AI access
Source: https://docs.boat.dev/api/reference/ai-credentials/block-or-unblock-sandbox-ai-access
openapi/boat-v1.yaml PUT /sandboxes/{sandboxId}/ai-access
Refuse or accept a sandbox's AI placeholders again.
# Create a credential profile
Source: https://docs.boat.dev/api/reference/ai-credentials/create-credential-profile
openapi/boat-v1.yaml POST /credential-profiles
Create a personal or organization AI credential profile, empty or as a copy.
# Delete a credential profile
Source: https://docs.boat.dev/api/reference/ai-credentials/delete-credential-profile
openapi/boat-v1.yaml DELETE /credential-profiles/{profile}
Delete a profile that is not the default and that no environment names.
# Forget an account of a credential
Source: https://docs.boat.dev/api/reference/ai-credentials/forget-credential-account
openapi/boat-v1.yaml DELETE /credential-profiles/{profile}/accounts/{credential}/{account}
Delete an account; the one in use is replaced by another first.
# Get AI credentials proxy
Source: https://docs.boat.dev/api/reference/ai-credentials/get-ai-credentials-proxy
openapi/boat-v1.yaml GET /ai-proxy
Read the AI credentials proxy switch and its price.
# Get AI usage
Source: https://docs.boat.dev/api/reference/ai-credentials/get-ai-usage
openapi/boat-v1.yaml GET /ai-usage
Proxied AI usage of every sandbox of the wallet in scope.
# Get sandbox AI usage
Source: https://docs.boat.dev/api/reference/ai-credentials/get-sandbox-ai-usage
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/ai-usage
Proxied AI usage of one sandbox, per day, credential and model.
# List the accounts of a credential
Source: https://docs.boat.dev/api/reference/ai-credentials/list-credential-accounts
openapi/boat-v1.yaml GET /credential-profiles/{profile}/accounts/{credential}
Every account of one credential, the one in use first.
# List credential profiles
Source: https://docs.boat.dev/api/reference/ai-credentials/list-credential-profiles
openapi/boat-v1.yaml GET /credential-profiles
List the AI credential profiles you can use, yours and your organizations'.
# Remove a credential profile credential
Source: https://docs.boat.dev/api/reference/ai-credentials/remove-credential-profile-credential
openapi/boat-v1.yaml DELETE /credential-profiles/{profile}/keys/{credential}
Remove one API key or sign-in from a profile.
# Remove a custom API
Source: https://docs.boat.dev/api/reference/ai-credentials/remove-custom-api
openapi/boat-v1.yaml DELETE /credential-profiles/{profile}/custom-apis/{name}
Remove one custom API from a profile.
# Set a credential profile API key
Source: https://docs.boat.dev/api/reference/ai-credentials/set-credential-profile-api-key
openapi/boat-v1.yaml PUT /credential-profiles/{profile}/keys/{credential}
Set one API key in a profile.
# Set a custom API
Source: https://docs.boat.dev/api/reference/ai-credentials/set-custom-api
openapi/boat-v1.yaml PUT /credential-profiles/{profile}/custom-apis/{name}
Add or replace a custom API: a secret and its HTTPS base URL.
# Switch a credential to another account
Source: https://docs.boat.dev/api/reference/ai-credentials/switch-credential-account
openapi/boat-v1.yaml PUT /credential-profiles/{profile}/accounts/{credential}/{account}/active
Out of credits on one account: every sandbox on the profile moves to another one at once.
# Turn the AI credentials proxy on or off
Source: https://docs.boat.dev/api/reference/ai-credentials/turn-the-ai-credentials-proxy-on-or-off
openapi/boat-v1.yaml PUT /ai-proxy
Give sandboxes placeholder keys instead of real keys, or stop.
# Update a credential profile
Source: https://docs.boat.dev/api/reference/ai-credentials/update-credential-profile
openapi/boat-v1.yaml PUT /credential-profiles/{profile}
Rename a profile, or make it its owner's default.
# Add environment repository
Source: https://docs.boat.dev/api/reference/environments/add-environment-repo
openapi/boat-v1.yaml POST /environments/{environmentId}/repos
Adds a repository (or updates its base branch) by database id from the repository list. Mints a new immutable version.
# Create a sandbox environment
Source: https://docs.boat.dev/api/reference/environments/create-sandbox-environment
openapi/boat-v1.yaml POST /environments
Create a new named environment. It starts on version 1 with all fine-grained flags on and `safeForThirdParties` off.
# Remove environment repository
Source: https://docs.boat.dev/api/reference/environments/delete-environment-repo
openapi/boat-v1.yaml DELETE /environments/{environmentId}/repos/{repositoryId}
Removes one repository from the environment's selection. Mints a new immutable version.
# Remove environment secret file
Source: https://docs.boat.dev/api/reference/environments/delete-environment-secret-file
openapi/boat-v1.yaml DELETE /environments/{environmentId}/secret-files
Removes the secret file at `path`. Mints a new immutable version.
# Remove environment variable
Source: https://docs.boat.dev/api/reference/environments/delete-environment-var
openapi/boat-v1.yaml DELETE /environments/{environmentId}/vars/{key}
Removes a single variable. Mints a new immutable version.
# Delete a sandbox environment
Source: https://docs.boat.dev/api/reference/environments/delete-sandbox-environment
openapi/boat-v1.yaml DELETE /environments/{environmentId}
Soft-deletes an environment. The default environment cannot be deleted, and at least one environment is always kept.
# List Sandbox environments
Source: https://docs.boat.dev/api/reference/environments/list-sandbox-environments
openapi/boat-v1.yaml GET /environments
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.
# Write environment secret file
Source: https://docs.boat.dev/api/reference/environments/set-environment-secret-file
openapi/boat-v1.yaml PUT /environments/{environmentId}/secret-files
Adds or replaces a single secret file by path. Mints a new immutable version.
# Set environment variable
Source: https://docs.boat.dev/api/reference/environments/set-environment-var
openapi/boat-v1.yaml PUT /environments/{environmentId}/vars/{key}
Sets or replaces a single variable without reading or rewriting the rest. Mints a new immutable version.
# Update a sandbox environment
Source: https://docs.boat.dev/api/reference/environments/update-sandbox-environment
openapi/boat-v1.yaml PUT /environments/{environmentId}
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.
# Upgrade sandboxes to an environment's latest version
Source: https://docs.boat.dev/api/reference/environments/upgrade-sandbox-environment
openapi/boat-v1.yaml POST /environments/{environmentId}/upgrade
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.
# Create sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/create-sandbox
openapi/boat-v1.yaml POST /sandboxes
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.
# Fork sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/fork-sandbox
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/fork
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.
# Get sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/get-sandbox
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}
Poll this endpoint after create, stop, resume, or fork operations.
# Get sandbox usage
Source: https://docs.boat.dev/api/reference/sandboxes/get-sandbox-usage
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/usage
Machine time one sandbox consumed and its cost, over its life or a billing window, for per-sandbox billing of your own users.
# Get a stop by id
Source: https://docs.boat.dev/api/reference/sandboxes/get-stop
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/stops/{stopId}
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.
# List sandboxes
Source: https://docs.boat.dev/api/reference/sandboxes/list-sandboxes
openapi/boat-v1.yaml GET /sandboxes
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.
# Permanently delete sandbox data
Source: https://docs.boat.dev/api/reference/sandboxes/permanently-delete-sandbox-data
openapi/boat-v1.yaml DELETE /sandboxes/{sandboxId}
Confirm and accept irreversible background deletion of a sandbox.
# Recover sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/recover-sandbox
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/recover
Power-cycle the machine of a sandbox that stopped responding, without touching its disk.
# Resume sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/resume-sandbox
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/resume
Resume a stopped sandbox from its snapshot, optionally with a different environment or time-to-live.
# Share sandbox with the organization
Source: https://docs.boat.dev/api/reference/sandboxes/share-sandbox
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/share
Let every member of the organization that pays for this sandbox use it.
Your personal logins (GitHub token, Claude and Codex logins, environment secrets,
the sandbox's own CLI key) are never pushed to it again and are wiped off its disk
at its next start, so a teammate never acts as you. Files you wrote stay. One-way:
the sandbox stays like a `noEnv` sandbox from then on. A running sandbox stays
`view` for the organization until you stop and resume it (`restartRequired`).
Only the person who created the sandbox can share it, and only a sandbox billed to
an organization. Sharing an already shared sandbox is a no-op.
# Stop and archive sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/stop-and-archive-sandbox
openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/stop
Stop active work and archive/snapshot the sandbox for later resume or fork.
A stop always saves the sandbox's disk first. If that save is failing, the stop is
refused and the sandbox keeps running so your work is not discarded, we retry
automatically and email you. You are not billed for time spent in that state.
The stop is an operation: the response and the sandbox carry it as `stop`, with an
`id` and a `status`. Poll `GET /sandboxes/{sandboxId}` until `stop.status` is
`completed`. A failed attempt shows `failing` with its `error` and is retried
until the sandbox archives; commands and prompts you send meanwhile do not cancel
it. Only a resume ends it early (`superseded`). Calling stop again while one is
pending returns the same `id`.
Set `force: true` to stop anyway, keeping the last successful snapshot and
losing everything written since then. This is irreversible; only reach for it
after a stop has already failed. A force on a stop that is already pending
escalates that stop.
# Update sandbox
Source: https://docs.boat.dev/api/reference/sandboxes/update-sandbox
openapi/boat-v1.yaml PATCH /sandboxes/{sandboxId}
Update a sandbox's name, time-to-live, or the subdomain it is hosted on.
# Share a named snapshot
Source: https://docs.boat.dev/api/reference/snapshots/create-snapshot-share
openapi/boat-v1.yaml POST /named-snapshots/{name}/shares
Make a secret code that lets any Boat account create a sandbox from this named snapshot (`boat snapshot share ` in the CLI). The response shows the code once; Boat stores only a hash. Re-saving the name changes what the code deploys. Removing the name removes its codes. Everything on the disk is shared, so do not keep secrets in files on it. Needs `snapshot.write`.
# Delete a named snapshot
Source: https://docs.boat.dev/api/reference/snapshots/delete-named-snapshot
openapi/boat-v1.yaml DELETE /named-snapshots/{name}
Remove a named snapshot and release its storage (`boat snapshot rm ` in the CLI). Sandboxes already deployed from it are unaffected.
# Get latest boat snapshot
Source: https://docs.boat.dev/api/reference/snapshots/get-latest-sandbox-snapshot
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/snapshots/latest
Return the most recent completed snapshot for this sandbox, or `null` if it has none.
# Get a named snapshot
Source: https://docs.boat.dev/api/reference/snapshots/get-named-snapshot
openapi/boat-v1.yaml GET /named-snapshots/{name}
Get a named snapshot and its status. Poll this after saving one until the status settles at ready or failed.
# Get snapshot download
Source: https://docs.boat.dev/api/reference/snapshots/get-snapshot-download
openapi/boat-v1.yaml GET /snapshots/{snapshotId}/download
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 you.
# Download a file or folder from a snapshot
Source: https://docs.boat.dev/api/reference/snapshots/get-snapshot-file
openapi/boat-v1.yaml GET /snapshots/{snapshotId}/files
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 `tree` entries; docker volumes under `__dockervol__/`). An empty or `/` path downloads the whole snapshot as a tar. Folder responses set `X-Snapshot-File-Count`, `X-Snapshot-Total-Size-Bytes` and `X-Snapshot-Skipped-Base-Image-Files` headers; both response shapes set `X-Snapshot-Entry-Kind` (`file` or `dir`). File responses accept a single `Range: bytes=` header and answer 206 with `Content-Range`, so large files can be downloaded in parts and resumed.
# Get snapshot file tree
Source: https://docs.boat.dev/api/reference/snapshots/get-snapshot-tree
openapi/boat-v1.yaml GET /snapshots/{snapshotId}/tree
List the files and folders captured in a snapshot, with sizes. Returns a flat list of entries you can render as a tree.
# List named snapshots
Source: https://docs.boat.dev/api/reference/snapshots/list-named-snapshots
openapi/boat-v1.yaml GET /named-snapshots
List your named snapshots, newest first.
# List boat snapshots
Source: https://docs.boat.dev/api/reference/snapshots/list-sandbox-snapshots
openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/snapshots
List visible completed snapshots for one sandbox with uncapped cursor pagination.
# List share codes of a named snapshot
Source: https://docs.boat.dev/api/reference/snapshots/list-snapshot-shares
openapi/boat-v1.yaml GET /named-snapshots/{name}/shares
List the share codes of a named snapshot, active and revoked (`boat snapshot shares ` in the CLI). The full codes are not returned. Needs `snapshot.read`.
# List snapshots
Source: https://docs.boat.dev/api/reference/snapshots/list-snapshots
openapi/boat-v1.yaml GET /snapshots
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.
# Permanently delete snapshot data
Source: https://docs.boat.dev/api/reference/snapshots/permanently-delete-snapshot-data
openapi/boat-v1.yaml DELETE /snapshots/{snapshotId}
Confirm and accept irreversible background deletion of a snapshot.
# Revoke a share code
Source: https://docs.boat.dev/api/reference/snapshots/revoke-snapshot-share
openapi/boat-v1.yaml DELETE /named-snapshots/{name}/shares/{shareId}
Revoke a share code (`boat snapshot unshare ` in the CLI). The code stops creating new sandboxes. Sandboxes already created from it keep their own copy. Needs `snapshot.write`.
# Save a named snapshot
Source: https://docs.boat.dev/api/reference/snapshots/save-named-snapshot
openapi/boat-v1.yaml POST /named-snapshots
Freeze a sandbox's current state under a name (`boat snapshot ` 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`. Reusing one of your existing names replaces that snapshot's artifact once the new save is ready.
# Boat Public API v1
Source: https://docs.boat.dev/api/v1
Create, manage, prompt, observe, and expose sandboxes from your own products.
Use the Boat Public API from services, CI jobs, hosted workers, and product automation code. For clients with types, start with the [Boat SDKs](/sdks/overview), the [Python SDK](/sdks/python), or the [TypeScript/JavaScript SDK](/sdks/typescript).
## Recommended flow
1. Create a Boat API key with `boat api-key create` or in the dashboard.
2. Create a sandbox with `POST /sandboxes`. If the user continues earlier work, resume or fork a sandbox instead.
3. Poll `GET /sandboxes/{sandboxId}` until the sandbox is `ready` or `idle`.
4. Queue work with `POST /sandboxes/{sandboxId}/prompt`.
5. Read `GET /sandboxes/{sandboxId}/events` while the work runs.
6. If the user or your support team must see the computer live, use `POST /sandboxes/{sandboxId}/desktop`.
7. Stop (archive), resume, fork, or delete the sandbox as your retention policy requires.
The API does all that the Boat CLI does.
* Dedicated endpoints cover lifecycle, prompts, events, files, desktop, and snapshots.
* For all other actions, use [`POST /sandboxes/{sandboxId}/commands`](/api/reference/agent/execute-sandbox-command). Examples are in-sandbox tools like `host`, package installs, and your own scripts.
* For high-frequency or streaming control, run your own daemon in the sandbox. See [the daemon pattern](/platform-guide/agents#bring-your-own-harness-the-daemon-pattern).
## Base URL
```text theme={null}
https://boat.dev/api/v1
```
## Authentication
Send a Boat API key as a bearer token on each API request:
```bash theme={null}
curl -sS "https://boat.dev/api/v1/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
To create, rotate, and revoke service keys, use the `boat api-key` CLI command or the Boat dashboard. For the key lifecycle, see [API Keys](/api-keys).
Keep Boat API keys and returned desktop URLs secret. Desktop and VNC URLs can contain access tokens. Redact them before you log or store them.
`PATCH /account/data-retention` is the exception. It needs an interactive sandbox session and refuses API keys. A per-sandbox key works only on its sandbox. For reads across the account, use an account service key.
## Response envelope
Each v1 JSON response has an explicit field that tells success or failure:
```json theme={null}
{
"ok": true,
"type": "sandbox.list",
"sandboxes": []
}
```
| Field | Description |
| - | - |
| `ok` | `true` for success, `false` for failure. |
| `type` | Stable response or event discriminator, such as `sandbox.list`, `sandbox.created`, `sandbox.stopping`, or `prompt.queued`. |
## Error model
The HTTP status is the primary signal. Error bodies also use a structured JSON envelope:
```json theme={null}
{
"ok": false,
"type": "sandbox.error",
"status": 409,
"code": "provider_not_configured",
"message": "Prompting is locked until Codex is configured on the Agents page.",
"error": {
"code": "provider_not_configured",
"message": "Prompting is locked until Codex is configured on the Agents page.",
"status": 409,
"details": {
"provider": "codex",
"setupUrl": "https://boat.dev/dashboard?tab=agents"
}
},
"requestId": "req_..."
}
```
| Status | Typical codes | What to do |
| - | - | - |
| `400` | `invalid_json`, `prompt_required`, `provider_required`, `invalid_name`, `no_changes`, `invalid_path`, `invalid_timeout`, `invalid_env`, `unknown_environment`, `trial_auto_stop_required`, `fast_mode_not_supported` | Fix the request. |
| `400` | `machine_not_running` (desktop, browser, port hosting, SSH key) | The sandbox has no running machine. Resume it, then retry. |
| `401` | `unauthorized` | Provide a valid bearer token. |
| `402` | `billing_required`, `team_member_cap_reached` | Send the user to the returned billing URL, or ask the organization owner to raise the member's usage cap. |
| `403` | `trial_machine_class_not_allowed`, `org_suspended` | The requested machine size needs a payment method, or the organization wallet is suspended. |
| `404` | `not_found` | The sandbox or key does not exist anymore. Refresh your local state. |
| `409` | `account_not_ready`, `provider_not_configured`, `sandbox_not_promptable`, `resume_failed`, `fork_failed`, `sandbox_resuming`, `sandbox_stopping`, `sandbox_securing`, `snapshots_disabled`, `idempotency_in_progress`, `idempotency_key_reused` | Resolve the prerequisite or resource-state conflict. |
| `409` | `machine_not_running`, `sandbox_starting`, `sandbox_not_ready` (commands, files, processes) | See [Commands, files and processes](#commands-files-and-processes). |
| `429` | `rate_limited`, `daily_limit_reached`, `limit_reached`, `member_limit_reached` | Back off and show the limit message. |
| `500` | `http_500` and other `*_failed` codes | Retry idempotent calls with jitter. Include `requestId` when you contact support. |
| `502` | `sandbox_direct_failed` | See [Commands, files and processes](#commands-files-and-processes). |
| `503` | `browser_not_ready`, `ssh_host_key_unavailable` | Retry after a few seconds. |
### Commands, files and processes
These calls go to the machine of the sandbox:
* `POST /sandboxes/{sandboxId}/commands`
* `GET` and `PUT /sandboxes/{sandboxId}/files`
* The process calls
They can also fail because of the sandbox state.
| Status | Code | Retryable | Meaning |
| - | - | - | - |
| `409` | `machine_not_running` | No | The sandbox has no machine. It is stopped, or it never started. Call `POST /sandboxes/{sandboxId}/resume`, wait until `GET` reports `ready`, `idle` or `running`, then retry. |
| `409` | `sandbox_starting` | Yes | The sandbox is still starting. Retry every few seconds. |
| `409` | `sandbox_not_ready` | No | The sandbox is in a state that cannot run commands, such as `error` or `archived`. Resume it first. |
| `502` | `sandbox_direct_failed` | See `error.details.retryable` | The machine did not complete the call. When `retryable` is `true`, you can safely send the call again. A file read or write gives the same result again. A command with message `sandbox_restoring` did not run. A command with a different message possibly ran. Check its effect before you send it again. When `retryable` is `false` (a command that failed or timed out), the command can still be running. Do not run it again without a check. |
| `502` | `sandbox_direct_failed` with message `sandbox_restoring` | Yes | The sandbox is mounting its files in the first seconds of a resume or fork. Retry after 1-3 seconds. |
The response body has the flag in `error.details.retryable`:
```json theme={null}
{
"ok": false,
"type": "sandbox.error",
"status": 502,
"code": "sandbox_direct_failed",
"message": "sandbox_restoring",
"error": {
"code": "sandbox_direct_failed",
"status": 502,
"details": { "retryable": true, "message": "sandbox_restoring" }
}
}
```
## Idempotent sandbox creation
`POST /sandboxes` and `POST /sandboxes/{sandboxId}/fork` each make a new sandbox that bills when it succeeds. A response can get lost, for example a timeout or a `5xx` after Boat accepted the sandbox. Then you do not know if you can retry.
To make create and fork safe to retry, send an `Idempotency-Key` header. Use your own value that is unique in your account, for example a UUID.
1. The first request creates the sandbox and links it to the key.
2. Each retry with the **same account, key, and request body** returns that same sandbox. It does not create a second sandbox that bills.
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff" \
-H "Content-Type: application/json" \
-d '{"from":"web-stack","noEnv":true,"ttlSeconds":1800}'
```
| Situation | Result |
| - | - |
| Retry after a lost `202` or a `5xx` | Same key returns the original sandbox (no second sandbox). |
| Retry while the first sandbox is still being created | `409` `idempotency_in_progress`. Retry shortly with the same key. |
| Same key, different request body | `409` `idempotency_key_reused`. |
| Create that failed before the sandbox existed | Key auto-releases within \~2 minutes so a retry can create the sandbox. |
Boat keeps keys for 24 hours. A key belongs to your account, so two accounts can use the same key value without a conflict. Without the header, create and fork are not idempotent. That is the default. The header is optional on the create and fork calls of each SDK (`Idempotency-Key` / `idempotencyKey`). See [Create sandbox](/api/reference/sandboxes/create-sandbox) and [Fork sandbox](/api/reference/sandboxes/fork-sandbox).
## Sandbox lifecycle
A sandbox goes through these states:
| State | Meaning | Client behavior |
| - | - | - |
| `provisioning`, `provisioned`, `cloning` | The sandbox is being created or prepared. | Poll `GET /sandboxes/{sandboxId}`. |
| `ready`, `idle` | The sandbox can accept prompts and interactive access. | Prompt, open desktop, SSH, or inspect events. |
| `running` | The sandbox is working. | Read events. Interrupt only when the caller wants to stop the current work. |
| `archiving` | Stop/snapshot is in progress. | Poll until `archived` or another terminal state. |
| `archived` | The machine is stopped. A snapshot can be available. | Resume or fork. |
| `error` | Provisioning or runtime failed. | Show the error and let the user stop, delete, resume, or fork when allowed. |
`idle` and `running` show only work queued through `POST /sandboxes/{sandboxId}/prompt`. Processes that you run yourself, over SSH or the command endpoint, do not change the state. A sandbox can show `idle` while your own agent works inside it.
## Providers, models, and reasoning
`POST /sandboxes/{sandboxId}/prompt` runs work through an agent harness (provider):
| Provider | Aliases | Notes |
| - | - | - |
| `codex` | | OpenAI Codex / ChatGPT models |
| `claude-code` | `claude` | Claude Code models |
| `pi` | | Multi-model: Anthropic, OpenAI, and OpenRouter/llmgateway-routed models |
| `opencode` | | Multi-model |
| `prime-agent` | `prime` | Multi-model |
| `kimi` | `kimi-code` | Kimi Code CLI: Kimi models (subscription or Moonshot API key) |
| `mistral` | | Mistral Vibe: Mistral models (Mistral Vibe subscription or Mistral API key) |
Without `provider`, Boat uses the harness that the user selected on the Agents dashboard.
**Models and reasoning efforts depend on the harness and the model, and they change over time.** Get them from the live catalog. Do not hardcode lists.
* `GET /provider-models` returns each model for each provider, and the `reasoningEffort` levels that it accepts: `none`, `low`, `medium`, `high`, `xhigh`, `max`. Some models accept none.
* The `boat prompt --help` CLI command prints the same catalog.
* `pi`, `opencode`, and `prime-agent` also give models routed through OpenRouter and llmgateway (ids like `openrouter:anthropic/claude-sonnet-4.5`).
* Without `model`, Boat uses the default that the user saved on the dashboard for that harness.
To run a prompt in fast mode, set `fast: true`. The model stays the same and gives output faster. The provider bills it at its higher fast rate.
* Without `fast`, Boat uses the choice saved on the Agents dashboard.
* `fast: false` forces standard speed.
* Only models with `"fastMode": true` in `GET /provider-models` accept fast mode. Other models return `400 fast_mode_not_supported`.
Before you send a prompt, set the credentials on the provider setup page of the dashboard. If credentials are missing, the API returns `provider_not_configured` with a setup URL.
A sandbox runs **many conversations in parallel**. `POST /prompt` takes `new` or `conversationId` and returns the `conversationId`. `GET /events` and `POST /interrupt` take a `conversation` filter. See [Integrated agents](/integrated-agents).
## Request examples
These examples are raw HTTP. Each one has a CLI, TypeScript and Python equivalent on its feature page: [Snapshots](/snapshots), [Environments](/environments), [Webhooks](/webhooks), [Data retention](/data-retention), [Desktop](/desktop-streaming), [Hosting](/hosting). The [CLI reference](/cli-reference) maps commands to endpoints.
Set shared variables:
```bash theme={null}
export BOAT_API_BASE="https://boat.dev/api/v1"
export BOAT_API_KEY="sandbox_your_secret_here"
```
Create a one-hour sandbox and store its id:
```bash theme={null}
BOAT_ID=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttlSeconds":3600}' | jq -r '.sandbox.id')
```
Create a sandbox without automatic archival:
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttlSeconds":null}'
```
Poll readiness:
```bash theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
Prompt a sandbox to work in a repo:
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "codex",
"model": "gpt-5.4",
"reasoningEffort": "medium",
"prompt": "Work on the selected repo: run tests, fix failures, commit the result, and report the preview URL if you start a server."
}'
```
Read the work and lifecycle events of the sandbox:
```bash theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/events" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
Get a desktop streaming URL for live inspection:
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/desktop?vnc=1" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
To return a VNC URL that does not require an access token, send:
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/desktop?vnc=1" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"publicAccess":true}'
```
Stop (archive) a sandbox when the workflow is complete:
```bash theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/stop" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
An archive keeps the snapshots for a resume. A permanent delete needs the exact target id in a confirmation header. It returns `202`, and you cannot cancel it:
```bash theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "X-Ascii-Confirm-Delete: $BOAT_ID"
```
Poll `GET /deletion-operations/{operationId}` until `status` is `completed`. See [Data retention and deletion](/data-retention).
## Endpoint reference
| Endpoint | Reference |
| - | - |
| `GET /me` | [Get current Boat user](/api/reference/account/get-current-boat-user) |
| `GET /limits` | [Get Boat limits](/api/reference/account/get-boat-limits) |
| `GET /account/data-retention` | [Get account data-retention policy](/api/reference/account/get-account-data-retention-policy) |
| `PATCH /account/data-retention` | [Update account data-retention policy](/api/reference/account/update-account-data-retention-policy) |
| `GET /deletion-operations/{operationId}` | [Get deletion operation](/api/reference/account/get-deletion-operation) |
| `GET /repos` | [List GitHub repositories available to Boat](/api/reference/account/list-github-repositories-available-to-sandbox) |
| `POST /repos` | [Select repository for sandboxes](/api/reference/account/select-repository-for-sandboxes) |
| `GET /api-keys` | [List API keys](/api/reference/account/list-api-keys) |
| `GET /api-keys/{apiKeyId}/usage` | [Get API key usage](/api/reference/account/get-api-key-usage) |
| `GET /secrets` | [Get Boat secrets setup](/api/reference/account/get-boat-secrets-setup) |
| `POST /secrets` | [Update Boat secrets setup](/api/reference/account/update-boat-secrets-setup) |
| `GET /sandboxes` | [List sandboxes](/api/reference/sandboxes/list-sandboxes) |
| `POST /sandboxes` | [Create sandbox](/api/reference/sandboxes/create-sandbox) |
| `GET /sandboxes/{sandboxId}` | [Get sandbox](/api/reference/sandboxes/get-sandbox) |
| `GET /sandboxes/{sandboxId}/usage` | [Get boat usage](/api/reference/sandboxes/get-sandbox-usage) |
| `PATCH /sandboxes/{sandboxId}` | [Update sandbox](/api/reference/sandboxes/update-sandbox) |
| `DELETE /sandboxes/{sandboxId}` | [Permanently delete sandbox data](/api/reference/sandboxes/permanently-delete-sandbox-data) |
| `POST /sandboxes/{sandboxId}/stop` | [Stop and archive sandbox](/api/reference/sandboxes/stop-and-archive-sandbox) |
| `GET /sandboxes/{sandboxId}/stops/{stopId}` | [Get a stop by id](/api/reference/sandboxes/get-stop) |
| `POST /sandboxes/{sandboxId}/resume` | [Resume sandbox](/api/reference/sandboxes/resume-sandbox) |
| `POST /sandboxes/{sandboxId}/recover` | [Recover sandbox](/api/reference/sandboxes/recover-sandbox) |
| `POST /sandboxes/{sandboxId}/fork` | [Fork sandbox](/api/reference/sandboxes/fork-sandbox) |
| `POST /sandboxes/{sandboxId}/prompt` | [Prompt Sandbox](/api/reference/agent/prompt-sandbox-agent) |
| `GET /sandboxes/{sandboxId}/events` | [List boat events](/api/reference/agent/list-sandbox-events) |
| `GET /sandboxes/{sandboxId}/prompts/{promptId}` | [Get prompt run status](/api/reference/agent/get-prompt-run-status) |
| `GET /sandboxes/{sandboxId}/files` | [Read a file from a sandbox](/api/reference/agent/read-sandbox-file) |
| `PUT /sandboxes/{sandboxId}/files` | [Write a file in a sandbox](/api/reference/agent/write-sandbox-file) |
| `POST /sandboxes/{sandboxId}/files/download-url` | [Get a download URL for a sandbox file](/api/reference/agent/create-download-url) |
| `POST /sandboxes/{sandboxId}/files/upload-url` | [Get an upload URL for a sandbox file](/api/reference/agent/create-upload-url) |
| `POST /sandboxes/{sandboxId}/commands` | [Execute a command in a sandbox](/api/reference/agent/execute-sandbox-command) |
| `GET /sandboxes/{sandboxId}/artifacts` | [Download a sandbox artifact](/api/reference/agent/download-sandbox-artifact) |
| `POST /sandboxes/{sandboxId}/interrupt` | [Interrupt running work](/api/reference/agent/interrupt-running-agent-work) |
| `POST /sandboxes/{sandboxId}/desktop` | [Get desktop streaming URL](/api/reference/agent/get-desktop-streaming-url) |
| `POST /sandboxes/{sandboxId}/sshkey` | [Configure sandbox SSH key](/api/reference/agent/configure-sandbox-ssh-key) |
| `GET /snapshots` | [List snapshots](/api/reference/snapshots/list-snapshots) |
| `GET /sandboxes/{sandboxId}/snapshots` | [List boat snapshots](/api/reference/snapshots/list-sandbox-snapshots) |
| `GET /sandboxes/{sandboxId}/snapshots/latest` | [Get latest boat snapshot](/api/reference/snapshots/get-latest-sandbox-snapshot) |
| `GET /snapshots/{snapshotId}/tree` | [Get snapshot file tree](/api/reference/snapshots/get-snapshot-tree) |
| `GET /snapshots/{snapshotId}/files` | [Download a file or folder from a snapshot](/api/reference/snapshots/get-snapshot-file) |
| `GET /snapshots/{snapshotId}/download` | [Get snapshot download](/api/reference/snapshots/get-snapshot-download) |
| `DELETE /snapshots/{snapshotId}` | [Permanently delete snapshot data](/api/reference/snapshots/permanently-delete-snapshot-data) |
# Billing details
Source: https://docs.boat.dev/billing
Plan time versus credit packs, per-sandbox usage, and what happens when you run out.
The [Pricing](/pricing) page gives prices, sizes and plans. This page tells how billing works under them.
## Plan time vs credit packs
Your balance has two pools. They work differently, and the difference shows only at renewal.
| Pool | When you get it | At the end of the month |
| - | - | - |
| **Plan time** | Fresh at the start of every billing month | It expires. Boat does **not** carry it forward and does not convert it into credits. |
| **Credit packs** (\$20 buys 2,000,000 seconds) | When you buy a pack | It never expires. It carries over to the next month. |
**Boat always spends plan time first.** It uses credits only after the plan time of the month is gone. Credits that Boat uses are gone for good. The next renewal gives back your plan time, but never refills your credits.
Example: a \$20/month subscriber also bought one \$20 pack. They used 2.5M seconds in one month.
| | Plan time | Credits |
| - | - | - |
| Used this month | All 2M seconds | 500,000 seconds |
| Left at the start of next month | 2M fresh seconds | 1.5M seconds |
Check your balance at any time:
```bash CLI theme={null}
boat limits
boat limits --json
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/limits" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const limits = await sandbox.limits();
console.log(limits.canStart, limits.starts?.day?.remaining, limits.creditBalanceHours, limits.packBalanceDollars);
```
```python Python theme={null}
limits = sandbox.limits()
day = getattr(limits.starts, "day", None)
print(limits.can_start, getattr(day, "remaining", None), limits.credit_balance_hours, limits.pack_balance_dollars)
```
For every field, read [Get Boat limits](/api/reference/account/get-boat-limits).
## Per-sandbox usage
Every sandbox meters its own machine time. A platform can give each of its users or agents a sandbox. It can then bill them from the same numbers that drain your balance. Read one sandbox at any time, while it runs or after it stops:
```bash CLI theme={null}
boat usage bx_23456789
boat usage bx_23456789 --since 2026-09-01 --until 2026-10-01
boat usage bx_23456789 --json
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/bx_23456789/usage?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const usage = await sandbox.usage({ sandboxId: "bx_23456789", since: "2026-09-01T00:00:00Z", until: "2026-10-01T00:00:00Z" });
console.log(usage.seconds, usage.dollars, usage.running);
```
```python Python theme={null}
usage = sandbox.usage("bx_23456789", since="2026-09-01T00:00:00Z", until="2026-10-01T00:00:00Z")
print(usage.seconds, usage.dollars, usage.running)
```
| Field | Means |
| - | - |
| `seconds` | Billable machine time, with the multiplier of the sandbox type already applied. A `large` sandbox that ran ten minutes reads 1200. |
| `dollars` | `seconds` at list price (`seconds / secondsPerDollar`). |
| `running` | `true` while the sandbox runs and the number grows. `false` after it stops. Also `false` while a refused stop keeps the meter paused. |
* Boat never counts stopped time.
* Boat does not count time after a [refused stop](/snapshots/stop#when-a-stop-is-refused).
* Omit `since` and `until` to get the full life of the sandbox.
* If a billing period boundary falls inside a running stretch, Boat splits that stretch pro rata.
For every field, read [Get boat usage](/api/reference/sandboxes/get-sandbox-usage).
## AI credentials proxy
The [AI credentials proxy](/ai-credentials#the-ai-credentials-proxy) is paid in Boat time from the same balance, like named snapshots above the first 10:
| Charge | Price | Paid by |
| - | - | - |
| Each UTC day the proxy is on | \$1 | The account with the switch on |
| Proxied requests | \$1 per 1,000 | The wallet each sandbox bills |
`boat ai usage` and `GET /ai-usage` show the requests per sandbox, and `dollars` is their charge.
## Organizations
A team shares one plan and one balance through an organization. Everything else on this page applies to an organization in the same way. [Organizations & teams](/organizations) covers members, the active wallet, shared sandboxes, per-member caps and how to move a personal plan in.
## Running out
When your balance reaches zero:
1. You get a **24 hour grace period**. This is true with or without auto-pay.
2. Your sandboxes keep running. Boat sends you an email alert. You can top up before anything stops.
3. If you do not pay in that window, Boat stops your running sandboxes with a snapshot.
4. Nothing is lost. Resume the sandboxes after you top up.
To never reach that stop, turn on **auto-pay** in the billing dashboard. When you run out, auto-pay charges your saved card in small automatic amounts. It uses any prepaid balance on your account first.
If a monthly renewal payment fails and you still have credits, your sandboxes keep running until the credits run out.
Sandboxes keep running through the grace period. So you can use a little more machine time than you had.
* `creditBalanceSeconds` stops at zero. It reads `0` while you owe this time.
* Boat carries the shortfall and settles it on your next payment.
* You pay for exactly the seconds that you used.
## Related
* [Pricing](/pricing)
* [Organizations & teams](/organizations)
* [Build a Platform on Boat](/platform-guide)
* [FAQ](/faq)
* [Long-Running Tasks](/long-running-tasks)
# CLI Reference
Source: https://docs.boat.dev/cli-reference
Complete reference for all Boat CLI commands and global flags.
## Installation & updates
```bash theme={null}
# Install (run once)
curl -fsSL https://boat.dev/install | sh
# Check for and apply updates
boat self-update
```
The CLI checks for updates each time it runs. To skip this check, pass `--no-update`.
***
## Global flags
These flags work with all commands:
| Flag | Description |
| - | - |
| `--api-url ` | Use a different API endpoint (env: `BOAT_API_URL`) |
| `--org ` | Run this command against an organization wallet (env: `BOAT_ORG`). The scope that you set with `boat org switch` does not change. |
| `--json` | Print JSON for machines instead of text for people |
| `--no-update` | Skip the automatic update check |
When you pipe or redirect the output, `--json` turns on automatically. Scripts get JSONL without the flag.
A command that takes a sandbox ID also accepts two aliases:
| Alias | Sandbox |
| - | - |
| `current` | The last sandbox that you created in this shell |
| `self` | The sandbox that the CLI runs inside, when you use the CLI in a sandbox |
***
## In scripts and CI
In an application, use the [Python or TypeScript SDK](/sdks/overview) or the [HTTP API](/api/v1) with a `BOAT_API_KEY`. You do not install a binary, and the responses have types. Use the CLI in shell scripts and CI jobs.
Sign in without the key in the process arguments. Then read JSON from stdout:
```bash theme={null}
boat login --key-stdin --json <<< "$BOAT_API_KEY"
sandbox_id="$(boat new --json | jq -r 'select(.event == "ready") | .id')"
boat exec "$sandbox_id" "npm test"
boat stop "$sandbox_id" --json
```
Most commands print one JSON object. These commands print JSON Lines, one object per line:
* `boat new`
* `boat prompt`
* `boat events`, with or without `--follow`
* `boat conversations`
Parse JSON Lines one line at a time.
When a command fails in `--json` mode, it prints a last line and exits with a non-zero code:
```text theme={null}
{"event":"error","error":"...","code":"...","status":...}
```
The line has `code` and `status` when the Boat API refused the request. Errors in the arguments go to stderr, and they are possibly not JSON.
To use the CLI in a Docker image, do these steps:
1. Download the static binary for the architecture of the image.
2. Sign in when the container starts.
```dockerfile theme={null}
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl openssh-client \
&& rm -rf /var/lib/apt/lists/*
RUN set -eu; \
case "$(uname -m)" in \
x86_64|amd64) arch=x64 ;; \
arm64|aarch64) arch=arm64 ;; \
*) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;; \
esac; \
curl -fsSL "https://boat.dev/api/boat/cli/download?platform=linux-${arch}&channel=prod" -o /usr/local/bin/boat; \
chmod +x /usr/local/bin/boat
```
```sh theme={null}
#!/bin/sh
# entrypoint
set -eu
printf '%s' "$BOAT_API_KEY" | boat login --key-stdin --json
exec node server.js
```
***
## Shell completion
`boat completions ` prints a completion script for bash, zsh, fish, or PowerShell. The script completes these values:
* Subcommands.
* The IDs of your live sandboxes, and `current` and `self`.
The script keeps the results for 15 seconds, so the next tabs are instant.
```bash theme={null}
# bash: add to ~/.bashrc
eval "$(boat completions bash)"
# zsh: add to ~/.zshrc, after compinit
eval "$(boat completions zsh)"
# fish
boat completions fish > ~/.config/fish/completions/sandbox.fish
# PowerShell: add to $PROFILE
boat completions powershell | Out-String | Invoke-Expression
```
***
## Authentication
### `boat onboard`
Set up this computer. The command does these steps:
1. It signs you in through the browser.
2. It saves your token.
3. It asks only for what your account still needs: the third-party safety answer and the plan checkout.
```bash theme={null}
boat onboard
boat onboard --google
boat onboard --email you@example.com
```
It asks which sign-in method to use: GitHub, Google, or a 6-digit code that it sends to your email. `--google` and `--email` give that answer in advance. See [Quickstart](/account#sign-in-methods).
You can run it again safely. On a new install or a second computer, it finds the account that you already have. It skips each step that this account has done:
| Your account already has | What `boat onboard` does |
| - | - |
| An active plan | Prints your plan and usage. **No Stripe Checkout**, no second subscription. |
| A plan with depleted usage | Points you at the billing dashboard to top up or change tier, instead of starting another plan. |
| Answered what your sandboxes are for | Does not ask that question again, whichever way you answered. |
| A past subscription | Offers checkout without promising a 7-day trial, which Stripe grants once per customer. |
Boat records your answer on the environment when you give it. Boat keeps both answers, not only "a platform of mine". A plan never counts as an answer, because the dashboard checkout does not ask the question.
See [Reinstalling, or a second machine](/account#reinstalling-or-a-second-machine).
### `boat login [key]`
Sign in with an API token that you already have. Without a key, the command starts a sign-in in the browser. GitHub is the default. Google and email also work.
```bash theme={null}
boat login
boat login --google
boat login --email you@example.com
boat login --key-stdin <<< "$BOAT_API_KEY"
boat login boat_abc123...
```
`--key-stdin` reads the token from standard input, not from the command line. Other users on the host can read the process arguments, so the token stays out of them. Use `--key-stdin` when you sign in without a person present. You can also give the token as an argument. You cannot use both. `--key-stdin` needs a Boat CLI newer than 0.1.211.
Without a key, the CLI prints a URL and opens it. Then it waits up to six minutes for you to finish in the browser. `--email` sends a code to that address. If you omit the address, the browser page asks for it. Boat refuses disposable email domains.
All methods sign in to the same account only if they are already **connected** to it. A method that you never used before starts a new account, even when the email is the same. Add connections in [Dashboard > Account](https://boat.dev/dashboard?tab=account) instead. See [Quickstart](/account#sign-in-methods).
To create production API keys, run `boat api-key create` or use the API Keys page of the dashboard. For key management, see [API Keys](/api-keys). For Docker and CI setup, see [In scripts and CI](#in-scripts-and-ci).
### `boat api-key`
Create and manage API keys for SDKs, CI, and other projects.
```bash theme={null}
boat api-key create my-project --ttl 90d --preset ci
boat api-key create my-project --ttl 7d --sandbox bx_123 --actions sandbox.read,exec
boat api-key list # scope, expiry, last used
boat api-key list --all # also platform-managed per-sandbox machine keys
boat api-key usage # 30-day requests and live resource count
boat api-key usage --verbose # plus sandboxes/Agents split and created list
boat api-key rotate # old secret stops working, new one shown once
boat api-key revoke
```
| Flag | Rule |
| - | - |
| `--ttl` | Default 90d. Maximum 365d. |
| `--sandbox`, `--env` | You can repeat them. |
| `--preset` | `read-only`, `full-sandbox`, `ci`, or `admin`. |
| `--actions` | You cannot use it with `--preset`. |
`create` and `rotate` show the secret one time. You cannot get it again later. `list` shows the prefix, the last four characters, the scope, the expiry, the 30-day request total, and the live resource count. `usage` still works after you revoke a key. Revoke does not delete sandboxes or Agents.
`create` calls the `POST /api/v1/api-keys/scoped` endpoint. It needs a browser session or a token with admin scope. During a rollout, `create` can be unavailable for a short time. `api-key list` stays available. `rotate` and `revoke` still need a browser session. See [API Keys](/api-keys).
### `boat webhook`
Register lifecycle webhooks for all sandboxes of your account.
```bash theme={null}
boat webhook create https://example.com/hooks/boat --event ready --event error
boat webhook list
boat webhook rotate
boat webhook remove
```
The events are `sandbox.ready`, `sandbox.error`, `sandbox.archived`, `sandbox.hydrated`, `sandbox.degraded`, and `sandbox.recovered`. To subscribe to all of them, omit `--event`. You see the signing secret only when you create or rotate the webhook. See [Webhooks](/webhooks).
### `boat telemetry`
Send sandbox and account metrics, and lifecycle events, to an OTLP/HTTP endpoint.
```bash theme={null}
boat telemetry # show the export and its last result
boat telemetry set https://otlp.datadoghq.com -H dd-api-key=$DD_API_KEY
boat telemetry unset
```
`set` replaces the current export and sends a test export immediately. For more headers, repeat `-H key=value`. Boat encrypts the header values and never shows them. See [OpenTelemetry](/opentelemetry).
### `boat logout`
Sign out and clear the local token.
```bash theme={null}
boat logout
```
### `boat status`
Show the API health, the account that is signed in, its plan, and the path of the local configuration.
```bash theme={null}
boat status
```
***
## Sandbox lifecycle
### `boat new`
Create a new sandbox.
```bash theme={null}
boat new [--ttl SECONDS]
boat new --type small
boat new --type large
boat new --no-auto-stop
boat new --env KEY=VALUE --env OTHER=VALUE
boat new --no-env
boat new --no-snapshots
boat new --no-monitoring
boat new --fail-fast
boat new --setup-file ./setup.sh
boat new --environment users
boat new --from web-stack
boat --org acme new
boat org switch acme
boat new
boat new --personal
```
| Flag | Default | Maximum |
| - | - | - |
| `--type` | `default` | `small` or `large` |
| `--ttl` | `3600` (1 hour) | `2592000` (30 days) |
| `--no-auto-stop` | off | no automatic stop |
| `--env`, `-e` | none | 100 variables, 64KB total |
| `--environment` | your default (`base`) | one named environment |
| `--no-env` | off | none |
| `--no-snapshots` | off | none |
| `--no-monitoring` | off | none |
| `--fail-fast` | off | none |
| `--setup-file` | none | 64KB script file |
| `--from` | none | one named snapshot or share code |
| `--personal` | off | bills you, not the active org |
`--type` sets the machine size. A fork gets the size of its source sandbox, unless you pass `--type`. `boat resume --type` moves a sandbox to a different size. For the specifications and the hourly price of each size, see [Pricing](/pricing).
On the free trial, `--no-auto-stop` and a `--ttl` above 2 hours are refused, and `--type large` is not available. See [Pricing](/pricing#concurrency).
`--env` sets environment variables on this sandbox only, on top of your dashboard secrets. When two variables have the same name, the value for this sandbox wins. See [Environments](/environments).
`--environment ` sets the environment that the sandbox starts from: its repositories, secrets, and credentials. If you omit it, the sandbox uses your default. Boat refuses an unknown name before it creates the sandbox, so a typo costs you nothing. `--environment` and `--env` are not related. The first selects a template. The second sets a variable on this one sandbox. See [Environments](/environments).
`--no-env` creates a sandbox that gets none of the secrets of your account. The sandbox also cannot act on your account or on other sandboxes. Use it for sandboxes that you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work. See [Environments](/environments). If you make many such sandboxes, use an environment marked safe for third parties instead. It applies the same protection to each sandbox that uses it, and the protection stays after forks and resumes.
`--no-snapshots` creates a sandbox that Boat never snapshots. When you stop it, Boat erases it. See [Snapshots off](/data-retention/snapshots-and-monitoring-off#snapshots-off).
`--no-monitoring` creates a sandbox for which Boat keeps none of these: command output, process output, the process list, CPU and RAM samples. You still see the live output of a running command. See [Monitoring off](/data-retention/snapshots-and-monitoring-off#monitoring-off).
`--fail-fast` creates the sandbox only if a machine of its type is ready now. It answers in about 1.5 seconds. If no machine is ready, it fails with `no_ready_machine`. Boat then creates nothing, bills nothing, and counts nothing against your start limits. It works with `--from`. `boat fork` and `boat resume` also accept it. See [Fail fast](/machines/fail-fast).
`--setup-file` reads a local shell script (UTF-8, up to 64KB). Boat runs the script on the sandbox in the background after the sandbox is ready. The script never delays `ready`. To see the result, read `setupStatus` (`pending`, `running`, `done`, `failed`) and `setupError` in `boat info`. You can use it with `--from`.
`--personal` bills you, also when an org wallet is active. For daily use, run `boat org switch` one time. All later `boat new` commands use that wallet. To change the wallet for one create, run `boat --org new` or `boat --org personal new`. See [`boat org`](#boat-org).
`--from ` starts the sandbox from a named snapshot that you saved with `boat snapshot `. The stack is then already installed. The sandbox does not get the environment of the source sandbox. Pass `--environment`, or the sandbox uses your default. This flag is not related to `boat env set-file --from`, which reads a local file. See [Snapshots & Copies](/snapshots).
`--from bsh_...` uses a share code that another account gave you. The new sandbox is yours and bills your account. It does not get the per-sandbox variables of the owner. See [Share a snapshot with another account](/snapshots/templates#share-a-template-with-another-account).
The command returns the sandbox ID, the IP, and the first state.
For a long workflow without interruptions, disable auto-stop:
```bash theme={null}
boat new --no-auto-stop
```
See [Long-Running Tasks](/long-running-tasks).
### `boat list`
List your sandboxes that are up or running, with their current state and ID. `boat list` without flags is the same as `boat list --filter r`.
```bash theme={null}
boat list
boat list --filter s
boat list --filter sr
boat list --all
```
Give `--filter` one or more state group letters:
| Filter | Includes |
| - | - |
| `r` | Up/running sandboxes: `ready`, `cloning`, `idle`, `running` |
| `s` | Stopped sandboxes: `stopped` |
| `p` | Pending sandboxes: `init`, `provisioning` |
| `t` | Stopping sandboxes: `stopping` |
| `e` | Error sandboxes: `error` |
You can combine letters. For example, `boat list --filter sr` lists stopped sandboxes and sandboxes that are up or running. To include all states, use `--all`.
### `boat extend `
Change the auto-stop timer of a sandbox.
```bash theme={null}
boat extend bx_f7k2q9hd --hours 12
boat extend bx_f7k2q9hd --ttl 2592000
boat extend bx_f7k2q9hd --no-auto-stop
```
To extend by a fixed time, use `--hours` or `--ttl`. To keep the sandbox running until you stop it, use `--no-auto-stop`.
### `boat info `
Show the details of one sandbox: state, IP, desktop availability, and remaining TTL.
```bash theme={null}
boat info bx_f7k2q9hd
```
### `boat stop `
Pause a running sandbox. Boat makes a snapshot, then stops billing. The sandbox goes to `archiving`, then to `archived`.
```bash theme={null}
boat stop bx_f7k2q9hd
```
The snapshot takes a moment. When the command returns, the sandbox is not stopped yet. Poll `boat info` until the state is `archived`.
The stop prints its id (`operation.id`, for example `stop_3f9a1c2e7b4d5a60`). To read that stop later, pass the id to `--status`. The status is `pending`, `failing`, `completed` or `superseded`. `superseded` means that a resume ended the stop. You can still read old stops after a resume or a later stop.
```bash theme={null}
boat stop bx_f7k2q9hd --status stop_3f9a1c2e7b4d5a60
```
**If Boat refuses a stop.** A stop saves the disk first. If that save fails, Boat does these things:
1. It refuses the stop and keeps the sandbox running, so your work is not lost.
2. It tries the save again automatically.
3. It sends you an email.
**Boat does not bill you for the time that your sandbox spends in that state.** The meter pauses automatically from the first failed attempt. See [When a stop is refused](/snapshots/stop#when-a-stop-is-refused).
A refused stop stays pending until a save succeeds. Then the sandbox stops automatically.
`--force` stops the sandbox now and keeps its last successful snapshot. All data written after that snapshot is lost permanently. Use it only after a stop failed.
```bash theme={null}
boat stop bx_f7k2q9hd --force
```
`--force` discards unsaved work. First, read the time of the last snapshot in `boat info`. Then you know exactly what you lose.
### `boat delete `
Permanently delete a sandbox **and its snapshots**. Boat force-stops the sandbox without a last snapshot. Then Boat deletes from storage each snapshot chain that only this sandbox owns.
```bash theme={null}
boat delete bx_f7k2q9hd
boat delete bx_f7k2q9hd --yes
boat delete self --yes # from inside a sandbox
```
`boat delete` destroys data. You cannot resume, fork or recover a deleted sandbox. No list of deleted sandboxes exists to restore from.
**If you want to use the data later, run `boat stop` instead.** A stopped sandbox is free and keeps its disk. `boat resume` brings it back in the same condition.
The command asks you to confirm. To skip the question, pass `--yes`. In scripts (`--json`, or no terminal attached), `--yes` is necessary. Without it, the command refuses and does not wait.
Deletion is not instant. Boat must remove the machine before it can remove the data. The command does these steps:
1. It removes the sandbox from `boat list` immediately.
2. It prints the deletion operation id (`bdop_…`).
3. It follows that operation until it finishes.
**What Boat keeps.** Boat keeps snapshot data that something else also uses. If Boat deleted it, the other user of the data would break:
* A sandbox that you **forked** from this one, or a **resume** of it, restores from the same physical snapshot objects.
* A **named snapshot** saved from this sandbox (`boat snapshot `) keeps its data. To remove those bytes too, run `boat snapshot rm `.
Boat releases the storage when the last sandbox or named snapshot that uses a chain is gone.
### `boat deletion status `
Read the status of a deletion that you started earlier, here or through the API. The status is `pending`, `processing`, `blocked` or `completed`. `blocked` is not a final state. It means that an attempt found something that it cannot finish yet. Usually, another sandbox still reads a snapshot. Boat tries again automatically, with backoff.
```bash theme={null}
boat deletion status bdop_0123456789abcdef0123456789abcdef
```
See [Data retention and deletion](/data-retention).
### `boat resume `
Resume a stopped sandbox from its last snapshot. Before the CLI prints its last `ready` event, it waits for two things:
1. A ready state.
2. A test command that does nothing and succeeds.
This shows that the sandbox can run commands. The CLI does not wait for background hydration or setup scripts. The wait stops after 30 minutes. It fails on a final sandbox state or on an API error that cannot be retried. Older Box and Boat binaries need an updated CLI to get this check. See [Snapshots](/snapshots).
```bash theme={null}
boat resume bx_f7k2q9hd
boat resume --no-env bx_f7k2q9hd
boat resume --type large bx_f7k2q9hd
boat resume -e KEY=VALUE bx_f7k2q9hd
boat resume --ttl 7200 bx_f7k2q9hd
boat resume --no-auto-stop bx_f7k2q9hd
```
The sandbox must have a completed snapshot. This means that you stopped it correctly with `boat stop`.
| Flag | What it does |
| - | - |
| `-e`, `--env` | Sets per-sandbox environment variables. It works the same as `boat new -e`. Repeat it for more values. A per-sandbox value replaces a dashboard variable with the same name. The set you pass **replaces** the current per-sandbox variables of the sandbox. |
| `--environment ` | Moves the sandbox to a different environment when it resumes. |
| `--no-env` | Removes your account secrets, and removes owner secrets that came from the snapshot. You cannot undo this. The sandbox stays no-env. |
| `--type` | Resumes on a different machine size: `small`, `default`, or `large`. |
| `--ttl ` | Sets the lifetime of the resumed sandbox. |
| `--no-auto-stop` | Turns auto-stop off. |
Without `--environment`, the sandbox keeps the environment version that it had. A resume never moves a sandbox to a newer version without your command. Boat refuses an unknown name before it changes anything. The new environment can withhold a secret that the sandbox has now. Boat then removes that secret from the disk during the resume, and it does not come back. See [Environments](/environments).
Without `--type`, the sandbox keeps its current size. Boat refuses to shrink a sandbox that has more data than the smaller machine can hold. The sandbox then stays as it was. See [Machine Capabilities](/machines).
Without `--ttl` and `--no-auto-stop`, the sandbox keeps its current setting. A resume never makes the lifetime shorter or longer without your command.
A resume is like a server reboot. The systemd services that you enabled start again automatically. Processes that you started by hand do not come back: dev servers, background jobs, tunnels, desktop sessions. Start them again, or make them systemd services.
### `boat recover `
Power-cycle the machine of a sandbox that does not respond. Boat does not touch the disk. Usually the sandbox answers again in 1-2 minutes.
Boat refuses a recover in these cases. Resume the sandbox instead.
* The sandbox answers normally.
* A recover started less than 10 minutes ago.
* Boat cannot power-cycle its machine.
This command does the same as `POST /sandboxes/{id}/recover` and Recover in the dashboard.
```bash theme={null}
boat recover bx_f7k2q9hd
```
### `boat fork `
Copy a sandbox from its latest snapshot into a new, independent sandbox.
```bash theme={null}
boat fork bx_f7k2q9hd
boat fork --no-env bx_f7k2q9hd
boat fork --type small bx_f7k2q9hd
boat fork -e TENANT_ID=acme bx_f7k2q9hd
boat fork --ttl 600 bx_f7k2q9hd
boat fork --no-auto-stop bx_f7k2q9hd
```
The command returns the new sandbox ID asynchronously (HTTP 202). The source sandbox must have a completed snapshot.
A fork copies the filesystem of the snapshot into a new sandbox. The systemd services that you enabled start automatically, as on a resume. Processes that the source sandbox started by hand are not in the fork. Start them again in the fork if necessary.
Boat never changes the source sandbox.
| Flag | What it does |
| - | - |
| `--type` | Gives the fork a machine size that is different from its source. |
| `--ttl `, `--no-auto-stop` | Set the lifetime of the fork. |
| `--environment ` | Puts the fork on a different environment. |
| `--no-env` | Makes the fork a no-env sandbox. |
| `-e`, `--env` | Sets per-sandbox environment variables on the fork. It works the same as `boat new -e`. |
A fork does **not** get the lifetime of its source. The default is 1 hour. So a fork of a sandbox with auto-stop off does not make another sandbox that nothing stops.
Without `--environment`, the fork gets exactly the environment version of its source. A fork never gets configuration that its source did not have. See [Environments](/environments).
A fork of a no-env source is always no-env.
The variables that you pass with `--env` **replace** the per-sandbox variables that the fork gets from the source sandbox. Without `--env`, the fork gets them unchanged.
### `boat events `
Read the work of the agent on a sandbox: prompts and responses. By default, the command streams **all conversations** on the sandbox. Each event has a `conversationId`, which you see with `--json`. To keep polling for new events, add `--follow`. To watch one conversation, add `--convo`.
These events are the conversations of the agent, not the lifecycle of the sandbox. A sandbox that never got a prompt returns an empty list, also after it started, stopped and resumed. For the lifecycle state, use `boat info`.
```bash theme={null}
boat events bx_f7k2q9hd
boat events bx_f7k2q9hd --follow
boat events bx_f7k2q9hd --convo # just one conversation
boat events bx_f7k2q9hd --convo current # this shell's current conversation
```
| Flag | Description |
| - | - |
| `--follow` | Continue polling and printing new events until interrupted |
| `--convo ` | Only stream this conversation (or `current`). Repeat for several. Omit to stream all conversations. Alias `--conversation` |
### `boat conversations [id]`
List the conversations of a sandbox. The conversation with the most recent prompt comes first. Each row shows these values:
* The id.
* The last activity.
* The number of prompts.
* If a turn is running.
* The last harness and model.
* A preview of the last prompt.
Alias: `sandbox convos`.
```bash theme={null}
boat conversations
sandbox convos bx_f7k2q9hd
boat conversations bx_f7k2q9hd --json # one JSON line per conversation
```
```
ID When Prompts Running Harness/model Last prompt
8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c just now 1 yes pi/claude-sonnet-5 Investigate the flaky CI job [sandbox current, this shell]
2c0d9e4b-7a1f-4c3e-8b5d-6e7f8a9b0c1d 4 mins ago 2 no claude Now add tests
```
Two markers can come after the last prompt:
| Marker | Conversation |
| - | - |
| `sandbox current` | The one that `boat prompt` without flags continues from any shell. This is the conversation of the sandbox with the most recent prompt. |
| `this shell` | The one that `boat prompt` without flags continues from this shell. |
Copy an id into one of these commands:
* `boat prompt --resume `
* `boat steer --convo `
* `boat events --convo `
* `boat interrupt --convo `
### `boat steer `
Send a message to a turn that is **already running**, and do not stop it. The agent uses the message and continues its work. There are three options:
| Command | What happens to the running turn |
| - | - |
| `boat prompt` | Waits for the turn to end. |
| `boat steer` | Adds your message to the turn. |
| `boat interrupt` | Discards the turn. |
```bash theme={null}
boat steer "Skip the integration tests, the unit tests are enough"
boat steer bx_f7k2q9hd "Also update the changelog when you are done"
boat steer bx_f7k2q9hd --convo "Focus on the auth module first"
boat steer --convo current "Stop after the first failure"
```
Without `--convo`, the command steers the conversation that this shell prompted last. This is the same conversation that `boat prompt` without flags continues. If the conversation has no running turn, Boat refuses the steer with `no_running_turn`. Use `boat prompt` in that case.
How each harness handles a steer:
| Harness | What happens |
| - | - |
| Claude Code, Codex, pi, Prime Agent | The harness adds the message to the running turn natively. Nothing is interrupted. If the harness accepts the message but the turn ends before it uses the message, Boat immediately continues with a new turn on the same session. So the agent always acts on a steer. |
| OpenCode | OpenCode cannot take a message during a turn. Boat stops that turn and immediately continues the same conversation with your instruction. The conversation keeps all of its memory. |
The `native` field of the JSON output tells which path ran. The steer shows in `boat events` as a `steer` event with the final `mode`: `native`, `native-continued`, `fallback` or `late`. See [Integrated agents](/integrated-agents).
| Flag | Description |
| - | - |
| `--convo ` | Steer this conversation (or `current`). Omit to steer the one this shell last prompted. Alias `--conversation` |
### `boat interrupt `
Interrupt the running agent work in a sandbox. By default, the command stops **all conversations** on the sandbox. To stop only one, use `--convo`. The other conversations keep running.
```bash theme={null}
boat interrupt bx_f7k2q9hd
boat interrupt bx_f7k2q9hd --convo # stop just one conversation
boat interrupt bx_f7k2q9hd --convo current
```
| Flag | Description |
| - | - |
| `--convo ` | Interrupt only this conversation (or `current`). Omit to interrupt the whole sandbox. Alias `--conversation` |
***
## Access
### `boat ssh [command]`
Open an SSH session in a sandbox, or run one command without a session. The CLI manages the key at `~/.ssh/ascii_box_ed25519` automatically. The box CLI used the same key file, so you do not authorize it again.
```bash theme={null}
boat ssh bx_f7k2q9hd
boat ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
boat ssh bx_f7k2q9hd -- bash -lc "cd /home/user/my-repo && npm test"
boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```
### `boat exec [command...]`
Run a command in a sandbox through the Boat API. You do not need an SSH session or a key. `boat exec` exits with the exit code of the remote command, so you can use it directly in scripts and CI.
```bash theme={null}
boat exec bx_f7k2q9hd "npm test"
boat exec bx_f7k2q9hd --cwd my-repo --timeout 120 -- npm run build
boat exec bx_f7k2q9hd bash -lc 'echo "$HOME" && ls'
```
One argument runs as a shell command line. More than one argument runs as argv. Each argument keeps its quoting, as with `boat ssh`.
| Flag | Default | Description |
| - | - | - |
| `--cwd ` | sandbox work directory | Working directory, relative to the sandbox work directory (`/home/user`) |
| `--timeout ` | `30` | Synchronous timeout, 1–600 seconds |
| `--detach` | off | Run in the background and print the process id |
| `--status ` | none | Show status and logs of a process started with `--detach` |
| `--kill ` | none | Stop a process started with `--detach`, and every process it started |
| `--attach ` | none | Print the output of a process started with `--detach` as it writes it, from its start, until it ends. Exits with its exit code. Reconnects every 10 minutes with no gap |
Wait until the sandbox is `ready` before you run `boat exec`. Boat refuses earlier calls with a `boat_starting` error that you can retry.
The synchronous limit is 600 seconds. For a command that can run longer, detach it and poll:
```bash theme={null}
pid="$(boat exec bx_f7k2q9hd --detach "npm run build" | jq -r .processId)"
boat exec bx_f7k2q9hd --status "$pid"
boat exec bx_f7k2q9hd --attach "$pid" # follow the output live until it ends
```
`--detach` starts the command in the background and returns a JSON object. Take `processId` from it, as in the example. When you pipe or capture the output, `--json` turns on automatically. So in a script you always get JSON here, also without the flag.
The output goes to `~/.ascii/processes/.log` on the sandbox. `--status ` prints these values:
* If the process still runs.
* The exit code, after the process ends.
* The last lines of stdout and stderr.
If the agent of the sandbox restarts (stop and resume), the status changes to `lost`. The log files stay on the disk. See [Long-Running Tasks](/long-running-tasks).
### `boat history [command-id]`
List the commands that ran in a sandbox, newest first. With a command id, print the stored output of that command. This works while the sandbox is stopped.
| What | Boat keeps it for |
| - | - |
| Commands run through `boat exec` or the API | 90 days |
| The output of all other processes in the sandbox | 72 hours |
```bash theme={null}
boat history bx_f7k2q9hd
boat history bx_f7k2q9hd --mode commands
boat history bx_f7k2q9hd cmd_k3v9x2mq7tbw --stderr
boat history bx_f7k2q9hd cmd_k3v9x2mq7tbw --follow
```
| Flag | Default | Description |
| - | - | - |
| `--limit ` | `20` | How many commands to list, at most 100 |
| `--mode ` | all | Only these, comma-separated: `commands` (what you ran), `process` (every other process), or `sync`, `stream`, `detached` |
| `--stderr` | off | Print stderr instead of stdout |
| `-f`, `--follow` | off | Keep printing new output until the command ends |
See [Command History](/long-running-tasks/command-history).
### `boat ps `
List the processes in a sandbox, busiest first: pid, CPU, memory, user, history record and command line. To read the output of a process, pass its HISTORY id to `boat history`. For a stopped sandbox, the command shows the last sample that Boat kept, with its time.
### `boat env`
Manage the templates that new sandboxes start from: repositories, secrets, and the credentials that a sandbox can use. Each change makes a new version that you cannot change. Running sandboxes stay on their start version until you run `boat env upgrade`. See [Environments](/environments).
`--environment` and `--env` are different. `boat new --environment staging` sets the environment that the sandbox uses. `boat new --env KEY=value` sets one variable on that one sandbox, on top of what the environment gives it.
```bash theme={null}
boat env list
boat env info base
boat env new staging
boat env rename staging prod
boat env default prod
boat env rm staging
```
| Command | Description |
| - | - |
| `boat env list` | Your environments, with the default marker, latest version, and live sandboxes per version |
| `boat env info ` | One environment in full: toggles, variables, secret files, repos, versions |
| `boat env new ` | Create an environment. Starts with everything injected |
| `boat env rename ` | Rename. Sandboxes stay pinned to their versions |
| `boat env default ` | Make it the environment new sandboxes use when none is named |
| `boat env rm ` | Soft delete. Pinned sandboxes keep running. New sandboxes cannot use it |
#### `boat env set `
Change what the environment injects.
```bash theme={null}
boat env set base --safe-for-third-parties true
boat env set base --github true --secrets false
```
| Flag | Description |
| - | - |
| `--safe-for-third-parties ` | Master switch. `true` injects nothing of yours and overrides every flag below |
| `--github ` | Your GitHub access: token and repository clones |
| `--secrets ` | Your environment variables and secret files |
| `--sandbox-credentials ` | The in-sandbox Boat CLI credentials, so the sandbox can manage its own lifecycle |
| `--agents-credentials ` | Your agent provider logins (Claude, Codex, and so on) |
| `--credential-profile ` | The [credential profile](/ai-credentials#credential-profiles) the sandboxes get. `default` = the sandbox owner's default profile |
| `--proxy-ai-credentials ` | With `--safe-for-third-parties true`: still pass AI credentials, as proxy placeholders. Needs `boat ai proxy on` for the profile owner |
#### Organization environments
Add `--org ` to any `boat env` command to work on the organization's shared environments. Members read and use them. Owners and admins change them. Without `--org`, `boat env` works on your own environments. See [Environments](/environments/named-environments#organization-environments).
```bash theme={null}
boat env list --org acme
boat env set agents --org acme --credential-profile team-claude
```
#### Contents
```bash theme={null}
boat env set-var base STRIPE_KEY=sk_live_123
boat env rm-var base STRIPE_KEY
boat env set-file base backend/.env --from ./local.env
cat ./local.env | boat env set-file base backend/.env
boat env rm-file base backend/.env
boat env add-repo base octocat/hello-world --branch develop
boat env rm-repo base octocat/hello-world
```
`set-file` reads the contents from `--from `. Without `--from`, it reads from stdin. Paths are relative to the sandbox work directory (`/home/user`).
#### `boat env upgrade `
Move the sandboxes of this environment to its latest version.
* Live sandboxes get the new configuration immediately. First, Boat removes from the machine each secret that the new version withholds.
* Stopped sandboxes get it when they resume.
* Nothing upgrades without this command.
```bash theme={null}
boat env upgrade base
```
Boat deletes a withheld secret from the disk of the sandbox. It does not hide it. If you pin the sandbox to the older version again, the secret does not come back.
### `boat host `
Expose a service that runs in a sandbox on a stable HTTPS URL. You do not open an SSH session.
```bash theme={null}
boat host bx_f7k2q9hd 3000
boat host bx_f7k2q9hd 3000 --title "Login preview"
boat host bx_f7k2q9hd 3000 --public
boat host bx_f7k2q9hd 5173 --localhost
boat host bx_f7k2q9hd 3000 --json
```
The command opens the sandbox firewall, registers the HTTPS subdomain, and prints the URL. If you run it again for the same sandbox and port, you get the same URL.
| Flag | Default | Description |
| - | - | - |
| `--title ` | none | Set the display title for the hosted port. |
| `--private` | on | Require the generated `_token` query parameter to access the URL. |
| `--public` | off | Clear any saved access token and return a URL that does not require `_token`. |
| `--localhost` | off | The service listens on `localhost`, `127.0.0.1` or `::1` only. The sandbox relays the URL to it. Leave it off for a service on `0.0.0.0`. See [Services that listen on localhost](/hosting/how-it-works#services-that-listen-on-localhost). |
### `boat scp`
Copy files to or from a sandbox. Use `bx_<id>:/path` as the remote address.
```bash theme={null}
# Download a file
boat scp bx_f7k2q9hd:/home/user/output.zip ./output.zip
# Upload a file
boat scp ./local-file.txt bx_f7k2q9hd:/home/user/
# Copy a directory recursively
boat scp --recursive ./my-project bx_f7k2q9hd:/home/user/
```
| Flag | Description |
| - | - |
| `--recursive` | Copy directories recursively |
On macOS and Linux, a recursive copy to a new directory can send one archive over SSH. This needs `tar` on both ends. It removes one network round trip for each file. You see the new directory only after the full transfer. These copies use the installed OpenSSH `scp`:
* Single files.
* Merges into a directory that exists.
* Trees that the archive mode does not support.
### `boat forward <id>`
Forward one TCP port from a sandbox to your computer.
```bash theme={null}
boat forward bx_f7k2q9hd --remote 8080
boat forward bx_f7k2q9hd --remote 3000 --bind 0.0.0.0
```
| Flag | Default | Description |
| - | - | - |
| `--remote <port>` | required | Remote port on the sandbox |
| `--local <port>` | same as remote | Local port to bind |
| `--bind <addr>` | `127.0.0.1` | Local bind address |
#### `--reverse`: reach your machine from the sandbox
`--reverse` sends the tunnel in the other direction. A port on your computer
becomes available inside the sandbox at `127.0.0.1:<remote>`. An agent in the
sandbox can then call an MCP server, a local model, or a webhook receiver that
stays on your laptop.
```bash theme={null}
# your app on localhost:7777 answers at 127.0.0.1:7777 inside the sandbox
boat forward bx_f7k2q9hd --reverse --local 7777
# a local model on 11434 shows up inside the sandbox on 11500
boat forward bx_f7k2q9hd --reverse --local 11434 --remote 11500
```
| Flag | Default | Description |
| - | - | - |
| `--local <port>` | required | Port on your computer to expose |
| `--remote <port>` | same as local | Port the sandbox listens on |
| `--bind <addr>` | `127.0.0.1` | Bind address **inside the sandbox**. Anything other than loopback needs `GatewayPorts` enabled on the sandbox's sshd |
Both directions run in the foreground until you press Ctrl+C. The tunnel can
stop because the sandbox moved. For example, `boat stop` then `boat resume`
brings the sandbox back on a new IP. The CLI then gets the connection again and
tries up to five times before it stops. A failure at startup, for example a
port that is already in use on the other side, shows immediately. The CLI does
not try again.
Neither direction makes anything public. The tunnel uses the same SSH session
as `boat ssh`, and the sandbox side listens on loopback only. For a public HTTPS
URL for a port inside the sandbox, use [`boat host`](#boat-host-id-port).
### `boat desktop <id>`
Open the desktop streaming URL of the sandbox in your browser.
```bash theme={null}
boat desktop bx_f7k2q9hd
boat desktop bx_f7k2q9hd --vnc
boat desktop bx_f7k2q9hd --vnc --public
```
By default, the desktop streams over Moonlight (60fps WebRTC). Some networks
block traffic or have low bandwidth. There, WebRTC can be unstable or not
connect. Use `--vnc` in that case. The VNC stream goes over plain HTTPS and
works much better on poor connections. If the default stream has problems, the
viewer also has a one-click switch to VNC.
| Flag | Default | Description |
| - | - | - |
| `--vnc` | off | Stream over VNC instead of Moonlight. More stable on poor networks. |
| `--public` | off | With `--vnc`, return a URL that does not require an access token. |
<Note>
The first `--vnc` on a sandbox takes a few seconds, because the sandbox
prepares the VNC stack. The CLI shows a spinner. The next opens are instant.
</Note>
### `boat browser <id>`
Get a stream that shows only the browser of the running sandbox.
```bash theme={null}
boat browser bx_f7k2q9hd
boat browser bx_f7k2q9hd --profile /data/chrome-profile
```
| Flag | Default | Description |
| - | - | - |
| `--profile <path>` | a managed dir on the sandbox | Absolute path on the sandbox used as the Chrome user data dir (the Chrome profile). |
With `--profile`, you can keep more than one signed-in Chrome profile on one
sandbox. You select one profile for each stream. Boat creates the directory and
gives it to the browser user. The path must be absolute and outside system
directories. It must not be under `/home/user`, because the browser sandbox
hides that path with an empty directory. The profile is on the sandbox
filesystem, so snapshots and forks keep it. When you change the profile, Chrome
restarts and the stream stays up. Sandboxes created before this feature return
`chrome_profile_unsupported`. To use the flag, create the sandbox again on a
current image.
The stream has these properties:
* 1920x1080 at 60 fps.
* It shows Chrome with tabs and an address bar.
* It uses a separate streaming process and identity.
* It does not give access to the desktop clipboard bridge.
* It does not create a separate sandbox.
* It cannot fall back to the desktop or VNC.
* The window-close controls are hidden. Mute, reconnect, and fullscreen stay on the viewer.
Behavior:
* When you close the last tab, Chrome opens a new tab and the stream stays up.
* When you run the command again, the live stream stays up.
* When you open the new URL in a second tab, it replaces the first tab and keeps the same Chrome session.
* New sandboxes get the browser-view files when Boat provisions them.
Keep the URL secret.
This feature limits the display and the input. It does not isolate the browser from the sandbox. Code that already runs in the sandbox can read or change the browser process and its data. This is especially true for code with root access.
***
## Snapshots
### `boat snapshots [id]`
List the snapshots of all your sandboxes, or of one sandbox.
```bash theme={null}
boat snapshots
boat snapshots bx_f7k2q9hd
```
### `boat snapshot <id> <name>`
Save the disk of a sandbox under a name. `boat new --from <name>` can then deploy it as many times as you want. To replace a named snapshot, use its name again.
```bash theme={null}
boat snapshot bx_f7k2q9hd web-stack
boat snapshot current web-stack # from inside a sandbox
boat snapshot rm web-stack # remove it and release its storage
```
A save from a running sandbox first makes a new capture, so it can take minutes. The CLI polls until the snapshot is `ready`. You can keep up to 10 named snapshots. See [Snapshots & Copies](/snapshots).
### `boat snapshot share|shares|unshare`
Give another Boat account a secret code that deploys one of your named snapshots.
```bash theme={null}
boat snapshot share web-stack # make a code; it shows once
boat snapshot shares web-stack # list codes, use counts, status
boat snapshot unshare web-stack shr_... # revoke one code
boat new --from bsh_... # the other account deploys it
```
`share` prints the full code one time only. Save it immediately. Boat removes these items from the sandbox of the other account: your logins, API keys, secret files, repository clones and SSH keys. The other account gets all other data on the disk. See [Share a snapshot with another account](/snapshots/templates#share-a-template-with-another-account).
### `boat snapshot latest|tree|pull`
Look inside a snapshot or download it. This works while the sandbox is stopped.
```bash theme={null}
boat snapshot latest bx_f7k2q9hd
boat snapshot tree <snapshotId> # files and sizes
boat snapshot pull <snapshotId> -o ./restore # download and reassemble
```
`pull` writes `home_user/` (your `/home/user`) and `docker/` (named volumes). See [Snapshots](/snapshots).
### `boat snapshot delete <snapshotId>...`
Permanently delete ordinary filesystem snapshots. The command accepts all snapshots, and the snapshot disappears immediately. Boat erases its stored data in the background when nothing reads it. A newer snapshot that you keep can be built on it. Then its data stays until that newer snapshot is deleted too. `--all <sandboxId>` deletes all ordinary snapshots of a sandbox and keeps the sandbox. To remove a named snapshot, use `boat snapshot rm <name>` instead.
```bash theme={null}
boat snapshot delete <snapshotId>
boat snapshot delete <snapshotId> <snapshotId> --yes
boat snapshot delete --all bx_f7k2q9hd
```
See [Data retention and deletion](/data-retention).
***
## AI agents
### `boat prompt [id]`
Send a prompt in natural language to an AI agent in the sandbox.
* Without an ID, the prompt goes to the current sandbox of your shell (the last `boat new` there). If you run the CLI inside a sandbox, it goes to that sandbox.
* Without `--provider`, the prompt uses the default harness and model from the Agents page of the dashboard.
```bash theme={null}
boat prompt "Fix the failing tests in this repo"
boat prompt bx_f7k2q9hd --provider claude "Fix the failing tests in this repo"
boat prompt bx_f7k2q9hd --provider codex --model gpt-5.4-mini --reasoning-effort xhigh "Refactor auth module"
boat prompt bx_f7k2q9hd --provider codex --model gpt-6.1-sol --fast "Refactor auth module"
boat prompt --attach ./error.png --attach ./trace.log "Why does this crash?"
```
| Flag | Required | Values |
| - | - | - |
| `--provider` | no | `claude`, `codex`, `pi`, `opencode`, `prime`, `kimi`, `mistral`. Default: the Agents page default harness |
| `--model` | no | Provider-specific model name. Default: the model selected for that harness on the Agents page |
| `--reasoning-effort` | no | Provider/model-specific thinking level such as `none`, `low`, `medium`, `high`, `xhigh`, or `max`. The accepted levels differ for each model. Some models have none |
| `--fast` | no | No value. Run this prompt in fast mode: same model, faster output, billed by the provider at its higher fast rate. Only fast-capable models accept it. Default: the choice saved on the Agents page for that model |
| `--new` | no | Start a new conversation instead of continuing this shell's current one |
| `--resume <id>` | no | Continue a specific conversation by id (or `current` for this shell's) |
| `--attach <path>` | no | Attach a file (image, PDF, any file). Repeat for multiple. Alias `--image`. Saved on the sandbox under `~/attachments`. Images are also sent to vision-capable models |
To get the current list of providers, models, and reasoning efforts from the Boat API, run `boat prompt --help`. It lists the models that support fast mode under "Fast mode (--fast):".
#### Conversations (running agents in parallel)
A sandbox runs **many conversations at the same time**. Each conversation has its own history. So one sandbox can run more than one independent agent task in parallel, for example different features, different users, or a demo. The tasks do not wait in a queue.
```bash theme={null}
boat prompt --new "Start on the billing refactor" # conversation A
boat prompt --new "Investigate the flaky test" # conversation B, runs alongside A
boat prompt --resume <A> "Now add tests" # continue a specific conversation
boat prompt "quick follow-up" # continues THIS shell's current conversation
boat conversations # list them all, with ids to resume
```
* **`--new`** starts a new conversation and makes it the current conversation of this shell. Each prompt prints its conversation id directly under `queued:` (`conversation: <id>`, with `(new)` when `--new` created it). In `--json`, the id is in `conversationId`.
* **`--resume <id>`** continues a specific conversation. `--resume current` continues the current conversation of this shell.
* **No flag** continues the current conversation of this shell. The "current conversation" belongs to your shell, the same as the `current` sandbox id. Two shells (or two people) can prompt the same sandbox. Each one keeps its own conversation, and they do not interfere.
* **[`boat conversations`](#boat-conversations-id)** lists all conversations on the sandbox with the id, the number of prompts, the running state and the last prompt. You can then resume a conversation from another shell or another day by its id.
* Conversations run in parallel up to a limit for each sandbox. The limit increases with the memory of the sandbox. Above the limit, new prompts wait in a queue and start when turns finish.
* You can continue a conversation with a different `--provider`. The history stays after the change.
For how harnesses, conversations, the agent lifecycle, and parallel runs work together, with diagrams, see [Integrated agents](/integrated-agents).
### `boat ai`
Manage AI credentials: credential profiles, API keys, custom APIs, the AI credentials proxy, usage, and blocking. `--org <org>` selects an organization for `proxy`, `usage` and `profile new`. See [AI credentials](/ai-credentials).
```bash theme={null}
boat ai accounts chatgpt-subscription # out of credits on this account?
boat ai switch chatgpt-subscription 2 # every sandbox on the profile uses account 2 now
boat ai proxy on
boat ai profiles
boat ai profile new work --copy-from default
boat ai profile default work
echo "$ANTHROPIC_API_KEY" | boat ai profile set-key work anthropic-api-key
echo "$STRIPE_KEY" | boat ai profile set-api work STRIPE_KEY --base-url https://api.stripe.com/v1
boat ai usage bx_23456789 --days 7
boat ai block bx_23456789
```
| Command | Description |
| - | - |
| `boat ai accounts <credential> [--profile <p>]` | The accounts of one credential, numbered, the one in use marked |
| `boat ai switch <credential> <account> [--profile <p>]` | Switch the credential to another account: its number, email or last key characters. Every sandbox on the profile uses it at once, running ones included |
| `boat ai add-account <credential> [value] [--profile <p>]` | Add another API key, ready to switch to. Reads stdin when the value is omitted or `-`. For another sign-in, use "Add another account" on the dashboard |
| `boat ai forget-account <credential> <account> [--profile <p>]` | Delete an account. Forgetting the one in use switches to another account, or removes the credential if it was the last |
| `boat ai proxy [on\|off]` | Show the proxy state and price, or turn it on or off. Running sandboxes switch at their next start |
| `boat ai profiles [--org-only]` | The profiles you can use, yours and your organizations' |
| `boat ai profile new <name> [--copy-from <profile>]` | Create a profile. With `--org`, the organization owns it |
| `boat ai profile default <profile>` | Make the profile its owner's default. Sandboxes get it at their next start |
| `boat ai profile rename <profile> <new-name>` | Rename a profile |
| `boat ai profile rm <profile>` | Delete a profile. Not the default, and not one an environment names |
| `boat ai profile set-key <profile> <credential> [value]` | Set an API key, for example `anthropic-api-key`. Reads stdin when the value is omitted or `-` |
| `boat ai profile rm-key <profile> <credential>` | Remove an API key or a sign-in, for example `claude-subscription` |
| `boat ai profile set-api <profile> <NAME> --base-url <url> [--value <v>]` | Set a custom API. The sandbox gets `NAME` and `NAME_BASE_URL`. Reads stdin without `--value` |
| `boat ai profile rm-api <profile> <NAME>` | Remove a custom API |
| `boat ai usage [id] [--days N]` | Proxied usage: per sandbox for the account in scope, or per day and model for one sandbox. Default 30 days |
| `boat ai block <id>` | Refuse the sandbox's AI placeholders, running or stopped. No effect on a sandbox with real keys |
| `boat ai unblock <id>` | Accept them again |
***
## Account
### `boat limits`
Show the remaining machine starts, compute time, and credits. A create, a fork, and a resume each count as one start.
```bash theme={null}
boat limits
boat limits --json
```
The text output shows these values:
* Remaining starts for each minute, hour and day.
* Remaining compute, in hours.
* Remaining credit-pack dollars.
`--json` prints the same payload as the API, with `starts.minute.remaining`, `creditBalanceHours`, and `packBalanceDollars`.
### `boat usage <id>`
Show the machine time that one sandbox used and its cost, for its full life or for a time window. This works on running and stopped sandboxes. The value for a running sandbox increases until the sandbox stops. `running` in the JSON tells if the sandbox still runs. It is false after a stop, and also while a refused stop keeps the meter paused.
```bash theme={null}
boat usage bx_f7k2q9hd
boat usage bx_f7k2q9hd --since 2026-09-01 --until 2026-10-01
boat usage bx_f7k2q9hd --json
```
| Flag | Default | Description |
| - | - | - |
| `--since <time>` | sandbox creation | Count from this time, ISO 8601 or Unix seconds |
| `--until <time>` | now | Count up to this time, ISO 8601 or Unix seconds |
The text output shows the billable machine time (with the multiplier of the sandbox type), the cost at list price, and the window. `--json` prints the API payload: `seconds`, `dollars`, `secondsPerDollar`, `sandboxType`, `billingMultiplier`, `since`, `until` and `running`. See [Per-sandbox usage](/billing#per-sandbox-usage).
### `boat dashboard`
Open your web dashboard in the browser, already signed in. The link has a code that you can use one time. The code expires in 15 minutes and cannot call the API. It is never your sandbox token. So the link is safe in a terminal, a log, or a message. If you signed in with a service API key, the link opens the dashboard signed out. To create, rotate, or revoke API keys, you must sign in through the browser.
```bash theme={null}
boat dashboard
```
### `boat org`
Show, switch, create, transfer, or delete the **organization wallet** that new sandboxes bill to. An organization has one shared plan and one shared balance.
* `boat org switch` sets the active wallet of the account (`PATCH /orgs/active`). The dashboard and an API key without `--org` bill the same wallet.
* `--org` (or `BOAT_ORG`) uses a different wallet for one command.
* Name an organization by its id or its name, as `boat org list` shows them.
```bash theme={null}
boat org # show the active wallet
boat org list # organizations you belong to, ids and names
boat org switch acme # bill new sandboxes to acme, from the CLI, the dashboard and the API
boat org switch personal # back to your own account
boat --org acme new # bill one create to acme without switching
boat --org personal new # bill one create to your account while an org is sticky
boat org create "Acme"
boat --org acme org transfer alice
boat --org acme org delete --yes
boat --org acme org migrate # move your personal plan and sandboxes into acme
boat org members # members and pending invites of the org in scope
boat org invite dana@example.com # owner only
```
`boat share <id>` gives one of your org sandboxes to the full team. Boat removes your logins from it at its next start. If it is running, stop and resume it. For what teammates can do with the sandboxes of the org, see [Organizations & teams](/organizations).
`boat org transfer`, `boat org delete` and `boat org migrate` act on the scope of the command. This is `--org` or `BOAT_ORG` if set. If not, it is the wallet from `boat org switch`. If you delete an org with `--org`, a different wallet from `boat org switch` stays active.
`boat org migrate` is for an owner who paid personally before the organization existed. It does these things:
* From that moment, each sandbox billed to your personal account bills the organization.
* Your personal plan ends the same day. Boat refunds the unused part of the month to your card.
* Credit packs that you bought stay on your personal account.
The organization must already have a plan. `boat --org acme billing plan 20 --move-personal` starts a plan and does the move in one step.
### `boat billing`
Manage the plan, extra time, prepaid balance and auto-refill of the wallet in scope. This is your personal account, or the organization from `boat org switch` or `--org`. A step that needs a card opens Stripe Checkout in your browser. The command waits until the payment is complete.
```bash theme={null}
boat billing # plan, renewal date, time left, prepaid balance, auto-refill
boat billing plan # the tiers, with the current one marked
boat billing plan 100 # switch to the $100/mo tier (prorated) or start it
boat billing credits 3 # three $20 packs of extra time; never expire
boat billing funds 50 # $50 of prepaid balance, spent before the card
boat billing autorefill on # buy time automatically when the balance runs low
boat billing portal # Stripe portal: card on file, invoices
boat --org acme billing credits 2 # same, on the organization's wallet (owner only)
boat --org acme billing plan 20 --move-personal # first org plan + bring your personal plan and sandboxes
```
The plan of an organization is per seat. `boat --org acme billing plan 100` bills \$100 × seats. The seats are the members. There are more seats if the owner bought extra seats on the dashboard. See [Organizations](/organizations/seats-and-limits#seats).
### `boat data-retention`
Show or enable zero data retention. Zero data retention puts each archived sandbox in a queue for permanent deletion.
```bash theme={null}
boat data-retention status
boat data-retention enable
boat data-retention enable --yes
```
To enable it, you need a browser sign-in session (`boat login` without a key). An API key does not work. See [Data retention and deletion](/data-retention).
### `boat self-update`
Find and install the latest CLI release on your current channel.
```bash theme={null}
boat self-update
```
The local configuration is at `~/.config/ascii/boat/config.json`. `boat status` prints its path, the API URL in use, the account and the plan.
# Data retention and deletion
Source: https://docs.boat.dev/data-retention
Choose archive or permanent deletion, enable zero data retention, and understand what is retained.
<video />
A stop archives a sandbox. A delete erases it. These are not the same.
## Archive is not delete
| Action | Can you resume the sandbox? | What happens to data? |
| - | - | - |
| **Stop/archive** | Yes | Boat keeps the filesystem snapshots of the sandbox for resume or fork. |
| **[Delete](/data-retention/delete)** | No | Boat queues the sandbox content, unshared snapshots and machine data for irreversible deletion. |
| **[Zero data retention (ZDR)](/data-retention/zero-data-retention)** | No after archive | Boat queues every archived sandbox for deletion automatically. |
| **[Snapshots off](/data-retention/snapshots-and-monitoring-off#snapshots-off)** | No | Boat never captures the sandbox. A stop erases it. |
| **[Monitoring off](/data-retention/snapshots-and-monitoring-off#monitoring-off)** | Yes | Boat keeps no command or process output, no process list and no CPU/RAM samples. |
## Command history
The [command history](/long-running-tasks/command-history) of a sandbox is account data.
| Record | Kept for |
| - | - |
| A command you run through `boat exec` or the API, and its output | 90 days |
| The output of every other process in the sandbox | 72 hours |
* A delete erases both records with the rest of the sandbox.
* With ZDR, a stop queues both records for deletion with the rest of the sandbox.
* With ZDR, Boat does not save the output that a process wrote after the last 30-second read.
## All surfaces
Every task on these pages works on all four surfaces.
| | CLI | API | SDKs | Dashboard |
| - | - | - | - | - |
| Delete a sandbox | `boat delete <id>` | `DELETE /sandboxes/{sandboxId}` | `deleteSandbox` | [Sandboxes](https://boat.dev/dashboard?tab=sandboxes) `⋯` → Delete |
| Delete a snapshot | `boat snapshot delete <id>` | `DELETE /snapshots/{snapshotId}` | `deleteSnapshot` | [Snapshots](https://boat.dev/dashboard?tab=snapshots) |
| Delete all snapshots of a sandbox | `boat snapshot delete --all <id>` | `DELETE /sandboxes/{sandboxId}/snapshots` | `deleteSandboxSnapshots` | [Snapshots](https://boat.dev/dashboard?tab=snapshots) → Select all |
| Delete a named snapshot | `boat snapshot rm <name>` | `DELETE /named-snapshots/{name}` | `deleteNamedSnapshot` | [Snapshots](https://boat.dev/dashboard?tab=snapshots) |
| Poll an operation | `boat deletion status <id>` | `GET /deletion-operations/{id}` | `getDeletionOperation` | shown inline while deleting |
| Read ZDR | `boat data-retention status` | `GET /account/data-retention` | `getDataRetention` | [Account](https://boat.dev/dashboard?tab=account) |
| Enable ZDR | `boat data-retention enable` | `PATCH /account/data-retention` | `updateDataRetention` | [Account](https://boat.dev/dashboard?tab=account) |
<Warning>
You cannot cancel a deletion operation. If you disable ZDR, only future archives change. Operations that Boat already accepted continue.
</Warning>
## Records kept after content deletion
Ascii keeps only the records that it needs for security, abuse prevention, compliance and billing. These records are:
* Machine-assignment history (internally `MachineAssignmentLog`).
* Network attribution, such as assigned IP and MAC records.
* Security audit events.
* Billing and usage records.
These records show who controlled the infrastructure and when. They do not keep your sandbox filesystem, prompts, messages, secrets or generated artifacts.
## Learn more
<Columns>
<Card title="Delete a sandbox or snapshot" icon="trash" href="/data-retention/delete">
Delete a sandbox or snapshots, follow the operation, and how named snapshots are deleted.
</Card>
<Card title="Zero data retention" icon="shield" href="/data-retention/zero-data-retention">
Read and enable ZDR. What changes when it is on.
</Card>
<Card title="Snapshots off and monitoring off" icon="eye-slash" href="/data-retention/snapshots-and-monitoring-off">
Keep no snapshots, or keep no monitoring data, for one sandbox or the whole account.
</Card>
<Card title="Close your account" icon="user-xmark" href="/data-retention/close-account">
Close your account, reopen it in 30 days, or erase it for good.
</Card>
</Columns>
## Related
* [Privacy Policy](https://boat.dev/privacy)
* [Snapshots](/snapshots)
* [CLI reference](/cli-reference)
* [Boat Public API v1](/api/v1)
* [Delete Boat API](/api/reference/sandboxes/permanently-delete-sandbox-data)
* [Update data retention API](/api/reference/account/update-account-data-retention-policy)
# Close your account
Source: https://docs.boat.dev/data-retention/close-account
Close your account, reopen it within 30 days, or erase it permanently for a GDPR request.
Closing removes the whole account, not one sandbox.
You can close the account only on the [Account](https://boat.dev/dashboard?tab=account) tab. It needs a dashboard sign-in session. Boat refuses the request from an API key and from the CLI.
## What closing does
Closing does all of these at once:
* It cancels your subscription **immediately**, not at the end of the period. You lose the remaining plan time and unused credits. If you close just after a renewal, you lose that renewal.
* It archives every running sandbox, with a snapshot.
* It revokes every API key and every other session. The session that you closed from stays active, so you can still read your invoices.
* It sends you a confirmation email with the date when Boat purges your data.
## The 30-day window
| Time after closing | State of the account |
| - | - |
| Up to **30 days** | Closed but recoverable. **Reopen** on the same tab brings it back, except the subscription. |
| After 30 days | Boat purges the sandbox data permanently. If you reopen, you get a working but empty account. |
## Permanent erasure
<Warning>
The same screen also offers permanent erasure, for GDPR requests. It does not wait 30 days. It scrubs the data and your identity when the sandboxes finish archiving. You **cannot cancel or reopen** it. Use ordinary closing, unless you specifically need erasure.
</Warning>
# Delete a sandbox or snapshot
Source: https://docs.boat.dev/data-retention/delete
Delete a sandbox, its snapshots or a named snapshot, and follow the deletion operation until the data is erased.
A delete is permanent. You cannot resume a deleted sandbox.
## How a delete works
1. You send a delete request.
2. Boat returns `202 Accepted` with an operation.
3. The sandbox or snapshot disappears from lists, restores and forks immediately.
4. Boat erases the stored data in the background, when nothing reads it any more.
5. You poll the operation until its status is `completed`.
Boat never refuses a delete because the data is still in use.
The `stage` of the operation tells you where the deletion is.
| `stage` | Meaning |
| - | - |
| `removing` | Boat erases the stored data now. |
| `waiting_for_uploads` | Boat erases the data at `expectedBy`, when the last upload link issued for it expires. This is at most six hours after the last upload. |
| `kept_for_newer_snapshots` | A newer snapshot, or a sandbox forked or deployed from it, still builds on this data. Boat erases this data when those are deleted. The status stays `blocked` until then. |
| `waiting_for_restore` | A sandbox still restores from it. |
| `retrying` | A transient fault occurred. Boat retries automatically. |
| `completed` | Boat erased every snapshot of it. A fork or named snapshot made from it keeps its own copy until you delete that too. |
<Warning>
You cannot cancel a deletion operation.
</Warning>
## Delete a sandbox
Every sandbox or snapshot delete needs the header `X-Ascii-Confirm-Delete`. Its value must be exactly the target id. The CLI and the dashboard set this header for you.
<CodeGroup>
```bash CLI theme={null}
boat delete bx_f7k2q9hd # asks first, then follows the operation to completion
boat delete bx_f7k2q9hd --yes # no prompt, for scripts
```
```bash curl theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "X-Ascii-Confirm-Delete: $BOAT_ID"
```
```ts TypeScript theme={null}
const accepted = await sandbox.deleteSandbox({
sandboxId: "bx_f7k2q9hd",
xAsciiConfirmDelete: "bx_f7k2q9hd",
});
console.log(accepted.operation.id, accepted.operation.status);
```
```python Python theme={null}
accepted = sandbox.delete_sandbox(
x_ascii_confirm_delete="bx_f7k2q9hd",
sandbox_id="bx_f7k2q9hd",
)
print(accepted.operation.id, accepted.operation.status)
```
</CodeGroup>
In the dashboard, open [Sandboxes](https://boat.dev/dashboard?tab=sandboxes). Open the `⋯` menu on the row of the sandbox and choose **Delete**.
## Poll the operation
A delete returns an operation id (`bdop_…`). Poll it until `status` is `completed`.
<CodeGroup>
```bash CLI theme={null}
boat deletion status bdop_0123456789abcdef0123456789abcdef
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/deletion-operations/$OPERATION_ID" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const current = await sandbox.getDeletionOperation({ operationId: accepted.operation.id });
console.log(current.operation.status); // pending | processing | blocked | completed
```
```python Python theme={null}
current = sandbox.get_deletion_operation(accepted.operation.id)
print(current.operation.status)
```
</CodeGroup>
`boat delete` already polls for you. It prints the operation when it finishes. Use `boat deletion status` to check later on an operation that you started elsewhere.
## Delete one snapshot
| Request | What it deletes | Confirmation header |
| - | - | - |
| `DELETE /snapshots/{snapshotId}` | One ordinary snapshot | The snapshot id |
| `DELETE /sandboxes/{sandboxId}/snapshots` | Every ordinary snapshot of one sandbox. The sandbox stays. | The sandbox id |
| `DELETE /named-snapshots/{name}` | One named snapshot, by name | None |
<CodeGroup>
```bash CLI theme={null}
boat snapshot delete <snapshotId> # one ordinary filesystem snapshot
boat snapshot delete --all bx_f7k2q9hd # every ordinary snapshot of a sandbox
boat snapshot rm web-stack # a named snapshot, by name
```
```bash curl theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/snapshots/$SNAPSHOT_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "X-Ascii-Confirm-Delete: $SNAPSHOT_ID"
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID/snapshots" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "X-Ascii-Confirm-Delete: $BOAT_ID"
curl -sS -X DELETE "$BOAT_API_BASE/named-snapshots/web-stack" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.deleteSnapshot({
snapshotId: "<snapshotId>",
xAsciiConfirmDelete: "<snapshotId>",
});
await sandbox.deleteSandboxSnapshots({
sandboxId: "bx_f7k2q9hd",
xAsciiConfirmDelete: "bx_f7k2q9hd",
});
await sandbox.deleteNamedSnapshot({ name: "web-stack" });
```
```python Python theme={null}
sandbox.delete_snapshot(
snapshot_id="<snapshotId>",
x_ascii_confirm_delete="<snapshotId>",
)
sandbox.delete_sandbox_snapshots(
sandbox_id="bx_f7k2q9hd",
x_ascii_confirm_delete="bx_f7k2q9hd",
)
sandbox.delete_named_snapshot("web-stack")
```
</CodeGroup>
You can also delete snapshots on the [Snapshots](https://boat.dev/dashboard?tab=snapshots) tab of the dashboard.
Deletion and retention responses use `Cache-Control: no-store`.
## Shared and named snapshots
* A sandbox delete does not delete a named snapshot that you saved from it.
* A named snapshot is an independent shared artifact.
* A named snapshot can share deduplicated storage with other snapshots.
* Boat removes the stored objects only when no kept artifact uses them.
When you remove a named snapshot, it becomes unavailable immediately. Boat schedules the deletion of its data **six hours** later at the earliest. Snapshot upload URLs stay valid for six hours. This delay stops an upload that already started from creating the data again after the delete.
If you enable [zero data retention](/data-retention/zero-data-retention), Boat removes your named snapshots and queues their data for deletion. You cannot create a named snapshot while ZDR is on.
# Snapshots off and monitoring off
Source: https://docs.boat.dev/data-retention/snapshots-and-monitoring-off
Keep no snapshots of a sandbox, or keep no monitoring data, for one sandbox or for the whole account.
| Setting | What Boat does not keep | Can you resume the sandbox? |
| - | - | - |
| [Snapshots off](#snapshots-off) | Any copy of the sandbox outside its machine | No. A stop erases it. |
| [Monitoring off](#monitoring-off) | Command and process output, the process list, CPU/RAM samples | Yes |
## Snapshots off
Boat never captures a sandbox with snapshots off.
* Nothing of the sandbox is stored outside its machine.
* No background work runs on it.
* A stop erases it.
* You cannot resume it, fork it or save it as a named snapshot.
* If its machine fails, there is no backup.
* If you create it from a template, a named snapshot or another sandbox, its snapshot list shows that source's snapshots with `origin: "template"`. They are copies of the source's data. Boat did not capture them from this sandbox.
### Turn snapshots off for the whole account
1. Open the [Account](https://boat.dev/dashboard?tab=account) tab.
2. Under **Data & privacy**, turn on **Snapshots off**.
Every sandbox that you create or fork after this has snapshots off, from any surface. Existing sandboxes keep their setting.
### Turn snapshots off for one sandbox
<CodeGroup>
```bash CLI theme={null}
boat new --no-snapshots
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"snapshots":false}'
```
```ts TypeScript theme={null}
await sandbox.create({ snapshots: false });
```
```python Python theme={null}
from boat_sdk.models.create_sandbox_request import CreateSandboxRequest
sandbox.create(CreateSandboxRequest(snapshots=False))
```
</CodeGroup>
## Monitoring off
Boat keeps no monitoring data for a sandbox with monitoring off.
| Not kept | Still works |
| - | - |
| [Command history](/long-running-tasks/command-history) and the output of every process | Live output of a running command (attach, read from an offset) |
| The process list | Abuse checks on the machine |
| CPU, RAM, disk and IO samples, and their graphs and [OpenTelemetry](/opentelemetry) metrics | Lifecycle events and webhooks |
* The sandbox runs no process tracer.
* Disk-full alerts need CPU/RAM samples. They are not available for this sandbox.
* The cause shown for a lost sandbox needs CPU/RAM samples. It is not available for this sandbox.
* Its history, processes and metrics calls return `409 monitoring_off`.
### Turn monitoring off for the whole account
Do one of these:
* On the [Account](https://boat.dev/dashboard?tab=account) tab, under **Data & privacy**, turn on **Monitoring off**.
* Send `PATCH /account/data-retention` with `{"monitoringOff": true}`.
Every sandbox that you create or fork after this has monitoring off. Existing sandboxes keep their setting.
While this setting is on, Boat refuses a request with `monitoring: true`. The error is `409 monitoring_off_for_account`.
A fork of a sandbox with monitoring off also has monitoring off. To change this, send `monitoring: true` in the fork request.
### Turn monitoring off for one sandbox
<CodeGroup>
```bash CLI theme={null}
boat new --no-monitoring
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"monitoring":false}'
```
```ts TypeScript theme={null}
await sandbox.create({ monitoring: false });
```
```python Python theme={null}
from boat_sdk.models.create_sandbox_request import CreateSandboxRequest
sandbox.create(CreateSandboxRequest(monitoring=False))
```
</CodeGroup>
The sandbox shows `"monitoring": false`.
# Zero data retention
Source: https://docs.boat.dev/data-retention/zero-data-retention
Read and enable zero data retention (ZDR), and what Boat deletes when it is on.
With zero data retention (ZDR), Boat queues every archived sandbox for deletion. You cannot resume a sandbox after it archives.
## Read the setting
You can read the setting from anywhere. An API key works.
<CodeGroup>
```bash CLI theme={null}
boat data-retention status
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/account/data-retention" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const policy = await sandbox.getDataRetention();
console.log(policy.enabled);
```
```python Python theme={null}
policy = sandbox.get_data_retention()
print(policy.enabled)
```
</CodeGroup>
`GET /me` also returns the setting, in the `zeroDataRetention` fields.
## Enable zero data retention
<Warning>
To **change** the setting, you need an interactive browser session. An API key does not work. Run `boat login` without a key first, or use the dashboard. An SDK client that uses `BOAT_API_KEY` gets `403 session_required`. This is by design. Enabling ZDR queues every archived sandbox for deletion, so a leaked service credential must never reach it.
</Warning>
1. Sign in with a browser session. Run `boat login` without a key, or open the dashboard.
2. Send the exact phrase `delete archived sandbox data` as the confirmation.
<CodeGroup>
```bash CLI theme={null}
boat data-retention enable # prompts for the confirmation phrase
boat data-retention enable --yes # skip the prompt
```
```bash curl theme={null}
curl -sS -X PATCH "$BOAT_API_BASE/account/data-retention" \
-H "Authorization: Bearer $BOAT_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled":true,"confirmation":"delete archived sandbox data"}'
```
```ts TypeScript theme={null}
// Requires a browser session token, not an API key.
await sandbox.updateDataRetention({
enabled: true,
confirmation: "delete archived sandbox data",
});
```
```python Python theme={null}
from boat_sdk.models.data_retention_update_request import DataRetentionUpdateRequest
# Requires a browser session token, not an API key.
sandbox.update_data_retention(DataRetentionUpdateRequest(
enabled=True,
confirmation="delete archived sandbox data",
))
```
</CodeGroup>
In the dashboard, the toggle is under **Data & privacy** on the [Account](https://boat.dev/dashboard?tab=account) tab.
## What happens when ZDR is on
* Boat queues your existing archived sandboxes for deletion.
* Future sandboxes discard their data when they archive.
* Boat removes your named snapshots and queues their data for deletion.
* Accepted deletions continue in the background until Boat verifies that they are complete.
<Warning>
You cannot cancel a deletion operation. If you disable ZDR, only future archives change. Operations that Boat already accepted continue.
</Warning>
ZDR still snapshots a sandbox while it runs. Boat uses these snapshots to rebuild a sandbox after a machine fails. To keep nothing at all, turn [snapshots off](/data-retention/snapshots-and-monitoring-off#snapshots-off).
# Desktop Streaming
Source: https://docs.boat.dev/desktop-streaming
How Boat opens a browser-based desktop stream for GUI work, and how its agents drive the same screen.
<video />
Each sandbox has a Linux desktop that you open in your browser. Use it for these tasks:
* Look at a running app.
* Use Chrome.
* Debug Electron apps.
* Control GUI tools that are hard to use over SSH.
The agents of the sandbox drive the same screen with the built-in [`computer` tools](/integrated-agents/computer-use). You can watch a prompt do GUI work live.
## Open the desktop
Run this command on your computer. It opens a desktop URL that is already signed in. Integrations get the same URL through the SDK or the API.
<CodeGroup>
```bash CLI theme={null}
boat desktop bx_f7k2q9hd
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/desktop?theme=light" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const desktop = await sandbox.desktop({ sandboxId: "bx_f7k2q9hd", theme: "light" });
console.log(desktop.desktopUrl);
```
```python Python theme={null}
desktop = sandbox.desktop("bx_f7k2q9hd", theme="light")
print(desktop.desktop_url)
```
</CodeGroup>
You can also open the desktop from the [Sandboxes](https://boat.dev/dashboard?tab=sandboxes) tab of the dashboard while the sandbox runs.
<Note>
The desktop is available only after the machine of the sandbox is up. If the sandbox is provisioning, archived or stopped, start or resume it first.
</Note>
## Ways to view the sandbox
| View | What you see | Command |
| - | - | - |
| Desktop (default) | The full desktop over Moonlight (WebRTC), 1920x1080 at 60 fps | `boat desktop <id>` |
| Desktop via VNC | The full desktop over plain HTTPS, at a lower frame rate | `boat desktop <id> --vnc` |
| Browser | Only Chrome, 1920x1080 at 60 fps | `boat browser <id>` |
## Learn more
<Columns>
<Card title="Streaming modes" icon="signal" href="/desktop-streaming/streaming-modes">
Moonlight or VNC. Which one to use on a slow or strict network.
</Card>
<Card title="Browser-only view" icon="window-maximize" href="/desktop-streaming/browser-only">
Show only Chrome. Use more than one Chrome profile.
</Card>
<Card title="Drive and record the desktop" icon="robot" href="/desktop-streaming/drive-and-record">
Let an agent use the screen. Record the screen to an MP4.
</Card>
<Card title="Desktop background" icon="image" href="/desktop-streaming/background">
Put your own PNG on the desktop.
</Card>
<Card title="URLs, embedding and security" icon="lock" href="/desktop-streaming/urls-and-security">
What a desktop URL looks like, how to embed it, and how to keep it safe.
</Card>
</Columns>
## Related
* [Computer use for the sandbox's agents](/integrated-agents/computer-use)
* [SSH Access](/ssh-access)
* [Long-Running Tasks](/long-running-tasks)
* [Hosting](/hosting)
* [Machine Capabilities](/machines)
# Desktop background
Source: https://docs.boat.dev/desktop-streaming/background
Put your own PNG image on the sandbox desktop.
## Set your own background
1. Put a PNG file at `~/.config/boat/wallpaper.png` on the sandbox.
2. The desktop shows it at once.
The image stays after a stop, a resume and a fork. To go back to the default background, delete the file.
<CodeGroup>
```bash CLI theme={null}
boat scp ./wallpaper.png bx_f7k2q9hd:/home/user/.config/boat/wallpaper.png
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"curl -fsSL -o ~/.config/boat/wallpaper.png https://example.com/wallpaper.png"}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: "curl -fsSL -o ~/.config/boat/wallpaper.png https://example.com/wallpaper.png",
});
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(
command="curl -fsSL -o ~/.config/boat/wallpaper.png https://example.com/wallpaper.png",
))
```
</CodeGroup>
## Image limits
| Limit | Value |
| - | - |
| Format | PNG |
| File size | 16 MiB or less |
| Width or height | 8192 pixels or less |
| Total pixels | 16,777,216 or less (for example 4096x4096) |
The image fills the screen and keeps its aspect ratio. If the file is not a valid PNG, the desktop keeps the default background.
# Browser-only view
Source: https://docs.boat.dev/desktop-streaming/browser-only
Stream only Chrome from a sandbox, without the desktop, and choose which Chrome profile to open.
Use the browser-only view when a person must see and control Chrome, but not the sandbox desktop.
## Open the browser view
* In the dashboard, open the sandbox menu and select **Browser**.
* In the CLI, run one of these commands:
```bash theme={null}
boat browser bx_f7k2q9hd
boat browser bx_f7k2q9hd --profile /data/chrome-profile
```
## Use a Chrome profile
Add `--profile <absolute path on the sandbox>` to stream a specific Chrome user data directory. One sandbox can then hold several signed-in profiles. You choose which one to open.
| Rule | Detail |
| - | - |
| Creation | Boat creates the directory for you. |
| Location | Outside system directories and outside `/home/user`. |
| Snapshots | The directory goes with the snapshots and forks of the sandbox. |
| Old sandboxes | Sandboxes created before this feature return `chrome_profile_unsupported`. |
## How the browser view works
The browser view is a separate browser surface on the same running sandbox. It does not create another sandbox. It never falls back to the desktop or to VNC.
| Topic | Behavior |
| - | - |
| Stream quality | 1920x1080 at 60 fps, the same as the default desktop. |
| Chrome | Chrome keeps its tabs and its address bar. |
| Close controls | Boat hides the window-close controls on purpose. |
| Minimize | Chrome's minimize cannot leave the stream on a blank desktop. |
| Last tab | When you close the last tab, Chrome opens a new tab. The stream stays up. |
| Run `boat browser` again | The live stream stays up. The command prints a new URL. |
| Second viewer tab | Two browser viewer tabs cannot share the stream. The new tab takes the stream from the first tab. |
| Desktop at the same time | The desktop and the browser view can run together. |
| Viewer controls | Mute, reconnect and fullscreen, the same as the desktop stream. |
The browser view has its own Moonlight process, streaming identity, active-stream slot and clipboard policy. These are separate from the desktop stream. Thus a browser URL cannot attach to the desktop stream.
New sandboxes get the browser-view files when Boat provisions them. The guest image must already have Chrome, X, Openbox, Sunshine and Moonlight.
<Warning>
The browser-only view limits the stream to Chrome. It does not show controls to close Chrome. It is not a security boundary against code that already runs inside the sandbox. A Boat user who can run any code, or who has root, can read or change the browser process and its data. Keep the returned URL secret.
</Warning>
# Drive and record the desktop
Source: https://docs.boat.dev/desktop-streaming/drive-and-record
Let the agents of a sandbox use its desktop, mix shell commands with prompts, and record the screen to an MP4.
## Drive the desktop with a prompt
The coding agents of the sandbox drive the same screen that you stream. Each harness on a sandbox has built-in `computer` tools. These tools take screenshots, click, type, scroll and start apps. You only send a prompt:
<CodeGroup>
```bash CLI theme={null}
boat prompt bx_f7k2q9hd "Open example.com in Chrome and tell me the page title"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Open example.com in Chrome and tell me the page title"}'
```
```ts TypeScript theme={null}
await sandbox.prompt({
sandboxId: "bx_f7k2q9hd",
prompt: "Open example.com in Chrome and tell me the page title",
});
```
```python Python theme={null}
sandbox.prompt("bx_f7k2q9hd", PromptRequest(
prompt="Open example.com in Chrome and tell me the page title",
))
```
</CodeGroup>
Open a stream in one window. Watch the agent work in it.
* You install nothing.
* You register nothing.
* Each harness already has the tools.
For the full tool list, the tool names per harness and the health check, read [Computer use](/integrated-agents/computer-use).
## Mix shell commands and prompts
Shell commands also work on the same screen. You can use them together with prompts. For example, open a page yourself, then give the sandbox a visual task:
<CodeGroup>
```bash CLI theme={null}
boat exec bx_f7k2q9hd 'DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome'
boat prompt bx_f7k2q9hd "Complete the checkout flow in the open browser window"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"DISPLAY=:0 google-chrome-stable \"https://example.com\" & sleep 2; wmctrl -a Chrome"}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: 'DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome',
});
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(
command='DISPLAY=:0 google-chrome-stable "https://example.com" & sleep 2; wmctrl -a Chrome',
))
```
</CodeGroup>
<Warning>
A sandbox has one screen. Each conversation on the sandbox drives that same screen. If two agents click at the same time, they interfere with each other. Give each parallel GUI task its own sandbox, or run the tasks one after the other.
</Warning>
## Record the screen
`ascii-record-desktop` records the live desktop to an MP4 from inside the sandbox. Use it to make a demo or to keep evidence of a GUI run.
<CodeGroup>
```bash CLI theme={null}
boat exec bx_f7k2q9hd "ascii-record-desktop start /home/user/demo.mp4"
# ... drive the desktop ...
boat exec bx_f7k2q9hd "ascii-record-desktop stop"
boat scp bx_f7k2q9hd:/home/user/demo.mp4 ./demo.mp4
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"ascii-record-desktop start /home/user/demo.mp4"}'
curl -L -o demo.mp4 "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/artifacts?path=demo.mp4" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: "ascii-record-desktop start /home/user/demo.mp4",
});
const video = await sandbox.artifact({ sandboxId: "bx_f7k2q9hd", path: "demo.mp4" });
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(
command="ascii-record-desktop start /home/user/demo.mp4",
))
video = sandbox.artifact("bx_f7k2q9hd", "demo.mp4")
```
</CodeGroup>
Run `ascii-record-desktop status` to see if a recording runs.
To share a recording without a download, serve its folder from the sandbox. Then expose the folder with a URL that needs a token:
```bash theme={null}
boat ssh bx_f7k2q9hd "cd ~ && (python3 -m http.server 8090 --bind 0.0.0.0 &) && host 8090 --private"
```
# Streaming modes
Source: https://docs.boat.dev/desktop-streaming/streaming-modes
Stream the desktop over Moonlight (WebRTC) or over VNC, and how to switch between them.
The desktop has two streaming modes.
| Mode | Transport | Quality | Best for |
| - | - | - | - |
| Moonlight (default) | WebRTC, which uses UDP and peer connections | Video and audio, 1920x1080 at 60 fps | Most networks |
| VNC | Plain HTTPS | Lower frame rate | Strict, corporate or low-bandwidth networks |
On a strict, corporate or low-bandwidth network, Moonlight can be choppy. It can also fail to connect. VNC works much better on a poor connection.
## Open the desktop over VNC
<CodeGroup>
```bash CLI theme={null}
boat desktop bx_f7k2q9hd --vnc
boat desktop bx_f7k2q9hd --vnc --public
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/desktop?vnc=1" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"publicAccess":true}'
```
```ts TypeScript theme={null}
const vnc = await sandbox.desktop({
sandboxId: "bx_f7k2q9hd",
vnc: 1,
requestBody: { publicAccess: true },
});
console.log(vnc.desktopUrl);
```
```python Python theme={null}
vnc = sandbox.desktop("bx_f7k2q9hd", vnc=1, request_body={"publicAccess": True})
print(vnc.desktop_url)
```
</CodeGroup>
## Switch mode in the viewer
You do not have to choose the mode first.
* The browser viewer shows a **"Switch to VNC"** option while the default stream connects or plays.
* The viewer shows this option again if the default stream has an error.
* The sandbox menu in the dashboard has three items: **Desktop**, **Browser** and **Desktop via VNC**.
<Note>
The VNC viewer opens as its own top-level page. It is not embedded. Its connection can authenticate only from a top-level page. The first `--vnc` on a sandbox takes a few seconds to prepare. Later opens are instant.
</Note>
# URLs, embedding and security
Source: https://docs.boat.dev/desktop-streaming/urls-and-security
What a desktop URL contains, how to embed the stream in your app, and how Boat protects the desktop.
## What happens when you open the desktop
1. The CLI or the dashboard asks Boat for a new signed-in desktop URL for your sandbox.
2. If the desktop stream is not ready, Boat prepares it.
3. Boat opens the browser viewer.
The URL opens a browser page. For the default Moonlight stream, the URL looks like this:
```text theme={null}
https://<sandbox-desktop-host>/stream.html?hostId=<host>&appId=<app>&theme=light#token=<token>
```
For a VNC stream (`--vnc`), the URL points to a noVNC page:
```text theme={null}
https://<sandbox-vnc-host>/vnc.html?autoconnect=true&password=<pw>&_token=<token>
```
Boat generates the host, the IDs, the password and the token for the running sandbox.
If you use `--public`, or send `publicAccess: true` to `POST /sandboxes/{sandboxId}/desktop?vnc=1`, the noVNC URL has no `_token`.
## How the Moonlight viewer handles the token
* The viewer removes the fragment from the URL at once.
* The viewer sends the token in authenticated request headers and in the first WebSocket frame.
* The viewer never puts the token in an HTTP or WebSocket request URL.
## Embed the stream in your app
To show the desktop inside your own product, put the default Moonlight URL in an `iframe`.
To hide the viewer overlay, add `overlay=0` to the query string. The side panel and the stats text then never show.
```text theme={null}
https://<sandbox-desktop-host>/stream.html?hostId=<host>&appId=<app>&theme=light&overlay=0#token=<token>
```
Add the parameter before the `#`. The token stays in the fragment.
## Security model
| Topic | Rule |
| - | - |
| How Boat makes a URL | Only through the authenticated Boat API. |
| URL lifetime | Ten minutes. |
| List and info responses | They do not cache or return a desktop URL. Call the desktop endpoint each time you open a stream. |
| Clipboard | Reads and writes work only with the credentials of the active desktop Moonlight stream. |
| Browser-only view | It has no clipboard routes. |
A desktop URL contains a desktop access token in its fragment. The URL can let a browser attach to that desktop session. Treat the URL as sensitive:
* Do not paste the full URL into shared chats or logs.
* To give another person access to a sandbox, use the correct Boat account and access controls. Do not share a desktop URL.
## After a stop, resume or fork
* When you stop or archive a sandbox, the desktop is not available. Resume the sandbox to use it again.
* Do not expect desktop processes to survive a resume or a fork. After a resume or a fork, open Chrome again and restart your app or dev server.
* The `computer` tools come back by themselves. Boat restarts the desktop daemon behind them with the sandbox.
# Environments
Source: https://docs.boat.dev/environments
Decide what every new sandbox starts with: repositories, secrets, and which of your credentials it can use.
<video />
An **environment** is the template that a new sandbox gets when it starts. It sets three things:
* The GitHub repositories that Boat clones into the sandbox.
* The secrets that Boat injects into the sandbox.
* The credentials of yours that the sandbox can use.
Manage environments in [Dashboard > Environment](https://boat.dev/dashboard?tab=environment) or with the `boat env` commands.
Every account has one environment named `base`. You can add more environments. You name the environment for a sandbox when you create, resume or fork it.
<Note>
This page is about what goes **into** a sandbox. To run code inside a sandbox, read [Setup & Scripts](/setup).
</Note>
## Safe for third parties
One switch sets the security of an environment.
| Switch | Use it for | What the sandbox gets |
| - | - | - |
| On | Sandboxes that other people use, for example your end users | Nothing of yours. The sandbox cannot act on your account or your other sandboxes. |
| Off | Sandboxes that only you use | What the four section toggles allow |
```bash theme={null}
boat env set base --safe-for-third-parties true
```
For all the details, read [Access and credentials](/environments/access).
## What happens when you save a change
* Boat makes a new version of the environment.
* New sandboxes get the new version.
* Running sandboxes stay on their version until you upgrade them.
Read [Versions and upgrades](/environments/versions).
## Learn more
<Columns>
<Card title="Access and credentials" icon="shield-check" href="/environments/access">
The safe for third parties switch, the four section toggles, and how to protect an existing sandbox.
</Card>
<Card title="Versions and upgrades" icon="code-branch" href="/environments/versions">
Which version a sandbox uses, and how to move it to the latest one.
</Card>
<Card title="Repositories" icon="github" href="/environments/repositories">
Clone GitHub repositories into each sandbox, and find where they land.
</Card>
<Card title="Secrets" icon="key" href="/environments/secrets">
Environment variables, secret files, and values for one sandbox only.
</Card>
<Card title="Named environments" icon="layer-group" href="/environments/named-environments">
Create, rename and delete environments, and pick one for a sandbox.
</Card>
</Columns>
## Related
* [Setup & Scripts](/setup)
* [Platform guide](/platform-guide)
* [Snapshots & Copies](/snapshots)
* [CLI reference](/cli-reference)
# Access and credentials
Source: https://docs.boat.dev/environments/access
Choose what of yours a sandbox receives: GitHub access, secrets, Boat credentials and agent logins.
## Safe for third parties
One switch sets the security of an environment.
<CardGroup>
<Card title="On" icon="shield-check">
Use it for sandboxes that other people use, for example your own end users. **Boat passes nothing of yours.** The sandbox gets no GitHub access, no secrets, and no sandbox or Agents credentials. This is true whatever the section toggles say. The sandbox is confined to itself. It cannot act on your account or your other sandboxes.
</Card>
<Card title="Off" icon="user">
Use it for sandboxes that only you use. The four section toggles below apply. You choose exactly what goes in.
</Card>
</CardGroup>
<CodeGroup>
```bash CLI theme={null}
boat env set base --safe-for-third-parties true
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"safeForThirdParties":true}'
```
```ts TypeScript theme={null}
await sandbox.updateEnvironment({
environmentId: envId,
safeForThirdParties: true,
});
```
```python Python theme={null}
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(safe_for_third_parties=True))
```
</CodeGroup>
### The `--no-env` flag
The `--no-env` flag (`noEnv` in the API) gives the same protection to one sandbox. Boat keeps this flag forever.
* `boat new --no-env` works exactly like a start in an environment that is safe for third parties.
* Use the environment when more than a few sandboxes need this protection.
* The environment setting applies to every sandbox that uses it.
* The environment setting stays through forks and resumes. Your code does not have to pass a flag.
### What a normal sandbox receives
This table shows what a sandbox gets from your account when Boat withholds nothing.
| Type | What Boat passes in |
| - | - |
| Environment variables | Your environment's variables, your GitHub token, and your model credentials if you configured agents (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `CHATGPT_ACCOUNT_ID`), plus neutral Boat-internal vars (`BOAT_ID`, a machine-scoped `ASCII_TOKEN`) |
| Credential files | Your secret files, the GitHub CLI login (`~/.config/gh/hosts.yml`), git credentials in cloned repos, Claude and Codex logins (`~/.claude/.credentials.json`, `~/.codex/auth.json`), the in-sandbox Boat CLI token (`~/.config/ascii/boat/config.json`), and the shell environment the sandbox exports to SSH sessions |
A protected sandbox receives none of these. It keeps only the neutral Boat-internal vars and the values that you pass with `env`.
### Protect an existing sandbox
A snapshot of a normal sandbox can contain your secrets. To protect a sandbox made from such a snapshot, resume or fork it with `--no-env`:
```bash theme={null}
boat resume <id> --no-env
boat fork <id> --no-env
```
Before the sandbox becomes reachable, Boat removes every owner secret that the snapshot can contain:
* The managed `~/.bashrc` blocks.
* `~/.config/gh/hosts.yml`. Boat also runs a `gh` logout.
* `~/.git-credentials`.
* The `~/.ssh/id_*` private keys.
* The Codex and Claude credential files.
* The in-sandbox Boat CLI token.
* Every secret file that you configured.
Boat keeps `authorized_keys` and `known_hosts`, so you can still reach the sandbox.
Boat does not touch credentials that it did not write. These stay:
* `aws` and `gcloud` credentials.
* `.netrc` and `.npmrc`.
* Docker logins added inside the sandbox.
While the removal runs, SSH and desktop return a `boat_securing` error. Retry the request. This change goes one way only. The sandbox stays protected after it.
<Warning>
Boat removes the Claude and Codex credential files even when the sandbox's own user signed in with a personal account inside the sandbox. Boat cannot tell whose files they are. If they belong to the sandbox's user, back them up first and restore them after.
</Warning>
## The four section toggles
When *Safe for third parties* is off, four separate toggles decide what a sandbox receives. Each toggle is a section in the dashboard. Open a section to edit what is inside it.
| Section | What the sandbox gets | When you turn it off |
| - | - | - |
| GitHub repositories | Your repositories cloned in, plus the GitHub token | `gh` and `git push` stop working |
| Secrets | Your environment variables and secret files | Sandboxes drop them at their next start. Boat keeps what you typed. |
| Boat credentials | A scoped Boat API key, so the sandbox can snapshot, stop and resume itself | The sandbox cannot manage its own lifecycle |
| Agents credentials | The provider keys (Claude, Codex, and others) from the Agents tab | Agents in the sandbox have no login |
<CodeGroup>
```bash CLI theme={null}
boat env set base --github true --secrets true --sandbox-credentials false --agents-credentials true
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"passGithub":true,"passSecrets":true,"passSandboxCredentials":false,"passAgentsCredentials":true}'
```
```ts TypeScript theme={null}
await sandbox.updateEnvironment({
environmentId: envId,
passGithub: true,
passSecrets: true,
passSandboxCredentials: false,
passAgentsCredentials: true,
});
```
```python Python theme={null}
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
pass_github=True,
pass_secrets=True,
pass_sandbox_credentials=False,
pass_agents_credentials=True,
))
```
</CodeGroup>
## AI credentials
Two fields decide which AI credentials the environment's sandboxes get.
| Field | CLI flag | What it does |
| - | - | - |
| `credentialProfileId` | `--credential-profile <name\|id\|default>` | The [credential profile](/ai-credentials#credential-profiles) the sandboxes get. `null` (`default` in the CLI) means the sandbox owner's default profile |
| `proxyAiCredentials` | `--proxy-ai-credentials <true\|false>` | Only with *Safe for third parties* on. The sandboxes still get AI credentials, as [proxy placeholders](/ai-credentials#the-ai-credentials-proxy). Needs the proxy on for the profile owner, else `400 ai_proxy_off` |
<CodeGroup>
```bash CLI theme={null}
boat env set base --credential-profile work
boat env set customers --safe-for-third-parties true --proxy-ai-credentials true
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"credentialProfileId":"work"}'
```
```ts TypeScript theme={null}
await sandbox.updateEnvironment({ environmentId: envId, credentialProfileId: "work" });
```
```python Python theme={null}
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(credential_profile_id="work"))
```
</CodeGroup>
# Named environments
Source: https://docs.boat.dev/environments/named-environments
Create, rename, upgrade and delete environments, and pick the environment for a sandbox.
You can have many environments. Exactly one of them is the default. A sandbox uses the default when you do not name an environment.
## Manage environments
<CodeGroup>
```bash CLI theme={null}
boat env list
boat env info staging
boat env new staging
boat env rename staging prod
boat env default prod
boat env rm staging
boat env upgrade prod
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/environments" -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X POST "$BOAT_API_BASE/environments" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"staging"}'
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"prod","isDefault":true,"safeForThirdParties":true}'
curl -sS -X POST "$BOAT_API_BASE/environments/$ENV_ID/upgrade" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X DELETE "$BOAT_API_BASE/environments/$ENV_ID" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
const { environments } = await sandbox.environments();
const staging = await sandbox.createEnvironment({ name: "staging" });
await sandbox.updateEnvironment({
environmentId: envId,
name: "prod", isDefault: true, safeForThirdParties: true,
});
await sandbox.upgradeEnvironment({ environmentId: envId });
await sandbox.deleteEnvironment({ environmentId: envId });
```
```python Python theme={null}
from boat_sdk.models.create_sandbox_environment_request import CreateSandboxEnvironmentRequest
from boat_sdk.models.update_sandbox_environment_request import UpdateSandboxEnvironmentRequest
envs = sandbox.environments()
staging = sandbox.create_environment(CreateSandboxEnvironmentRequest(name="staging"))
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
name="prod", is_default=True, safe_for_third_parties=True,
))
sandbox.upgrade_environment(env_id)
sandbox.delete_environment(env_id)
```
</CodeGroup>
* A delete is a soft delete. Sandboxes pinned to its versions keep running. New sandboxes cannot use it.
* `upgradeEnvironment` accepts an optional list of sandbox ids. Use it to upgrade only those sandboxes. Without the list, Boat moves every sandbox of yours that is on an older version. Read [Versions and upgrades](/environments/versions).
## Pick the environment for a sandbox
Pass the environment name when you create, resume or fork a sandbox. Without a name, Boat uses your default.
* Boat rejects an unknown name before it creates or changes anything. A typo costs you nothing.
* Boat never creates an environment by itself.
<CodeGroup>
```bash CLI theme={null}
boat new --environment staging
boat resume bx_f7k2q9hd --environment staging
boat fork bx_f7k2q9hd --environment staging
```
```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":3600,"environment":"staging"}'
```
```ts TypeScript theme={null}
await sandbox.create({ ttlSeconds: 3600, environment: "staging" });
await sandbox.resume({ sandboxId, environment: "staging" });
await sandbox.fork({ sandboxId, environment: "staging" });
```
```python Python theme={null}
sandbox.create(CreateSandboxRequest(ttl_seconds=3600, environment="staging"))
sandbox.resume(sandbox_id, ResumeRequest(environment="staging"))
sandbox.fork(sandbox_id, ForkRequest(environment="staging"))
```
</CodeGroup>
<Warning>
`--environment` and `--env` are different flags.
* `--environment staging` picks the environment that the sandbox uses.
* `--env KEY=value` sets one variable on that one sandbox. It adds to what the environment gives.
</Warning>
## Organization environments
An organization has its own shared environments. Add `?org=<org id or name>` to any environment route, or `--org <org>` to any `boat env` command. Only this query parameter selects them: the `X-Boat-Org` header and the active wallet do not, so a call without `org` always works on your own environments.
| Role | Can do |
| - | - |
| Member | List the organization environments and use them for sandboxes |
| Owner or admin | Also create, change and delete them |
A sandbox billed to the organization can name an organization environment. When you have an environment of the same name, yours wins. Name an [organization credential profile](/ai-credentials#organization-profiles) on an organization environment to give the team's sandboxes the team's AI credentials.
<CodeGroup>
```bash CLI theme={null}
boat env list --org acme
boat env new agents --org acme
boat env set agents --org acme --credential-profile team-claude
boat --org acme new --environment agents
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/environments?org=acme" -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID?org=acme" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"credentialProfileId":"team-claude"}'
```
```ts TypeScript theme={null}
const { environments } = await sandbox.environments({ org: "acme" });
await sandbox.updateEnvironment({ environmentId: envId, org: "acme", credentialProfileId: "team-claude" });
await sandbox.create({ org: "acme", environment: "agents" });
```
```python Python theme={null}
envs = sandbox.environments(org="acme")
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(credential_profile_id="team-claude"), org="acme")
sandbox.create(CreateSandboxRequest(org="acme", environment="agents"))
```
</CodeGroup>
# Repositories
Source: https://docs.boat.dev/environments/repositories
Clone GitHub repositories into every new sandbox, and find where they land.
<Note>
Repositories need a GitHub connection on your account. If you signed in with Google or an email code, do these steps:
1. Open [Dashboard > Environment](https://boat.dev/dashboard?tab=environment).
2. Under GitHub repositories, click **Connect GitHub**.
This adds GitHub to the account that you already have. You keep the same way to sign in. Nothing else in Boat needs this connection. You can also skip it and use `gh` with your own token inside the sandbox.
</Note>
## Add or remove a repository
Each repository has a base branch and an optional setup script.
* Boat clones the base branch as it is.
* Boat never creates a branch for you, also not for forks.
* A repository stays on the base branch until you, or something inside the sandbox, changes it.
<CodeGroup>
```bash CLI theme={null}
boat env add-repo base octocat/hello-world --branch develop
boat env rm-repo base octocat/hello-world
```
```bash curl theme={null}
repo_id=$(curl -sS "$BOAT_API_BASE/repos?sync=true&q=hello-world" \
-H "Authorization: Bearer $BOAT_API_KEY" \
| jq -r '.installations[0].repositories[0].databaseId')
curl -sS -X POST "$BOAT_API_BASE/repos" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"repositoryId\":\"$repo_id\",\"baseBranch\":\"develop\"}"
```
```ts TypeScript theme={null}
const repos = await sandbox.repos({ sync: true, q: "hello-world" });
const repo = repos.installations.flatMap((i) => i.repositories)[0];
await sandbox.selectRepo({ repositoryId: repo.databaseId, baseBranch: "develop" });
```
```python Python theme={null}
from boat_sdk.models.repo_selection_request import RepoSelectionRequest
repos = sandbox.repos(sync=True, q="hello-world")
repo = repos.installations[0].repositories[0]
sandbox.select_repo(RepoSelectionRequest(repository_id=repo.database_id, base_branch="develop"))
```
</CodeGroup>
<Note>
`selectRepo` and `updateSecrets` change your **default** environment. To edit a named environment, use the calls in [Named environments](/environments/named-environments).
</Note>
## Where repositories land
On the hosted image, the SSH user is `user` and the work directory is `/home/user`. Each folder has the name of the repository, not the `owner/name` pair.
| GitHub repository | Boat path |
| - | - |
| `ariana-dot-dev/ariana-ide-private` | `/home/user/ariana-ide-private` |
| `octocat/hello-world` | `/home/user/hello-world` |
| Number of repositories | Project directory for agent tools |
| - | - |
| One | The repository folder |
| Several | `/home/user` is the parent workspace. Each repository is a folder next to the others. |
# Secrets
Source: https://docs.boat.dev/environments/secrets
Give sandboxes environment variables and secret files, for all sandboxes or for one sandbox only.
Boat injects two types of secret when a sandbox starts.
| Type | Inside the sandbox |
| - | - |
| Environment variables | Process env vars and shell exports |
| Secret files | Files under `/home/user`, at the relative path that you give |
Use secrets for app credentials, API keys, `.env` files and deployment tokens.
Do not put secrets in these places:
* Prompts.
* URLs.
* CLI arguments that can go into logs.
* Docker build args.
* Committed files.
## Set secrets
<CodeGroup>
```bash CLI theme={null}
boat env set-var base STRIPE_KEY=sk_live_123
boat env rm-var base STRIPE_KEY
boat env set-file base backend/.env --from ./local.env
cat ./local.env | boat env set-file base backend/.env
boat env rm-file base backend/.env
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/secrets" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"envContents":"STRIPE_KEY=sk_live_123\n","secretFiles":[{"path":"backend/.env","contents":"DATABASE_URL=postgres://...\n"}]}'
```
```ts TypeScript theme={null}
// default environment
await sandbox.updateSecrets({
envContents: "STRIPE_KEY=sk_live_123\n",
secretFiles: [
{ path: "backend/.env", contents: "DATABASE_URL=postgres://...\n" },
],
});
// any named environment
await sandbox.updateEnvironment({
environmentId: envId,
envContents: "STRIPE_KEY=sk_live_123\n",
secretFiles: [{ path: "backend/.env", contents: "DATABASE_URL=postgres://...\n" }],
});
```
```python Python theme={null}
from boat_sdk.models.secret_file import SecretFile
from boat_sdk.models.secrets_update_request import SecretsUpdateRequest
# default environment
sandbox.update_secrets(SecretsUpdateRequest(
env_contents="STRIPE_KEY=sk_live_123\n",
secret_files=[SecretFile(path="backend/.env", contents="DATABASE_URL=postgres://...\n")],
))
# any named environment
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
env_contents="STRIPE_KEY=sk_live_123\n",
secret_files=[SecretFile(path="backend/.env", contents="DATABASE_URL=postgres://...\n")],
))
```
</CodeGroup>
<Warning>
The `/secrets` endpoint **replaces** all secrets. It does not merge. Send every variable and secret file that you want to keep. Boat drops the ones that you leave out. The `boat env set-var` and `set-file` commands change one item at a time, so they do not have this risk.
</Warning>
## Secret file paths
Paths are relative to `/home/user`. There is no repository picker. To put a file inside a clone, start the path with the repository folder name.
This path:
```text theme={null}
ariana-ide-private/backend/.env
```
writes to:
```bash theme={null}
/home/user/ariana-ide-private/backend/.env
```
Boat skips absolute paths and paths that go outside `/home/user`.
## Variables for one sandbox
The variables of an environment apply to every sandbox that uses it. To give one sandbox its own values, pass `env` when you create it.
Boat merges the per-sandbox values over the environment's values. If the two have the same key, the per-sandbox value wins.
<CodeGroup>
```bash CLI theme={null}
boat new --env DATABASE_URL=postgres://... --env FEATURE_FLAG=1
```
```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":3600,"env":{"DATABASE_URL":"postgres://...","FEATURE_FLAG":"1"}}'
```
```ts TypeScript theme={null}
await sandbox.create({
ttlSeconds: 3600,
env: { DATABASE_URL: "postgres://...", FEATURE_FLAG: "1" },
});
```
```python Python theme={null}
sandbox.create(CreateSandboxRequest(
ttl_seconds=3600,
env={"DATABASE_URL": "postgres://...", "FEATURE_FLAG": "1"},
))
```
</CodeGroup>
| Rule | Limit |
| - | - |
| Key format | `[A-Za-z_][A-Za-z0-9_]*` |
| Key length | 128 characters maximum |
| Variables per sandbox | 100 maximum |
| Total size per sandbox | 64KB maximum |
| Reserved Boat-internal names (`ASCII_TOKEN`, `BOAT_ID`, and similar) | Rejected |
A fork gets the per-sandbox variables of its source sandbox. If the fork passes its own `env`, it does not get them.
# Versions and upgrades
Source: https://docs.boat.dev/environments/versions
Each saved change makes a new environment version. A sandbox moves to it only when you upgrade.
Each time you save a change to an environment, Boat makes a new version.
```
you save a change ──▶ a new version is created
│
├──▶ every sandbox that starts from now on gets it
│
└──▶ Sandboxes already running: nothing happens
│
└──▶ they move only when you upgrade
```
## Which version a sandbox uses
* A sandbox takes the latest version **at the moment it starts**.
* The sandbox keeps that exact version for the rest of its life.
* A save never changes a running sandbox.
* There is no automatic upgrade, no background rollout and no scheduled window.
* A sandbox moves only when you click **Upgrade** in the dashboard or run `boat env upgrade`.
## Find the version of a sandbox
1. Run `boat info <id>`. It shows the version as `environment` and `environmentVersion`.
2. Run `boat env list`. It shows the latest version of each environment.
3. Compare the two numbers. A sandbox below the latest still runs the older configuration.
This is the usual answer to "I added that secret. Why does my sandbox not have it?"
```bash theme={null}
boat info bx_f7k2q9hd # env: prod (v2)
boat env list # prod latest v3 -> this sandbox is one upgrade behind
```
## Upgrade
An upgrade applies the new configuration. It also removes every secret that the new version withholds.
| Sandbox state | When the upgrade applies |
| - | - |
| Live | Immediately. Boat cleans and updates it. |
| Stopped | When it resumes |
<Warning>
You cannot undo an upgrade on the disk of that sandbox. Boat deletes a withheld secret from the machine. It does not hide it. If you pin the sandbox to the older version again, a secret file that the newer version dropped does not come back.
</Warning>
The Versions panel lists every version and the number of sandboxes on each. Use it to find sandboxes that still run an old configuration.
To upgrade only some sandboxes, give `upgradeEnvironment` an optional list of sandbox ids. Without the list, Boat moves every sandbox of yours that is on an older version. For the commands, read [Named environments](/environments/named-environments).
# FAQ
Source: https://docs.boat.dev/faq
Short answers on accounts, regions, billing, snapshots, lifecycle, and running a platform on Boat.
<video />
## Accounts and sign-in
<AccordionGroup>
<Accordion title="Do I need a GitHub account?">
No. You can sign in with GitHub, Google, or a 6-digit code that we email to you. This works on the CLI and on the dashboard. You need GitHub only to clone your repositories into a sandbox. You can connect GitHub later. This does not change how you sign in. Read [Sign-in methods](/account#sign-in-methods).
</Accordion>
<Accordion title="I signed in with Google and my sandboxes are gone.">
You are on a second account. A sign-in method creates a new account, unless it is already connected to an existing account. A matching email does not change this.
1. Sign in again with the method that you used first.
2. Add the other method from [Dashboard > Account](https://boat.dev/dashboard?tab=account).
Only support can merge two accounts that already exist. If this happened to you, [contact us](/support).
</Accordion>
<Accordion title="How do I change the email address Boat writes to?">
Boat sends account notifications to the connection that is marked primary.
1. Connect the address that you want.
2. Make it primary from [Dashboard > Account](https://boat.dev/dashboard?tab=account).
You cannot remove your primary connection. You cannot remove your last connection.
</Accordion>
</AccordionGroup>
## Regions and trust
<AccordionGroup>
<Accordion title="Where do sandboxes run?">
In the EU: Germany, Finland and France. Your data and snapshots stay there. The [Privacy Policy](https://boat.dev/privacy) tells how we handle account data.
</Accordion>
<Accordion title="Is EU latency a problem from the US or Latin America?">
Round trips take about 100 to 200 ms. Agent work runs for minutes, so you do not notice this in practice. For production traffic from end users, publish builds to a CDN or a regional host. Keep Boat for the agent and the dev preview. Read [Build a Platform on Boat](/platform-guide).
</Accordion>
<Accordion title="Do you have compliance certifications?">
Not yet. SOC 2 is in progress. Sandboxes are full VMs with sudo. You can add any controls that you need inside them, such as firewall rules, proxies or encryption.
</Accordion>
</AccordionGroup>
## Billing
<AccordionGroup>
<Accordion title="Am I billed when a sandbox is stopped?">
No. Stopped sandboxes are free. Boat keeps their snapshot for the life of the sandbox.
</Accordion>
<Accordion title="What do snapshots, IP addresses, and egress cost?">
Nothing extra. Read [Pricing](/pricing).
| Item | Included |
| - | - |
| Snapshot | Boat keeps the latest snapshot per sandbox, up to the [data size](/machines#machine-types) of your sandbox type. |
| IP address | Every sandbox has a dedicated IPv6 or IPv4. |
| Egress | Up to 2 TB per sandbox per month. |
</Accordion>
<Accordion title="Do unused credits expire?">
Plan time resets every month. Credit packs that you buy never expire.
</Accordion>
<Accordion title="How much has one sandbox cost me?">
Run `boat usage <id>`, or call `GET /sandboxes/{sandboxId}/usage`. You get the machine time and list-price cost of one sandbox. You can read it over the life of the sandbox or over a billing window, while it runs or after it stops. It is the same meter that your balance uses. Platforms use it to bill their own users per sandbox. Read [Per-sandbox usage](/billing#per-sandbox-usage).
</Accordion>
</AccordionGroup>
## Lifecycle
<AccordionGroup>
<Accordion title="How do I get rid of a sandbox?">
In almost all cases, use `boat stop`. It takes a snapshot, it is free and you can reverse it. You can resume at any time, also months later. Stopped sandboxes cost nothing, so you rarely need to delete one.
To remove a sandbox fully, run `boat delete <id>`, or pick Delete in the dashboard `⋯` menu. This force-stops the sandbox and **permanently deletes its snapshots**. You cannot resume or fork it after this. There is no undo. Use it only when you are sure that the data has no value.
Boat keeps two things:
* Snapshot data that another sandbox still uses because it forked or resumed from this one.
* Named snapshots saved from this sandbox.
Read [Snapshots](/snapshots/download-and-delete#delete-a-sandbox).
</Accordion>
<Accordion title="Why does a sandbox sometimes come back up instead of stopping?">
A stop saves the disk first. If the sandbox has no successful snapshot in the last 30 minutes, Boat takes one to prove that snapshots work. If that snapshot fails, Boat keeps the sandbox running. It does not throw away your work.
You do not pay for that time. The meter pauses by itself from the first failed attempt, so you have nothing to claim. If this continues, snapshots fail on that sandbox. [Contact us](/support). Read [When a stop is refused](/snapshots/stop#when-a-stop-is-refused).
</Accordion>
<Accordion title="How fast are resume and fork?">
A few seconds, whatever the sandbox holds. Files stream in the background for the first moments after you get access. If you read a file that has not arrived yet, the read waits until it arrives. It never returns wrong data.
Wait for state `ready` or `idle` before you run commands. Commands that you send earlier run before Boat applies your environment variables.
</Accordion>
<Accordion title="Do processes survive stop and resume?">
| Item | After resume |
| - | - |
| Files, installed packages, enabled systemd services | Come back. |
| Processes that you started by hand | Do not come back. Start them again or [make them a systemd service](/long-running-tasks/always-on-services#run-an-always-on-service). |
| Docker containers, their images and named volumes | Come back. |
| Docker build cache | Does not come back. Read [Docker builds across resume and fork](/snapshots/whats-saved#docker-builds). |
</Accordion>
</AccordionGroup>
## Running a platform
<AccordionGroup>
<Accordion title="One sandbox per user, per project, or per session?">
[Build a Platform on Boat](/platform-guide) compares the three patterns and their costs.
</Accordion>
<Accordion title="How long should I leave a user's sandbox running before stopping it?">
Boat has no idle timer. The auto-stop TTL counts from creation or resume. It never counts from the last activity.
1. Run your own countdown.
2. Call `boat stop` between a few seconds and about two minutes after the agent finishes.
Resume takes seconds. So a short countdown cuts cost and has little effect on the user experience. Plan for the resumes: each resume counts against your machine start limits, the same as a create.
</Accordion>
<Accordion title="What counts as a machine start, and what are the limits?">
Create, fork and resume each count as one machine start.
* Your plan sets a per-minute burst rate.
* Hour and day limits on top of it control sustained starts.
The table on [Pricing](/pricing#concurrency) gives the numbers for every plan. These limits go up as we add capacity. We can raise them more for committed accounts. If you need more, [contact us](/support).
</Accordion>
<Accordion title="How do I handle launch spikes?">
1. Prepare a template sandbox.
2. Run `boat fork` on it for each user. Do not install from zero each time.
3. Make sure that your start limits cover the peak.
Read [Template Sandboxes](/snapshots/templates).
</Accordion>
<Accordion title="Do prepared templates actually reduce billed time?">
Yes. A fork gets the full filesystem in seconds. You never pay for the same install again.
</Accordion>
<Accordion title="Is Boat good for sustained heavy compute?">
Sandboxes have shared vCPUs. They are best for agent work that is IO-heavy and comes in bursts. If a workload needs more room, `boat new --type large` gives two times the CPU and memory of a `default` sandbox. For multi-hour loads at 100% CPU, or GPU loads, dedicated compute is a better fit.
</Accordion>
<Accordion title="Can I resize a sandbox?">
Yes. Pass `--type` to `resume` or `fork`. This moves a sandbox between `small`, `default` and `large`.
* A larger size always works.
* A smaller size fails if the sandbox holds more data than the smaller machine takes. The sandbox then stays exactly as it was.
Read [Machine Capabilities](/machines).
</Accordion>
</AccordionGroup>
# Host with Boat
Source: https://docs.boat.dev/hosting
Run a service inside a sandbox and expose it on a stable public HTTPS URL.
<video />
Run a service in your sandbox. Boat gives it a stable public HTTPS URL.
## Quick path
<Steps>
<Step title="Open the sandbox">
Connect to the sandbox with SSH. In an integration, use the command endpoint to run the same setup in the sandbox.
<CodeGroup>
```bash CLI theme={null}
boat ssh bx_f7k2q9hd
npm run dev -- --host 0.0.0.0 --port 3000
```
```bash curl theme={null}
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"}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: "npm run dev -- --host 0.0.0.0 --port 3000", cwd: "my-repo",
});
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(
command="npm run dev -- --host 0.0.0.0 --port 3000",
cwd="my-repo",
))
```
</CodeGroup>
</Step>
<Step title="Start your app on an explicit port">
<Info>
Tell `host` where your app listens. An app on `0.0.0.0` needs no flag. An app on `localhost`, `127.0.0.1` or `::1` needs `--localhost` (`"localhost": true` in the API). See [Services that listen on localhost](/hosting/how-it-works#services-that-listen-on-localhost).
</Info>
To keep the process alive after your SSH command exits, start it as a detached process before you host the port.
</Step>
<Step title="Host the port">
In the sandbox, run `host`. An integration can run the same command in the sandbox.
<CodeGroup>
```bash CLI theme={null}
host 3000 --title "App preview"
```
```bash curl theme={null}
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\""}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: 'host 3000 --title "App preview"',
});
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(command='host 3000 --title "App preview"'))
```
</CodeGroup>
</Step>
<Step title="Open the URL">
Open the public HTTPS URL that `host` prints.
```text theme={null}
https://<sandbox-subdomain>-3000.on.boat.dev
```
For a protected port, the URL includes a `_token` query parameter.
```text theme={null}
https://<sandbox-subdomain>-3000.on.boat.dev?_token=<access-token>
```
</Step>
</Steps>
<Info>
A new `host <port>` URL is protected by default and includes `_token`. Pass `--public` only to clear the access token and get an ungated URL.
</Info>
## Facts
| Fact | Value |
| - | - |
| URL format | `https://<sandbox-subdomain>-<port>.on.boat.dev` |
| Ports per sandbox | Up to 50 |
| Default access | Protected, with `_token` |
| Address your app listens on | `0.0.0.0`, or `localhost` with `--localhost` |
| Host from your computer | `boat host <sandbox-id> <port>` |
| Host from inside the sandbox | `host <port>` |
## Learn more
<Columns>
<Card title="Host CLI reference" icon="terminal" href="/hosting/host-cli">
`boat host`, `host`, `host list`, `host url` and `host hide`, with all options.
</Card>
<Card title="How HTTPS hosting works" icon="globe" href="/hosting/how-it-works">
How Boat routes a request to your sandbox, and the `on.ascii.dev` domain.
</Card>
<Card title="Firewall rules" icon="shield" href="/hosting/firewall">
Add firewall rules in a sandbox without breaking Boat.
</Card>
</Columns>
## Related
* [SSH Access](/ssh-access)
* [Environments](/environments)
* [Long-Running Tasks](/long-running-tasks)
* [Desktop Streaming](/desktop-streaming)
# Firewall rules inside a sandbox
Source: https://docs.boat.dev/hosting/firewall
Add firewall rules in a sandbox without blocking Boat's agent or tunnel.
You have root, so you can add any firewall rule. Boat reaches the sandbox in two ways. 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 |
## Block outgoing UDP for `user`
Linux tags a tunnel packet with the process that sent the data inside it. So an owner rule on `user` also blocks the tunnel.
To block outgoing UDP for `user` and keep Boat working, allow the tunnel endpoint first.
```bash theme={null}
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
```
## What happens to a blocked sandbox
Boat never stops a sandbox for this, or marks it `error`, if it answers on any route. Instead:
* The sandbox shows `"health": "degraded"` with a reason.
* Boat sends a [`sandbox.degraded`](/webhooks#events) webhook.
# Host CLI reference
Source: https://docs.boat.dev/hosting/host-cli
Expose, list, print and hide hosted ports with `boat host` and the in-sandbox `host` CLI.
Two commands expose a service from a sandbox on a public HTTPS URL.
| Command | Runs on |
| - | - |
| `boat host` | Your local computer |
| `host` | Inside the sandbox |
<Info>
A service on `0.0.0.0` needs no flag. For a service that listens only on `localhost`, `127.0.0.1` or `::1`, pass `--localhost`. See [Services that listen on localhost](/hosting/how-it-works#services-that-listen-on-localhost).
</Info>
## `boat host <sandbox-id> <port>`
Expose a running service without an interactive SSH session:
```bash theme={null}
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
boat host bx_f7k2q9hd 5173 --localhost
```
The command does these steps:
1. It opens the firewall for that port.
2. It registers an HTTPS subdomain.
3. It prints the URL.
If you run it again for the same sandbox and port, you get 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`. |
| `--localhost` | The service listens on localhost only. The sandbox relays the URL to it. |
Use `--json` to print a machine-readable object with `sandboxId`, `port`, `url`, `access`, `isProtected` and `localhost`.
It is a single API call. This makes it the fastest way to host a port from a script:
```bash theme={null}
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"}'
```
For an ungated URL, pass `{"public":true}`. For a service that listens on localhost only, pass `{"localhost":true}`.
```ts TypeScript theme={null}
await sandbox.hostPort({ sandboxId: "bx_f7k2q9hd", port: 5173, localhost: true });
```
## In-sandbox `host <port>`
Expose a running service on a stable HTTPS URL:
<CodeGroup>
```bash CLI theme={null}
host 3000
host 3000 --title "Login preview"
host 3000 --private
host 3000 --public
host 5173 --localhost
```
```bash curl theme={null}
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\""}'
```
```ts TypeScript theme={null}
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" });
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host 5173 --localhost" });
```
```python Python theme={null}
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"))
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host 5173 --localhost"))
```
</CodeGroup>
The command does these steps:
1. It opens the firewall for that port.
2. It registers an HTTPS subdomain.
3. It prints the URL.
If you run it again for the same port, you get the same URL. A sandbox can host up to 50 ports.
| 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`. |
| `--localhost` | The service listens on localhost only. The sandbox relays the URL to it. `host url` takes it too. |
By default, `host <port>` creates a protected URL with a `_token` query parameter. This protection stays. If you host the same port again, the URL has the same `_token`, unless you pass `--public`.
For raw access without HTTPS or a subdomain, open the port yourself with `ufw`. Then use `http://<sandbox-ip>:<port>` directly.
## `host list`
Show the hosted ports of the current sandbox:
<CodeGroup>
```bash CLI theme={null}
host list
```
```bash curl theme={null}
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"}'
```
```ts TypeScript theme={null}
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host list" });
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host list"))
```
</CodeGroup>
* `host list` shows protected ports as `(gated)`.
* `host list` shows relayed ports as `(localhost)`.
* `host list` does not print the access token.
* To print the full URL with `_token=...`, use `host url <port>`.
## `host url <port>`
Wait until the HTTPS URL is ready, then print it:
<CodeGroup>
```bash CLI theme={null}
host url 3001
host url 3001 --public
```
```bash curl theme={null}
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"}'
```
```ts TypeScript theme={null}
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001" });
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001 --public" });
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001 --public"))
```
</CodeGroup>
For a protected port, it prints the full token-gated URL:
```text theme={null}
https://<sandbox-subdomain>-3001.on.boat.dev?_token=<access-token>
```
Use it when one service needs the public URL of another service:
<CodeGroup>
```bash CLI theme={null}
BACKEND_URL=$(host url 3001)
```
```bash curl theme={null}
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')
```
```ts TypeScript theme={null}
const result = await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host url 3001" });
const backendUrl = result.stdout.trim();
```
```python Python theme={null}
result = sandbox.command("bx_f7k2q9hd", CommandRequest(command="host url 3001"))
backend_url = result.stdout.strip()
```
</CodeGroup>
## `host hide <port>`
Take down the public URL:
<CodeGroup>
```bash CLI theme={null}
host hide 3000
```
```bash curl theme={null}
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"}'
```
```ts TypeScript theme={null}
await sandbox.command({ sandboxId: "bx_f7k2q9hd", command: "host hide 3000" });
```
```python Python theme={null}
sandbox.command("bx_f7k2q9hd", CommandRequest(command="host hide 3000"))
```
</CodeGroup>
* It closes public access, unregisters the HTTPS route and turns off the localhost relay.
* It does not stop the local server process. Stop the server yourself when you are done.
* It keeps the access tokens. If you host the same port again, existing protected links stay valid.
To get an ungated URL after a port became protected, run `host <port> --public`.
# How HTTPS hosting works
Source: https://docs.boat.dev/hosting/how-it-works
How Boat routes a public HTTPS request to a port in your sandbox.
## 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.
```text theme={null}
https://<sandbox-subdomain>-<port>.on.boat.dev
```
## 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`:
```text theme={null}
browser -> route -> sandbox address:<port> -> Boat relay -> 127.0.0.1:<port> or [::1]:<port>
```
* 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.
* Each relayed port has its own small relay process. `lsof -ti :<port> | xargs kill -9` or `npx kill-port <port>` kills that relay too. The rest of the sandbox keeps working, and the relay starts again in about one second.
* 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.
```bash theme={null}
npm run dev -- --port 5173 # Vite listens on localhost by default
host 5173 --localhost
```
<Note>
Some dev servers reject requests for host names they do not know. For Vite, add `.on.boat.dev` to `server.allowedHosts`.
</Note>
## 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
<Note>
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](/migrating-from-box)). Change the links that you publish to `on.boat.dev` when convenient.
</Note>
# Integrated agents
Source: https://docs.boat.dev/integrated-agents
Boat runs coding-agent harnesses for you: the boilerplate you would otherwise build on a bare cloud computer, with every part open to customize or replace.
<video />
Every sandbox has seven coding-agent harnesses, installed and ready: **Claude Code, Codex, pi, OpenCode, Prime Agent, Kimi Code, and Mistral Vibe**. Run `boat prompt` to give one of them a task. Boat then does these things for you:
* It streams back what the agent does.
* It keeps the memory of the agent.
* It runs many tasks at the same time.
* It keeps the tasks when the sandbox stops and resumes.
* It lets you change the model or the harness during a task.
Nothing here is hidden. It is the code you would write if you put an agent on a bare cloud computer. This page shows that code, how Boat does it, and where you add your own instructions, tools, keys or harness.
## What Boat builds for you
| You would have to build | Boat does it with |
| - | - |
| Install the harness, keep it updated | Seven harnesses, installed and updated on every sandbox |
| Give it API keys, or the keys of your user | Your keys from the [Agents dashboard](https://boat.dev/dashboard?tab=agents), or per-sandbox keys with `boat new -e`. Read [Keys and subscriptions](/integrated-agents/keys) |
| Start the harness with a prompt in the right directory | `boat prompt "…"` / `POST /prompt`. It runs in `/home/user` |
| Capture stdout, parse tool calls, stream them to your UI | `boat events` / `GET /events`: structured prompt, response, and tool-call events |
| Keep the session id, so the next prompt continues the thread | A **conversation**. Boat keeps the history and the harness session |
| Run two tasks at once without a session collision | Many parallel conversations per sandbox, each with its own harness process |
| Send SIGINT to the right process | `boat interrupt --convo <id>` |
| Type to the agent while it works, for each harness | `boat steer "…"` / `POST /steer`. Read [Steer a running turn](/integrated-agents/steering) |
| Save sessions to disk, so a reboot loses nothing | Conversations survive `boat stop`, `boat resume`, `boat fork` |
| Let the user pick a model or a thinking level | `--model`, `--reasoning-effort` and `--fast` on every prompt |
| Let the user pick a harness, and keep the context when they change it | `--provider` on every prompt. The conversation history carries across |
| Add house rules, MCP servers, skills, tools | Ordinary harness config files in the sandbox home. Read [Customize the harness](/integrated-agents/customize) |
| Attach a screenshot or a file | `boat prompt --attach` |
| Let the agent see and use a real screen | The `computer` tools, on every harness. Read [Computer use](/integrated-agents/computer-use) |
You can still do each of these by hand. Boat never stops you. Run `boat ssh` and run what you want. Read [Bring your own harness](/integrated-agents/customize#bring-your-own-harness).
## How it fits together
```mermaid theme={null}
flowchart LR
You["You: CLI, API, SDK"]
subgraph Backend["Boat backend"]
Q["Queue prompts<br/>pick harness + model"]
E["Collect events"]
end
subgraph Boat["Your Sandbox"]
AS["Agent server<br/>(always on)"]
A["Conversation A<br/>claude process"]
B["Conversation B<br/>pi process"]
C["Conversation C<br/>codex process"]
D[("/home/user<br/>files, config, sessions")]
end
You -- "boat prompt" --> Q --> AS
AS --> A & B & C
A & B & C --> D
AS -- "events" --> E -- "boat events" --> You
```
* Every sandbox runs a small agent server. It is always on.
* Each **conversation** has one harness process and one history.
* The harnesses are ordinary processes. They run as `user` in `/home/user`.
* They read ordinary config files and credentials. So you can look at all of it and replace all of it.
## Learn more
<Columns>
<Card title="Harnesses and models" icon="robot" href="/integrated-agents/harnesses-and-models">
The seven harnesses, their models, the live model catalog, and fast mode.
</Card>
<Card title="Keys and subscriptions" icon="key" href="/integrated-agents/keys">
Your keys or the keys of your users. Subscriptions, DeepSeek, Amazon Bedrock and Mistral.
</Card>
<Card title="Conversations" icon="comments" href="/integrated-agents/conversations">
Agent memory, parallel conversations, the prompt lifecycle, and a change of harness.
</Card>
<Card title="Steer a running turn" icon="hand-pointer" href="/integrated-agents/steering">
Send a new message to an agent while it works, without a stop.
</Card>
<Card title="Computer use" icon="desktop" href="/integrated-agents/computer-use">
The agent sees and uses the sandbox desktop. Tools, config files and checks.
</Card>
<Card title="Customize the harness" icon="sliders" href="/integrated-agents/customize">
House rules, MCP servers, skills, tools, and your own harness.
</Card>
</Columns>
## Reference
* CLI flags: [`boat prompt`](/cli-reference#boat-prompt-id), [`boat conversations`](/cli-reference#boat-conversations-id), [`boat steer`](/cli-reference#boat-steer-id-message), `boat events --convo`, `boat interrupt --convo`
* API: [Prompt](/api/reference/agent/prompt-sandbox-agent), [Conversations](/api/reference/agent/list-sandbox-conversations), [Events](/api/reference/agent/list-sandbox-events), [Steer](/api/reference/agent/steer-a-running-turn), [Interrupt](/api/reference/agent/interrupt-running-agent-work), with the same `new`, `conversationId`, and `conversation` fields
* SDKs: [Python](/sdks/python), [TypeScript](/sdks/typescript)
* Build a product on top: [SDKs](/sdks/overview), [Platform Guide](/platform-guide)
# Computer use
Source: https://docs.boat.dev/integrated-agents/computer-use
Every harness on a sandbox can see and use the Linux desktop of the sandbox through the built-in computer tools.
Every sandbox runs a Linux desktop. Every harness on it can see and use that desktop with ordinary tools. You do not install or register anything:
```bash theme={null}
boat prompt "Open example.com in the browser and tell me the page title"
boat prompt --provider codex "Log into the admin app in Chrome and screenshot the dashboard"
```
The tools come from the [Cua Driver](https://github.com/trycua/cua). It is preinstalled on every sandbox. It is registered as an MCP server named `computer` for all seven harnesses:
```mermaid theme={null}
flowchart LR
P["boat prompt"] --> H["Harness process<br/>claude / codex / pi / opencode / prime / kimi / vibe"]
H -- "stdio MCP<br/>server name: computer" --> M["cua-driver mcp"]
M -- "unix socket" --> D["cua-driver daemon<br/>systemd user service"]
D --> X["The Sandbox desktop<br/>Xorg :0, 1920x1080, Chrome"]
X -.-> S["boat desktop<br/>watch it live"]
```
The daemon runs as the desktop user. So the tools act on the same screen that `boat desktop` streams. Open a stream in one window and watch the agent work in it.
## What the agent gets
| Group | Tools |
| - | - |
| Look | `get_window_state` (screenshot plus the accessibility tree in one call), `get_desktop_state`, `get_screen_size`, `list_windows`, `list_apps` |
| Point and type | `click`, `double_click`, `right_click`, `drag`, `scroll`, `move_cursor`, `type_text`, `press_key`, `hotkey`, `set_value` |
| Apps and windows | `launch_app`, `kill_app`, `bring_to_front`, `set_window_frame`, `invoke_menu` |
| Browser | `browser_navigate`, `browser_click`, `browser_type`, `get_browser_state`, `browser_download` |
| Clipboard | `clipboard_read`, `clipboard_write` |
By default, the tools send clicks and keystrokes in the background. They go to the target window, but they do not raise it or move the real pointer. So the agent can use several windows without a fight for focus.
Some widgets accept input only when they have focus. In that case the tool says so. The agent can then try again with `delivery_mode: "foreground"`. This activates the window, does the action, and gives focus back.
In `boat events`, each harness shows the tool names with its own prefix:
| Harness | Example tool name |
| - | - |
| Claude Code, Kimi Code | `mcp__computer__click` |
| Codex | `mcp:computer/click` |
## Where it is registered
The registration is an ordinary entry in the config file of each harness. Boat writes it at sandbox start, and merges it with what you put there yourself:
| Harness | File | Entry |
| - | - | - |
| Claude Code | `~/.claude.json` | `mcpServers.computer` |
| Codex | `~/.codex/config.toml` | `[mcp_servers.computer]`, in a marked block |
| pi | `~/.pi/agent/mcp.json` | `mcpServers.computer` |
| OpenCode | `~/.config/opencode/opencode.json` | `mcp.computer` |
| Prime Agent | `~/.prime/agent/settings.json` | `mcpServers.computer` |
| Kimi Code | `~/.kimi-code/mcp.json` | `mcpServers.computer` |
| Mistral Vibe | none: the agent server passes it when it opens each session | `computer` |
* Boat does not touch your own MCP servers in those files.
* If you remove `computer` from a file, that harness loses the tools.
* Boat writes the entry again at the next sandbox start. To remove the tools for good, delete the daemon from the sandbox.
OpenCode has one tool, `browser_prepare`, turned off in `opencode.json` `tools`. The reason: OpenCode sends MCP tool schemas to the model provider without change, and the Anthropic API rejects the schema of that tool. Without this, every OpenCode turn on an Anthropic model fails.
Prime Agent calls the server from inside its Python tool, as `await mcp.call_tool("computer", "click", {...})`.
## Practical notes
* **One screen, shared.** All conversations on a sandbox use the same desktop. Two agents that click at the same time interfere with each other. Give each parallel GUI task its own sandbox, or run the tasks one after the other.
* **It survives stop, resume and fork.** The daemon is a systemd user service on the sandbox. It starts again automatically. The socket is on `/run`, so a resumed sandbox never gets an old socket.
* **Logins persist.** A Chrome profile that the agent signed into is on the disk of the sandbox. It comes back on resume and goes with a fork.
* **Screenshots are large.** A full-desktop screenshot is a real image in the context of the model. When a task runs in a loop, ask for one window (`get_window_state` with a window id).
* **Watch it, and record it.** Run `boat desktop` to open the stream and watch the agent work. Run `ascii-record-desktop` to record the run to an MP4. Read [Desktop Streaming](/desktop-streaming).
## Check the daemon
If a prompt says that it has no computer tools, check the daemon:
```bash theme={null}
boat exec 'systemctl --user status cua-driver.service --no-pager'
boat exec '/opt/ascii/cua-driver/cua-driver status --socket /run/ascii-cua/driver.sock'
boat exec 'systemctl --user restart cua-driver.service'
```
# Conversations
Source: https://docs.boat.dev/integrated-agents/conversations
How the agent keeps its memory, runs many tasks at once, survives a stop, and changes harness or model in a thread.
A **conversation** is a thread of prompts and responses with its own memory. The native session of the harness holds that memory.
* The first `boat prompt` on a sandbox starts a conversation.
* Every later prompt continues it.
You never have to handle the session id. But you can get it when you want it:
* Every prompt prints its conversation id: `conversation: <id>` under `queued:`.
* `--json` and the API response give it as `conversationId`.
* Every event carries one.
```bash theme={null}
boat prompt "Now add tests" # this shell's current conversation
boat prompt --new "Look into the flaky CI job" # a brand-new conversation
boat prompt --resume <id> "Continue where we left off" # a specific one
boat conversations # every conversation on the sandbox, with ids
```
## List conversations
`boat conversations` (`GET /sandboxes/{id}/conversations`) lists the conversations, newest first. Each row shows:
* the prompt count
* whether a turn is running
* the last harness and model
* a preview of the last prompt
* which one is the current conversation of the sandbox
Use it to get back the id of a thread that you started yesterday, or from another shell. Then pass that id to `--resume`.
## The current conversation is per shell
The current conversation is scoped to your shell, like the `current` sandbox id.
* `--new` makes the new conversation the current one for this shell.
* A bare `boat prompt` continues the current one.
So two shells, two people, or two machines can prompt the same sandbox. Each one keeps its own thread. They do not interfere.
## Parallel conversations
Conversations run at the same time. Each one has its own harness process and its own history:
```mermaid theme={null}
gantt
dateFormat s
axisFormat %S s
section A claude
refactor billing :a1, 0, 40
add tests (waits for A) :a2, after a1, 25
section B pi
fix flaky test :b1, 0, 30
section C codex
write the changelog :c1, 5, 20
```
The rules are the rules you would write yourself:
* **One turn at a time per conversation.** A second prompt to the same conversation waits for the current turn, because it needs the context of that turn. Prompts to different conversations run at the same time.
* **A cap per sandbox** on turns that run at the same time. The cap depends on the memory of the sandbox:
| Size | Turns at the same time |
| - | - |
| `small` | Fewer than `default` |
| `default` (8 GB) | About two dozen |
| `large` | More than `default` |
Above the cap, prompts wait in a queue and start when turns finish. Boat drops nothing. To set an exact number, set the `ASCII_MAX_PARALLEL_CONVERSATIONS` environment variable on the sandbox. Or change the size of the sandbox ([Machine Capabilities](/machines)).
* **List them** with `boat conversations`. Each row shows whether a turn runs in it. So you see the parallel work at a glance.
* **Events stream all conversations by default**, tagged with `conversationId`. To watch one, run `boat events --convo <id>`.
* **Interrupt is scoped.** `boat interrupt --convo <id>` stops one turn. The others keep running. A bare `boat interrupt` stops everything on the sandbox.
* **Steer is scoped too.** `boat steer --convo <id> "..."` changes one running turn without a stop. Read [Steer a running turn](/integrated-agents/steering).
## Agent lifecycle
A prompt moves through a small state machine. Watch it with `boat events` or `GET /prompts/{promptId}`:
```mermaid theme={null}
stateDiagram-v2
[*] --> queued: boat prompt
queued --> running: conversation free and Boat under its cap
running --> running: boat steer (message joins this turn)
running --> finished
running --> interrupted: boat interrupt
running --> failed: harness or credential error (reason in the event)
finished --> [*]
interrupted --> [*]
failed --> [*]
```
A steer never makes a state of its own. The turn that was running is the turn that finishes. The work your message causes is part of that turn.
## Conversations survive a stop
The sandbox lifecycle is under the prompt lifecycle. Conversations move with it:
```mermaid theme={null}
flowchart LR
N["boat new"] --> R["ready"]
R --> P["prompt … prompt"]
P --> S["boat stop<br/>disk snapshot incl. sessions"]
S --> R2["boat resume / boat fork"]
R2 --> P2["boat prompt --resume id<br/>same memory"]
```
* A stop takes a snapshot of the disk. The snapshot includes the history of every conversation and the native session files of the harness under `/home/user`.
* A resumed or forked sandbox gets them back. So `--resume <id>` continues with full memory.
* Conversations and every config file in [Customize the harness](/integrated-agents/customize) survive a stop.
* Processes that the harness started by hand do not survive a stop, the same as on any reboot. A dev server or a tunnel it started are examples.
## Switch harness or model in a conversation
Continue a conversation on a different harness. The new harness keeps the thread:
```mermaid theme={null}
sequenceDiagram
participant You
participant Conv as Conversation A
participant CC as Claude Code
participant Pi as pi
You->>Conv: prompt 1, prompt 2 (--provider claude)
Conv->>CC: turns
You->>Conv: --resume A --provider pi "take it from here"
Conv->>Pi: full earlier transcript + new prompt
Pi-->>You: continues with the whole context
```
```bash theme={null}
boat prompt --resume <A> --provider pi --model claude-sonnet-5 "Take it from here"
```
Boat freezes the transcript of the earlier harness into the conversation. Then it gives that transcript to the new harness. So the change is one flag, not a script that rebuilds the context.
To give your users a selector for harness and model, map it to `provider` and `model` on `POST /prompt`.
# Customize the harness
Source: https://docs.boat.dev/integrated-agents/customize
Add house rules, MCP servers, skills and tools to the harnesses on a sandbox, reach your own app, or bring your own harness.
Every harness reads its own config files from the sandbox home. Boat adds only two things:
* A short system prompt. It tells the harness that it runs headless in a sandbox, and that the `boat` CLI exists.
* The `boat` skill.
You add everything else. Use any of these:
* `boat ssh`, `boat exec` or `boat scp`
* a file that the agent writes
* an [environment setup script](/environments)
* a [named snapshot](/snapshots), so every new sandbox starts with it
We tested each row on this page end to end through `boat prompt`, on the current harness versions. Each row names the file that changed the answer of the harness.
## Instructions and hidden rules
Add a rules file. Every prompt on that sandbox then obeys it, even when the prompt does not mention it:
| Harness | Files read (all applied together) | Not read |
| - | - | - |
| Claude Code | `~/CLAUDE.md`, `~/.claude/CLAUDE.md` | `AGENTS.md` |
| Codex | `~/AGENTS.md`, `~/.codex/AGENTS.md` | `config.toml` `developer_instructions` (Boat sets the base instructions) |
| pi | `~/AGENTS.md`, `~/.pi/agent/AGENTS.md`, `~/.pi/agent/APPEND_SYSTEM.md` | `CLAUDE.md` when an `AGENTS.md` exists |
| OpenCode | `~/AGENTS.md`, `~/.config/opencode/AGENTS.md`, files listed in `opencode.json` `instructions` | |
| Prime Agent | `~/AGENTS.md`, `~/.prime/agent/AGENTS.md`, `~/.prime/agent/APPEND_SYSTEM.md` | |
| Kimi Code | `~/AGENTS.md`, `~/.kimi-code/AGENTS.md`, `~/.agents/AGENTS.md` | `CLAUDE.md` |
| Mistral Vibe | `AGENTS.md` at the root of a git repository it works in, after you trust that folder (`~/.vibe/trusted_folders.toml`) | `~/AGENTS.md`, `CLAUDE.md`. Use a skill for house rules |
* One `~/AGENTS.md` plus one `~/CLAUDE.md` covers every harness except Mistral Vibe.
* `APPEND_SYSTEM.md` (pi, Prime) goes at the end of the system prompt itself, not into the project context.
* When an environment clones a single repository, Claude Code starts inside that repository. So a `CLAUDE.md` there also applies.
```bash theme={null}
boat exec "printf '# House rules\nAlways run the test suite before saying you are done.\n' > ~/AGENTS.md; cp ~/AGENTS.md ~/CLAUDE.md"
```
## MCP servers
| Harness | How to register | Config written |
| - | - | - |
| Claude Code | `claude mcp add --scope user <name> -- <command>` | `~/.claude.json` (project scope: `~/.mcp.json`) |
| Codex | `codex mcp add <name> -- <command>` | `~/.codex/config.toml` `[mcp_servers.<name>]` |
| pi | `pi install npm:pi-mcp-extension`, then `~/.pi/agent/mcp.json` | `{"mcpServers": {"<name>": {"transport": "stdio", "command": …, "lifecycle": "eager"}}}` |
| OpenCode | `~/.config/opencode/opencode.json` | `"mcp": {"<name>": {"type": "local", "command": [...]}}` |
| Prime Agent | `prime-agent mcp add <name> -- <command>` | `~/.prime/agent/settings.json` `mcpServers` |
| Kimi Code | `~/.kimi-code/mcp.json` | `{"mcpServers": {"<name>": {"command": …, "args": [...]}}}` (`{"url": …}` for HTTP) |
| Mistral Vibe | `~/.vibe/config.toml` | `[[mcp_servers]]` with `name`, `transport = "stdio"`, `command`, `args` (`url` for HTTP) |
* Remote (HTTP) servers work the same way, with a URL instead of a command.
* On a sandbox, the MCP resource browsing tools of Claude Code are turned off. MCP tools stay on.
Every sandbox already has one server registered this way: `computer`, in these same files. Your server next to it does not change it, and it never overwrites yours. Read [Computer use](/integrated-agents/computer-use).
## Reach your own app from the sandbox
A sandbox has no route back to your laptop. So the agents in it cannot see an MCP server, a local model, or a webhook receiver on your `localhost`.
`boat forward --reverse` opens that route. A port on your machine then answers at `127.0.0.1:<port>` inside the sandbox. It uses the same SSH session as `boat ssh`. Nothing is public on either end.
```bash theme={null}
# leave this running; your MCP server on localhost:7777 is now in the sandbox
boat forward bx_f7k2q9hd --reverse --local 7777
```
Register it one time inside the sandbox. Then every harness can call it:
```bash theme={null}
boat exec bx_f7k2q9hd "claude mcp add --scope user mine --transport http http://127.0.0.1:7777/mcp"
```
* The registration is in the sandbox home. It survives `boat stop`, `boat resume`, and `boat fork`.
* The tunnel does not survive. Start it again the next time the agent must reach you.
* A local model works the same way. `boat forward <id> --reverse --local 11434` puts Ollama on `http://127.0.0.1:11434` inside the sandbox. Any harness that uses that base URL can call it.
For the flags and the redial behaviour, read [`boat forward --reverse`](/cli-reference#--reverse-reach-your-machine-from-the-sandbox).
Products that do not ship the CLI can open the same tunnel. The CLI only wraps stock OpenSSH:
```bash theme={null}
# 1. authorize your public key on the sandbox; the reply carries machineIp
curl -s -X POST https://boat.dev/api/v1/sandboxes/$BOAT_ID/sshkey \
-H "Authorization: Bearer $BOAT_API_KEY" -H 'Content-Type: application/json' \
-d "{\"key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
# 2. open the reverse tunnel and leave it running
ssh -o ExitOnForwardFailure=yes -i ~/.ssh/id_ed25519 -N -R 7777:127.0.0.1:7777 user@<machineIp>
```
## Skills
A skill is a folder with a `SKILL.md` file. The file has frontmatter with `name` and `description`, then the instructions. Every harness on a sandbox already has a skills directory with the `boat` skill in it. Add yours next to it:
| Harness | Skills directory |
| - | - |
| Claude Code | `~/.claude/skills/<name>/SKILL.md` |
| Codex | `~/.codex/skills/<name>/SKILL.md` |
| pi | `~/.pi/agent/skills/<name>/SKILL.md` |
| OpenCode | `~/.config/opencode/skills/<name>/SKILL.md` |
| Prime Agent | `~/.prime/agent/skills/<name>/SKILL.md` |
| Kimi Code | `~/.kimi-code/skills/<name>/SKILL.md` (also `~/.agents/skills/<name>/SKILL.md`) |
| Mistral Vibe | `~/.vibe/skills/<name>/SKILL.md` (also `~/.agents/skills/<name>/SKILL.md`) |
## Command-line tools
Anything on `PATH` is a tool. To add one, do one of these:
* Put a script in `~/.local/bin` or `/usr/local/bin`.
* Install it with `npm i -g`, `pip install` or `apt install`.
Then ask for it by name. All seven harnesses run it through their shell tool.
## Custom in-process tools and extensions
Use these when a tool must show as a native function call, not a shell command:
| Harness | Mechanism | Path |
| - | - | - |
| pi | extension calling `pi.registerTool({...})` | `~/.pi/agent/extensions/<name>.ts` |
| Prime Agent | same extension API | `~/.prime/agent/extensions/<name>.ts` |
| OpenCode | `tool({description, args, execute})` from `@opencode-ai/plugin` (dependencies install themselves on first run) | `~/.config/opencode/tools/<name>.ts` |
| Claude Code | hooks in `~/.claude/settings.json`, plugins | see [Claude Code docs](https://code.claude.com/docs/en/hooks) |
| Codex | hooks in `~/.codex/hooks.json` | see [Codex docs](https://learn.chatgpt.com/docs/hooks) |
| Kimi Code | `[[hooks]]` in `~/.kimi-code/config.toml`, plugins | see [Kimi Code docs](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html) |
| Mistral Vibe | hooks in `~/.vibe/hooks.toml` | see [Mistral Vibe on GitHub](https://github.com/mistralai/mistral-vibe#hooks) |
## What is shared, what persists
* **Config is per sandbox, not per conversation.** Every parallel conversation on a sandbox reads the same home directory, whatever its harness. There is one `AGENTS.md`, one skills folder, one MCP list. For rules per user, use a sandbox per user, or put the rules in the prompt.
* **Boat captures everything in `/home/user` on stop.** Rules, MCP registrations, skills, extensions, tools you installed under home, and the harness sessions all come back on `boat resume` and `boat fork`. Tools installed outside home (`apt`, `/usr/local`) are also part of the system snapshot.
* **Set it up one time.** An [environment](/environments) setup script or a [named snapshot](/snapshots) gives every new sandbox the same rules, tools and servers from the first prompt.
## Bring your own harness
The built-in harnesses are ordinary binaries on `PATH`. They have the same credentials that the agent server uses. You have three ways to go further than `boat prompt`:
* **Run a built-in harness yourself.** Use `boat ssh` or `boat exec`. Run `claude`, `codex`, `pi`, `opencode`, `prime-agent`, `kimi`, or `vibe` (Mistral Vibe) directly, in any mode they support. The agent server does not lock the files or the processes.
* **Install a harness that Boat does not ship.** Run `boat exec "npm i -g <harness>"`, or add it to an environment or a snapshot. Run it over `boat exec` or SSH. It works next to the built-in harnesses and reads the same per-sandbox `-e` keys.
* **Run your own agent loop.** Put a small HTTP daemon in the sandbox and talk to it directly. The [Platform Guide](/platform-guide/agents#bring-your-own-harness-the-daemon-pattern) shows how. `boat host` gives it a URL. [Webhooks](/webhooks) tell your control plane when the sandbox is up.
Whatever you run, these keep working: `boat events`, attachments under `~/attachments`, [desktop streaming](/desktop-streaming), snapshots, and forks.
# Harnesses and models
Source: https://docs.boat.dev/integrated-agents/harnesses-and-models
The seven coding-agent harnesses on every sandbox, the models each one runs, and fast mode.
Pick the harness for each prompt with `--provider`. If you omit it, Boat uses the harness you chose on the Agents dashboard.
## Harnesses
| `--provider` | Harness | Models |
| - | - | - |
| `claude` | Claude Code | Anthropic models, or DeepSeek models on a DeepSeek key |
| `codex` | OpenAI Codex | OpenAI models, or DeepSeek models on a DeepSeek key |
| `pi` | pi | Anthropic, OpenAI, Mistral, and OpenRouter or llmgateway-routed models (DeepSeek and Mistral included) |
| `opencode` | OpenCode | same multi-vendor catalog |
| `prime` | Prime Agent | same multi-vendor catalog |
| `kimi` | Kimi Code CLI (Moonshot AI) | Kimi models: K3, Kimi for Coding, K2.7 Code, K2.6 |
| `mistral` | Mistral Vibe (Mistral AI) | Mistral models: Large 4 (default), Medium 3.5, Small 4 |
For the keys each harness needs, read [Keys and subscriptions](/integrated-agents/keys).
## The model catalog
Each model accepts a different set of reasoning levels. The catalog changes often, so Boat serves it live. This page does not list it.
* `boat prompt --help` prints the catalog.
* `GET /provider-models` returns it as JSON.
You can change the model or the thinking level on any prompt. The prompt stays in the same conversation.
```bash theme={null}
boat prompt --provider pi --model claude-sonnet-5 --reasoning-effort high "Refactor the billing module"
boat prompt --model gpt-5.6-terra "Same task, second opinion" # same conversation, other model
```
## Fast mode
Fast mode runs the same model with faster output. The provider bills it at its higher fast rate.
| Harness | Fast mode is | Speed | Billing |
| - | - | - | - |
| Codex | The "Fast" service tier | About 1.5x to 2x faster | Uses ChatGPT plan limits faster |
| Claude Code | Opus fast mode | Up to 2.5x faster | Billed from Claude usage credits |
* Only models with `"fastMode": true` in `GET /provider-models` accept it. Examples are GPT-6.1 Sol, GPT-6 Sol and Opus.
* A prompt without `fast` uses the choice saved on the Agents dashboard.
* `fast: false` forces standard speed.
<CodeGroup>
```bash CLI theme={null}
boat prompt --provider codex --model gpt-6.1-sol --fast "Fix the failing tests"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"codex","model":"gpt-6.1-sol","fast":true,"prompt":"Fix the failing tests"}'
```
```ts TypeScript theme={null}
await sandbox.prompt({ sandboxId, provider: "codex", model: "gpt-6.1-sol", fast: true, prompt: "Fix the failing tests" });
```
```python Python theme={null}
sandbox.prompt(sandbox_id, PromptRequest(provider="codex", model="gpt-6.1-sol", fast=True, prompt="Fix the failing tests"))
```
</CodeGroup>
A model without fast mode refuses `fast: true` with `400 fast_mode_not_supported`. The error message lists the models that have fast mode.
# Keys and subscriptions
Source: https://docs.boat.dev/integrated-agents/keys
Run the harnesses on your own keys and subscriptions, or on the keys of your users. DeepSeek, Amazon Bedrock and Mistral setup.
The harness reads its credentials from the environment and the auth files of the sandbox. Boat fills them from one of two sources:
| Source | How | Who sees the keys |
| - | - | - |
| **Your account** | Connect keys or subscriptions on the [Agents dashboard](https://boat.dev/dashboard?tab=agents) one time. Every sandbox gets them | You, on your own sandboxes |
| **Per sandbox, from your user** | `boat new --no-env -e ANTHROPIC_API_KEY=… -e OPENAI_API_KEY=…` (API: `noEnv: true` plus `env`) | Only that sandbox. Your account keys never go on it |
<Warning>
Your account keys go on a sandbox only if its [environment](/environments) lets them in. If you chose the platform option at onboarding (the preselected option), your first environment is **Safe for third parties**. This setting keeps every key out.
If a prompt fails with "no credential" but the Agents tab shows you as connected, do these steps:
1. Open [Dashboard > Environment](https://boat.dev/dashboard?tab=environment).
2. Turn off **Safe for third parties**.
3. Keep **Agents credentials** on.
New sandboxes get the change at once. For running sandboxes, press the upgrade button on that page. The Agents tab warns you when an environment blocks your keys.
</Warning>
## Connect a subscription
The Agents dashboard connects subscriptions the same way for all four vendors:
| Subscription | Plans |
| - | - |
| **Claude** | Pro or Max |
| **ChatGPT** | Plus, Pro or Team |
| **Kimi** | Kimi Code |
| **Mistral** | Le Chat Pro or Team, for Mistral Vibe |
1. Click **Sign in**.
2. Approve on the page of the vendor. ChatGPT and Kimi show a short code to confirm. Mistral needs no code.
3. The dashboard shows the subscription as connected.
The Mistral sign-in gives Boat a Mistral API key. This key bills against the Vibe quota of your plan, not against paid API credits. It does not expire.
Boat keeps the sign-in alive for you. The server refreshes the token before every prompt and every sandbox start. So a sandbox never starts on an expired token.
To remove a subscription from every sandbox, click **Sign out** on the same row.
## Use the keys of your users
`--no-env` keeps every one of your credentials out of the sandbox. The `-e` values are the only credentials the sandbox has. Use this for a product where each end user brings their own key or subscription and picks a harness in a selector:
```mermaid theme={null}
sequenceDiagram
participant U as Your user
participant App as Your app
participant API as Boat API
U->>App: pastes key, picks Claude Code
App->>API: POST /sandboxes {noEnv: true, env: {ANTHROPIC_API_KEY}}
API-->>App: sandbox id
App->>API: POST /prompt {provider: "claude", prompt}
API-->>App: events (streamed)
App-->>U: live output
```
Keys are per sandbox, not per conversation. A sandbox that several users share runs on one set of credentials.
* When the keys of each paying user must stay apart, give each user their own sandbox.
* When the keys are yours, share one sandbox across conversations.
## Environment variables
The harnesses read these variables. Any subset works. If the vendor key of a harness is missing, that harness refuses the prompt with a credential error. The other harnesses keep working.
| Variable | Used by |
| - | - |
| `ANTHROPIC_API_KEY` | Claude Code, pi, OpenCode, Prime Agent |
| `OPENAI_API_KEY` | Codex, pi, OpenCode, Prime Agent |
| `OPENROUTER_API_KEY` | pi, OpenCode, Prime Agent |
| `LLMGATEWAY_API_KEY` | pi, OpenCode, Prime Agent |
| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code. A Claude Pro or Max subscription token from `claude setup-token` |
| `MOONSHOT_API_KEY` | Kimi Code. A Kimi open platform key (api.moonshot.ai) |
| `MISTRAL_API_KEY` | Mistral Vibe, pi, OpenCode, Prime Agent. A [Mistral API key](https://console.mistral.ai/api-keys), or the key the Mistral Vibe sign-in made |
| `KIMI_CODE_ACCESS_TOKEN`, `KIMI_CODE_REFRESH_TOKEN` | Kimi Code. A Kimi Code subscription token pair: the `access_token` and `refresh_token` that `kimi login` stores in `~/.kimi-code/credentials/kimi-code.json` |
| `DEEPSEEK_API_KEY` | Claude Code and Codex. A [DeepSeek platform key](https://platform.deepseek.com/api_keys). Read [DeepSeek](#deepseek) |
| `AWS_BEARER_TOKEN_BEDROCK` + `AWS_REGION` | Claude Code (with `CLAUDE_CODE_USE_BEDROCK=1`) and Codex (with `OPENAI_BASE_URL`). Read [Amazon Bedrock](#amazon-bedrock) |
Kimi Code does not read a credential from the environment itself. Before the first prompt, the sandbox writes these values into `~/.kimi-code/config.toml` and the token file. After that, the CLI refreshes the subscription token by itself.
## DeepSeek
Claude Code and Codex can run on the models of DeepSeek instead of Anthropic or OpenAI. One credential covers both: a [DeepSeek platform key](https://platform.deepseek.com/api_keys). It is a single string that starts with `sk-`.
DeepSeek publishes an Anthropic-shaped endpoint and an OpenAI-shaped endpoint for the same key. So Boat does not change either harness, and neither harness needs a gateway in front of it.
| Source | How |
| - | - |
| **Your account** | Agents dashboard, the DeepSeek API key row. Paste the key one time. Then point Claude Code or Codex (or both) at it and pick a DeepSeek model |
| **Per sandbox, from your user** | `boat new --no-env -e DEEPSEEK_API_KEY=sk-…`. This one variable sets up both harnesses. If you also pass the key of another vendor, that harness keeps its own credential |
What the sandbox gives each harness, and the model ids to pass:
| Harness | Environment | Model ids |
| - | - | - |
| Claude Code | `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic`, `ANTHROPIC_AUTH_TOKEN` = the key, `ANTHROPIC_API_KEY` empty. If it is not empty, Claude Code sends an `x-api-key` header that the endpoint rejects | `deepseek-flash`, `deepseek-v4-pro`. DeepSeek also maps the Claude model names onto these. So the small, fast and subagent models of the harness work by themselves |
| Codex | `OPENAI_BASE_URL=https://api.deepseek.com/v1` and the key. Codex ignores `OPENAI_BASE_URL` itself, so the agent server writes a `model_providers.deepseek` block that points at `https://api.deepseek.com/` with `wire_api = "responses"`. Web search is off | `deepseek-flash`, `deepseek-v4-pro`. Reasoning levels are `low` and `high`, the two levels that both Codex and DeepSeek accept |
<CodeGroup>
```bash CLI theme={null}
boat new --no-env -e DEEPSEEK_API_KEY=sk-…
boat prompt --provider claude --model deepseek-flash "Summarize this repo"
boat prompt --provider codex --model deepseek-v4-pro --reasoning-effort high "Now review the diff"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"noEnv":true,"env":{"DEEPSEEK_API_KEY":"sk-…"}}'
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"claude","model":"deepseek-flash","prompt":"Summarize this repo"}'
```
```ts TypeScript theme={null}
const created = await sandbox.create({ noEnv: true, env: { DEEPSEEK_API_KEY: "sk-…" } });
await sandbox.prompt({
sandboxId: created.sandbox.id,
provider: "claude", model: "deepseek-flash", prompt: "Summarize this repo",
});
```
```python Python theme={null}
created = sandbox.create(CreateSandboxRequest(no_env=True, env={"DEEPSEEK_API_KEY": "sk-…"}))
sandbox.prompt(created.sandbox.id, PromptRequest(provider="claude", model="deepseek-flash", prompt="Summarize this repo"))
```
</CodeGroup>
pi, OpenCode and Prime Agent get DeepSeek in a different way. They use your OpenRouter key, with no DeepSeek account. They need only `OPENROUTER_API_KEY`. The models are:
* `openrouter:deepseek/deepseek-v4.1-flash`
* `openrouter:deepseek/deepseek-v4-flash-0731`
* `openrouter:deepseek/deepseek-v4-pro-0813`
## Amazon Bedrock
Claude Code and Codex can run on models that your AWS account serves, instead of the Anthropic or OpenAI API.
The simplest credential is a [Bedrock API key](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html):
* It is one string that starts with `ABSK`.
* You make it in the Bedrock console, under API keys.
* It is valid in every region.
IAM access keys also work: access key id, secret, and an optional session token.
| Source | How |
| - | - |
| **Your account** | Agents dashboard, the Bedrock row under Claude Code or Codex. Set the region, then the API key or the IAM keys. Point the harness at it and pick a Bedrock model |
| **Per sandbox, from your user** | `boat new --no-env -e AWS_BEARER_TOKEN_BEDROCK=ABSK… -e AWS_REGION=us-east-1 -e CLAUDE_CODE_USE_BEDROCK=1` |
### Claude Code on Bedrock
The sandbox gives Claude Code `CLAUDE_CODE_USE_BEDROCK=1`, `AWS_REGION`, and the key (or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`).
The model ids are Bedrock cross-region inference profiles on the Anthropic line:
* `us.anthropic.claude-sonnet-4-6`
* `us.anthropic.claude-opus-4-6-v1`
* `us.anthropic.claude-sonnet-4-5-20250929-v1:0`
* `us.anthropic.claude-opus-4-5-20251101-v1:0`
* `us.anthropic.claude-haiku-4-5-20251001-v1:0`
* `us.anthropic.claude-sonnet-5`
* `us.anthropic.claude-opus-5`
* `us.anthropic.claude-fable-5-1`
* `us.anthropic.claude-fable-5`
* `us.anthropic.claude-opus-4-8`
* `us.anthropic.claude-opus-4-7`
When you use the Bedrock credential, these are the only Claude Code models that Boat offers. The default becomes Sonnet 4.6. The reason: inside Claude Code, the plain `sonnet` and `opus` aliases point to model ids that many AWS accounts have not enabled.
### Codex on Bedrock
The sandbox gives Codex `OPENAI_BASE_URL=https://bedrock-mantle.<region>.api.aws/v1` and the key. Codex ignores `OPENAI_BASE_URL` itself. So the agent server selects the built-in `amazon-bedrock` provider of Codex for that region. It uses the OpenAI-compatible [Mantle endpoint](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) of Bedrock. Web search is off.
The model ids are the OpenAI line on Mantle:
* `openai.gpt-5.6-terra`
* `openai.gpt-5.6-sol`
* `openai.gpt-5.6-luna`
* `openai.gpt-5.5`
* `openai.gpt-5.5-2026-04-23`
* `openai.gpt-5.4`
* `openai.gpt-5.4-2026-03-05`
Codex on Bedrock needs the API key. IAM keys alone do not authenticate the OpenAI-compatible endpoint.
The list does not include the open-weight `gpt-oss` models. It also does not include the third-party models on Mantle (Kimi, MiniMax, Qwen, DeepSeek, GLM, Mistral). These models answer the `/v1` routes of Mantle, but not the `/openai/v1/responses` route that Codex calls.
### Example
<CodeGroup>
```bash CLI theme={null}
boat new --no-env -e AWS_BEARER_TOKEN_BEDROCK=ABSK… -e AWS_REGION=us-east-1 -e CLAUDE_CODE_USE_BEDROCK=1
boat prompt --provider claude --model us.anthropic.claude-sonnet-4-6 "Summarize this repo"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"noEnv":true,"env":{"AWS_BEARER_TOKEN_BEDROCK":"ABSK…","AWS_REGION":"us-east-1","CLAUDE_CODE_USE_BEDROCK":"1"}}'
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"claude","model":"us.anthropic.claude-sonnet-4-6","prompt":"Summarize this repo"}'
```
```ts TypeScript theme={null}
const created = await sandbox.create({
noEnv: true, env: { AWS_BEARER_TOKEN_BEDROCK: "ABSK…", AWS_REGION: "us-east-1", CLAUDE_CODE_USE_BEDROCK: "1" },
});
await sandbox.prompt({
sandboxId: created.sandbox.id,
provider: "claude", model: "us.anthropic.claude-sonnet-4-6", prompt: "Summarize this repo",
});
```
```python Python theme={null}
created = sandbox.create(CreateSandboxRequest(no_env=True, env={"AWS_BEARER_TOKEN_BEDROCK": "ABSK…", "AWS_REGION": "us-east-1", "CLAUDE_CODE_USE_BEDROCK": "1"}))
sandbox.prompt(created.sandbox.id, PromptRequest(provider="claude", model="us.anthropic.claude-sonnet-4-6", prompt="Summarize this repo"))
```
</CodeGroup>
### Model access is granted per AWS account and region
The lists above show what Amazon Bedrock offers for each harness. They do not show what your account can call today. Bedrock grants model access per AWS account and per region. Boat lists a model as soon as Bedrock serves it, including frontier models that AWS has not granted to you yet. Your access to a model is between your account and AWS.
To request access:
1. Open the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/) in the region that your credential uses.
2. Go to **Model catalog**.
3. Find the model.
4. Choose **Request model access**.
Some models ask for a short use case form. AWS approves these, so the approval is not instant. Access in one region does not carry to another region.
If you pick a model that your account cannot use, the prompt fails. The error names the model, the reason and the fix. For example:
```
Amazon Bedrock has not granted this AWS account access to anthropic.claude-opus-5. Bedrock grants
model access per AWS account and per region, so a model in the sandbox catalog still has to be enabled
on your side: open the Amazon Bedrock console in the region this sandbox's credential uses, find
anthropic.claude-opus-5 in the Model catalog, request access, and retry once AWS approves it. Pick a
model you already have access to in the meantime.
```
Two related failures show different errors:
| Cause | What you see |
| - | - |
| AWS rejects the key | An authentication error. The harness names the endpoint it called |
| The region prefix of the model id does not match the region of your credential | `The provided model identifier is invalid` |
The `us.` profiles above work only from US regions. From `eu-west-1`, pass `eu.anthropic.claude-sonnet-4-6` instead. The same applies to `au.` and `jp.`. A `global.` prefix works from any supported source region. It needs a wider IAM policy. Read [global cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/global-cross-region-inference.html).
## Mistral
Mistral Vibe runs the models of Mistral. pi, OpenCode and Prime Agent run the same models on the same credential. They also run them through OpenRouter or LLM Gateway, on those keys.
| Source | How |
| - | - |
| **Your account** | Agents dashboard: the Mistral Vibe subscription row (Sign in) or the Mistral API key row |
| **Per sandbox, from your user** | `boat new --no-env -e MISTRAL_API_KEY=…` |
| Harness | Model ids |
| - | - |
| Mistral Vibe | `mistral-large-4` (default), `mistral-medium-3.5`, `mistral-small-4`. Reasoning levels are `none` and `high`, the two levels the Mistral API accepts |
| pi, OpenCode, Prime Agent | The same ids plus `mistral-large-3` on the Mistral credential. `openrouter:mistralai/mistral-large-4-0` and the other OpenRouter ids on an OpenRouter key. `llmgateway:mistral-large-4` and the other LLM Gateway ids on an LLM Gateway key |
When both Mistral credentials are on, Boat uses the subscription key. So usage goes to the Vibe quota of your plan first.
```bash theme={null}
boat prompt --provider mistral "Summarize this repo"
boat prompt --provider pi --model mistral-large-4 "Now review the diff"
```
# Steer a running turn
Source: https://docs.boat.dev/integrated-agents/steering
Send a new message to an agent while it works. The agent uses it and keeps what it was doing.
You have three options while a turn runs:
| Command | What happens to the running turn |
| - | - |
| `boat prompt` | The new prompt waits until the turn finishes |
| `boat interrupt` | The turn stops. Its work is discarded |
| **`boat steer`** | The turn gets your new message. The agent uses it and keeps all it was doing |
`boat steer` is the same as typing into a coding agent while it works.
```bash theme={null}
boat prompt "Refactor billing and run the full test suite"
boat steer "Skip the integration tests, the unit tests are enough"
boat steer --convo <id> "Also update the changelog when you are done"
```
If you omit `--convo`, `boat steer` steers the conversation that this shell prompted last. A bare `boat prompt` continues the same conversation.
```mermaid theme={null}
sequenceDiagram
participant You
participant Turn as The running turn
You->>Turn: boat prompt "refactor billing, run the tests"
Note over Turn: working, tests running
You->>Turn: boat steer "skip the integration tests"
Note over Turn: still the same turn, now with your instruction
Turn-->>You: finishes the whole thing
```
## How each harness gets the message
Four of the seven harnesses accept a message during a turn natively. Nothing stops.
OpenCode, Kimi Code and Mistral Vibe have no such feature. Their protocol has "prompt" and "cancel", and nothing between them. For these harnesses, Boat uses a fallback automatically.
| Harness | Delivery | Turn interrupted? |
| - | - | - |
| Claude Code | Native. The message goes into the turn when the harness takes it in. If it does not, Boat runs it right after, as its own turn on the same session. | No |
| Codex | Native. `turn/steer` adds your message to the turn in progress. | No |
| pi | Native. The message goes in at the next model call of the turn. This is usually right after the tool in progress finishes. | No |
| Prime Agent | Native. Same as pi. | No |
| OpenCode | Fallback. Boat stops the turn. It then starts a new turn at once on the **same** conversation, with "Continue what you were doing" plus your instruction. | Yes, and it continues by itself |
| Kimi Code | Fallback. Same as OpenCode. | Yes, and it continues by itself |
| Mistral Vibe | Fallback. Same as OpenCode. | Yes, and it continues by itself |
## Boat makes sure the agent acts on a steer
A harness can accept a message and then do nothing with it. So Boat does not trust the harness. Boat does these things:
* Where the harness has its own steering queue, Boat watches it.
* Boat waits for that queue to empty before it marks the turn finished.
* Where Boat cannot see the delivery, it runs your instruction as its own turn when the turn ends.
So when `boat steer` returns and the turn later reports `finished`, the agent did the instruction. It did not only receive it.
## Steer modes
The API response and the event both carry `native`. The event also carries the exact `mode`. It is one of `native`, `native-continued`, `fallback`, or `late`.
**`native-continued`** is the honest middle case. The harness accepted the message, but its turn ended without acting on it. So Boat ran it at once as its own turn on the same session. Nothing was interrupted and nothing was forgotten. The instruction only runs one turn boundary later.
The `fallback` path also keeps the harness session and all its memory. So nothing is forgotten. The cost is the one tool call that was in progress. The agent can redo a small part of the work it had just started.
## A steer in the event stream
A steer is its own event in the stream. It is never a queued prompt:
```bash theme={null}
boat events --convo <id>
```
```
you [prompt]: Refactor billing and run the full test suite
you [steer]: Skip the integration tests, the unit tests are enough
...
```
## Steer with no running turn
If the conversation has no turn in progress, Boat refuses the steer with `no_running_turn` (409). This is on purpose. You asked to change a running turn. A new queued turn would be a surprise. To start a new turn, use `boat prompt`.
# Eve
Source: https://docs.boat.dev/integrations/eve
Run Eve sandboxes on Boat with the @asciidev/eve-box backend. A step-by-step guide for people new to Eve or Boat.
<video />
<Note>The adapter package keeps its old name until we publish it again under the new name. Everything it talks to is Boat.</Note>
[Eve](https://www.npmjs.com/package/eve) is a TypeScript framework for coding agents. Eve runs each agent inside a **sandbox**. The sandbox is an isolated filesystem and shell. The agent reads files, writes files and runs commands there. Eve lets you choose where the sandbox runs.
[Boat](/quickstart) is the Ascii cloud sandbox. It is a full Linux machine. You create it over an API, run commands in it, and read and write its files.
`@asciidev/eve-box` connects Eve to Boat. It is an Eve **sandbox backend**. It sends the Eve filesystem and process operations to the Boat API. Your Eve agents then run on Boat sandboxes, not on your laptop.
<Note>
You need only two things for this guide: Node.js 18+ and a Boat API key. You do not need to know Eve or Boat before you start.
</Note>
## How it fits together
| Part | Job |
| - | - |
| **Eve** | Holds your agent logic. Calls a sandbox for filesystem and shell work. |
| **`@asciidev/eve-box`** | The adapter that you plug into Eve. |
| **Boat** | The machine where the work runs. |
```
your Eve agent ──> Eve sandbox API ──> @asciidev/eve-box ──> Sandbox machine
```
## Set it up
<Steps>
<Step title="Create a Boat account">
Sign in at [boat.dev](https://boat.dev) with GitHub. Start a Boat plan. The plan includes a free 7-day trial. You need an account to create sandboxes. For the full onboarding steps, read the [Boat quickstart](/quickstart).
</Step>
<Step title="Get a Boat API key">
Create a key on the [API keys](/api-keys) tab of the Boat dashboard. Keep the key secret. Store it in an environment variable. Never put it in source control.
```bash theme={null}
export BOAT_API_KEY=sandbox_your_real_key_here
```
</Step>
<Step title="Install the packages">
```bash theme={null}
npm install @asciidev/eve-box eve
```
Use a modern TypeScript config: `"module": "NodeNext"`, `"target": "ES2022"`, `"lib": ["ES2022", "DOM"]`. Set `"type": "module"` in `package.json`.
</Step>
<Step title="Define the sandbox backend">
Set the Eve sandbox to use Boat. In an Eve project, put this in your sandbox definition file:
```ts title="sandbox.ts" theme={null}
import { defineSandbox } from "eve/sandbox";
import { asciiBox } from "@asciidev/eve-box";
export default defineSandbox({
backend: asciiBox({
apiKey: process.env.BOAT_API_KEY!,
ttlSeconds: 3600, // auto-stop the sandbox one hour after creation
}),
});
```
The Eve agents in this project now run on Boat.
</Step>
</Steps>
## A complete example
This script runs on its own. It creates a Boat sandbox session and tests the operations that Eve uses: run commands, read files and write files. Use it to check your setup before you connect the backend to a larger Eve agent.
```ts title="hello-sandbox.ts" theme={null}
import { asciiBox } from "@asciidev/eve-box";
async function main() {
const backend = asciiBox({
apiKey: process.env.BOAT_API_KEY!,
name: "eve-hello",
ttlSeconds: 600,
});
// Create a session (this provisions a sandbox and waits until it is ready).
const handle = await backend.create({
templateKey: null,
sessionKey: "hello-session",
runtimeContext: { appRoot: process.cwd() },
});
const session = await handle.useSessionFn({ networkPolicy: "allow-all" });
// Write a file, run a command against it, and read the result back.
await session.writeTextFile({ path: "notes/hello.txt", content: "hello from Boat\n" });
const result = await session.run({ command: "cat notes/hello.txt && uname -a" });
console.log("exit:", result.exitCode);
console.log(result.stdout);
// Paths resolve under /workspace, matching Eve's sandbox contract.
console.log(session.resolvePath("notes/hello.txt")); // -> /workspace/notes/hello.txt
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
```
```bash theme={null}
BOAT_API_KEY=boat_... npx tsx hello-sandbox.ts
```
The output shows the file contents, the `uname` output of the machine, and exit code `0`.
## What the backend maps
| Eve operation | Boat behaviour |
| - | - |
| `run` | Runs a bounded command in the sandbox work directory. |
| `spawn` | Starts a background process. Gives streamed `stdout`/`stderr`, `wait()` and `kill()`. |
| `readTextFile` / `writeTextFile` | Reads and writes files under the sandbox work directory. |
| `readBinaryFile` / `writeBinaryFile` | The same, with base64 transfer for binary content. |
| `removePath` | Removes files and directories in the workspace. |
| `resolvePath` | Resolves relative paths from `/workspace`. |
| create / resume | Creates a new sandbox, or connects again to one from the saved Eve session state. |
## Configuration
`asciiBox(options)` accepts these options:
| Option | Default | Description |
| - | - | - |
| `apiKey` | `process.env.BOAT_API_KEY` | Boat API key. |
| `baseUrl` | public Boat API | Boat API base URL. |
| `name` | `eve-<sessionKey>` | Name, or `(input) => string`, for the sandboxes that Eve creates. |
| `ttlSeconds` | `3600` | Auto-stop TTL in seconds. `null` turns off auto-stop. |
| `noEnv` | `false` | Keeps your account secrets and credentials out of sandboxes. Read [Agents that other people use](#running-agents-for-other-people). |
| `env` | none | Environment variables for each sandbox that Eve creates. Read [Agents that other people use](#running-agents-for-other-people). |
| `pollMs` | `500` | How often `spawn()` streams and `wait()` poll. |
| `commandTimeoutMs` | none | Timeout for blocking `run()` commands. |
| `networkPolicy` | none | Initial network policy. Read [Network policies](#network-policies). |
## Running agents for other people
<Warning>
By default, a sandbox gets **your** Boat account. This includes your secrets, secret files, repositories cloned with your GitHub credentials, and your SSH identity. This is fine for your own agents. If other people can control the agent, set `noEnv: true`. Then they cannot read your secrets or act as you.
</Warning>
With `noEnv: true`, the sandbox starts without your account credentials. It cannot act on your account or other sandboxes. This does not restrict network access. You then give it only what it needs:
* Secrets: through `env`.
* Files and setup: through the Eve `onSession` hook.
```ts title="sandbox.ts" theme={null}
import { defineSandbox } from "eve/sandbox";
import { asciiBox } from "@asciidev/eve-box";
export default defineSandbox({
backend: asciiBox({
apiKey: process.env.BOAT_API_KEY!,
noEnv: true,
// Scoped secrets: the only env this sandbox gets:
env: { MY_APP_TOKEN: process.env.MY_APP_TOKEN! },
}),
async onSession({ use }) {
const sandbox = await use();
// Seed files and run setup with the session API. These wrap Boat's file
// and command APIs, so you don't need `boat scp` or `boat ssh`.
await sandbox.writeTextFile({ path: "config/app.json", content: JSON.stringify({ mode: "prod" }) });
await sandbox.run({ command: "git clone https://github.com/acme/public-repo . && npm ci" });
},
});
```
Rules for `env`:
* `env` keys merge over your account variables. The per-sandbox value wins.
* The limit is 100 variables and 64 KB in total.
* Boat rejects reserved Boat-internal names.
The session API replaces the Boat CLI inside Eve:
| Eve call | Same as |
| - | - |
| `writeFile` / `readFile` | [`boat scp`](/ssh-access#copy-files) |
| `run` / `spawn` | `boat ssh <id> <cmd>` |
A no-env sandbox cannot reach your private repositories. Clone public ones, or let the user sign in inside the sandbox. Read [No-env sandboxes](/environments#safe-for-third-parties).
## Reusing a prepared environment
Setup runs when Boat first creates the sandbox for each session. To start many sessions from the same prepared state, fork a sandbox:
1. Prepare one sandbox.
2. Stop it, so that its snapshot completes.
3. Fork it. Each copy keeps the full filesystem.
Read [Fork sandbox](/api/reference/sandboxes/fork-sandbox).
## Network policies
Boat does not enforce the fine-grained Eve network policies yet.
* The backend accepts `"allow-all"`.
* For stricter policies, it throws `EveSandboxUnsupportedError`. This includes `"deny-all"`, allow-lists and subnet rules.
Thus you never get isolation that is not real. If you need policies that a firewall enforces, run that Eve agent on a backend that supports them.
## Resources
<CardGroup>
<Card title="npm package" icon="npm" href="https://www.npmjs.com/package/@asciidev/eve-box">
`@asciidev/eve-box` on npm.
</Card>
<Card title="Source on GitHub" icon="github" href="https://github.com/ariana-dot-dev/eve-box">
Issues, examples and the adapter source.
</Card>
<Card title="Boat quickstart" icon="rocket" href="/quickstart">
Install Boat and create your first sandbox.
</Card>
<Card title="Boat API keys" icon="key" href="/api-keys">
Create and manage the key that this adapter needs.
</Card>
</CardGroup>
# Harbor
Source: https://docs.boat.dev/integrations/harbor
Run Harbor agent trials and evals on Boat with the harbor-box environment adapter. A step-by-step guide for people new to Harbor or Boat.
<video />
<Note>The adapter package keeps its old name until we publish it again under the new name. Everything it talks to is Boat.</Note>
[Harbor](https://pypi.org/project/harbor/) is a Python framework for coding-agent tasks and evals. Harbor runs each agent inside an **environment**. The environment is an isolated filesystem and shell. The agent reads files, writes files and runs commands there. Harbor lets you choose where the environment runs.
[Boat](/quickstart) is the Ascii cloud sandbox. It is a full Linux machine. You create it over an API, run commands in it, and read and write its files.
`harbor-box` connects Harbor to Boat. It is a Harbor **environment adapter** (`SandboxEnvironment`). It sends the Harbor lifecycle, command and file operations to the Boat API. Your Harbor trials then run on Boat sandboxes. They do not run in a local Docker container, E2B or Modal.
<Note>
You need only two things for this guide: Python 3.12+ and a Boat API key. You do not need to know Harbor or Boat before you start.
</Note>
## How it fits together
| Part | Job |
| - | - |
| **Harbor** | Holds your task and eval logic. Calls an environment for filesystem and shell work. |
| **`harbor-box`** | The adapter that you plug into Harbor. You import it as `harbor_box_environment`. |
| **Boat** | The machine where the work runs. |
```
your Harbor task ──> Harbor BaseEnvironment ──> harbor-box (SandboxEnvironment) ──> Sandbox machine
```
## Set it up
<Steps>
<Step title="Create a Boat account">
Sign in at [boat.dev](https://boat.dev) with GitHub. Start a Boat plan. The plan includes a free 7-day trial. You need an account to create sandboxes. For the full onboarding steps, read the [Boat quickstart](/quickstart).
</Step>
<Step title="Get a Boat API key">
Create a key on the [API keys](/api-keys) tab of the Boat dashboard. Keep the key secret. Store it in an environment variable. Never put it in source control.
```bash theme={null}
export BOAT_API_KEY=sandbox_your_real_key_here
```
</Step>
<Step title="Install the package">
```bash theme={null}
pip install harbor-box
```
This also installs Harbor (`harbor>=0.14.0`), `httpx` and `tenacity`. It needs Python 3.12+.
</Step>
<Step title="Wire it into Harbor">
When you run a task, give Harbor the import path of the adapter:
```bash theme={null}
harbor task run path/to/task.yaml \
--environment-import-path harbor_box_environment:SandboxEnvironment
```
The Harbor trials for this task now run on Boat.
</Step>
</Steps>
## A complete example
This script runs on its own. It creates a Boat sandbox environment and tests the operations that Harbor uses: run commands, read files and write files. Use it to check your setup before you connect the adapter to a larger Harbor run.
```python title="hello_sandbox.py" theme={null}
import asyncio
import tempfile
from pathlib import Path
from harbor.models.task.config import EnvironmentConfig
from harbor.models.trial.paths import TrialPaths
from harbor_box_environment import SandboxEnvironment
async def main() -> None:
with tempfile.TemporaryDirectory() as raw:
tmp = Path(raw)
# Harbor requires an environment definition. Boat runs its default image;
# the Dockerfile's WORKDIR drives the agent's working directory.
env_dir = tmp / "environment"
env_dir.mkdir()
(env_dir / "Dockerfile").write_text("FROM ubuntu:24.04\nWORKDIR /workspace\n")
trial_paths = TrialPaths(tmp / "trial")
trial_paths.mkdir()
env = SandboxEnvironment(
environment_dir=env_dir,
environment_name="harbor-hello",
session_id="hello-session",
trial_paths=trial_paths,
task_env_config=EnvironmentConfig(workdir="/workspace"),
ttl_seconds=600, # auto-stop the sandbox 10 min after creation
)
await env.start(force_build=False) # provisions a sandbox and waits until ready
try:
# Write a file, run a command against it, and read the result back.
await env.upload_file(__file__, "/workspace/hello_sandbox.py")
result = await env.exec(
"echo 'hello from Boat' > notes.txt && cat notes.txt && uname -a"
)
print("exit:", result.return_code)
print(result.stdout)
finally:
await env.stop(delete=True)
if __name__ == "__main__":
asyncio.run(main())
```
```bash theme={null}
BOAT_API_KEY=boat_... python hello_sandbox.py
```
The output shows the file contents, the `uname` output of the machine, and exit code `0`.
## What the adapter maps
| Harbor `BaseEnvironment` operation | Boat behaviour |
| - | - |
| `start` / `stop` | Creates a sandbox and waits for it. Or stops the sandbox and archives it. |
| `exec` | Runs a bounded command in the sandbox work directory. Optional: `cwd`, `env`, `user` and timeout. |
| `upload_file` / `download_file` | Copies files to and from the sandbox. Binary files use base64. |
| `upload_dir` / `download_dir` | Copies directory trees, with all subdirectories. |
| `ensure_dirs` | Creates the configured work and mount directories. |
| `is_file` / `is_dir` | Checks for paths inside the sandbox. |
## Configuration
`SandboxEnvironment(...)` takes the standard Harbor arguments: `environment_dir`, `environment_name`, `session_id`, `trial_paths`, `task_env_config`. It also takes these Boat options:
| Option | Default | Description |
| - | - | - |
| `api_key` | `os.environ["BOAT_API_KEY"]` | Boat API key. |
| `base_url` | public Boat API | Boat API base URL. |
| `ttl_seconds` | `86400` | Auto-stop TTL in seconds. `None` turns off auto-stop. |
| `no_env` | `True` | Creates [no-env sandboxes](#isolation) (strong isolation). Set `False` to use your account environment. |
| `request_timeout_seconds` | `30` | HTTP timeout for each request. |
| `client` | none | A preconfigured `AsyncSandboxClient`, if you want to supply your own. |
`BOAT_API_KEY` is required. Pass `api_key=...` or set the environment variable. The adapter calls `preflight()`. If the key is missing, it fails at once.
## Preparing the environment
Boat runs a ready image. It does not build Docker images. The adapter prepares each sandbox from your Harbor environment directory:
| Input | What the adapter does |
| - | - |
| **Files** in the environment directory | Uploads them into the sandbox working directory at start. Fixtures, configs and scripts are in place before the agent runs. |
| **`Dockerfile`** | Reads only the `WORKDIR` of the final stage. It does not run build steps (`RUN` / `COPY` / …). Install dependencies with a setup command (`await env.exec(...)`) or from your agent. |
| **Environment variables** | Takes them from the Harbor environment config and sends them into the sandbox. Per-command env goes through `exec`. |
```python theme={null}
task_env_config = EnvironmentConfig(workdir="/workspace", env={"DATABASE_URL": "postgres://..."})
```
To start many trials from the same prepared filesystem:
1. Prepare one sandbox.
2. Stop it, so that its snapshot completes.
3. Fork it. Each copy keeps the full filesystem.
Read [Fork sandbox](/api/reference/sandboxes/fork-sandbox).
## Isolation
By default, the adapter creates **no-env** sandboxes. A trial does not get your Boat account secrets, credentials or cloned private repositories. A trial cannot act on your account or on other sandboxes. This default is correct for evals and for sandboxes that you give to other people.
To use your account environment, pass `no_env=False`. You configure that environment on the [Secrets](https://boat.dev/dashboard?tab=environment) and [Repositories](https://boat.dev/dashboard?tab=environment) tabs of the Boat dashboard. Read [Environments](/environments).
## Not available on Boat
Some Harbor features do not work on Boat today. They raise a clear error:
* Network policies (no network, allow-lists).
* Docker image builds and Compose.
* GPUs, TPUs and Windows.
Run those tasks on a backend that supports them.
## Resources
<CardGroup>
<Card title="PyPI package" icon="python" href="https://pypi.org/project/harbor-box/">
`harbor-box` on PyPI.
</Card>
<Card title="Source on GitHub" icon="github" href="https://github.com/ariana-dot-dev/harbor-box">
Issues, evals and the adapter source.
</Card>
<Card title="Boat quickstart" icon="rocket" href="/quickstart">
Install Boat and create your first sandbox.
</Card>
<Card title="Boat API keys" icon="key" href="/api-keys">
Create and manage the key that this adapter needs.
</Card>
</CardGroup>
# Long-Running Tasks
Source: https://docs.boat.dev/long-running-tasks
Keep a sandbox running longer, restart processes after resume or fork, and read the history and output of past commands.
<video />
A sandbox stops by itself 1 hour after it starts. This is the default auto-stop timer. For work that runs longer, use the tools on these pages.
<Note>
Everything in these pages needs a payment method on the account. On the free trial, you cannot turn off auto-stop, and the TTL cannot be more than 2 hours. Boat refuses the call with `trial_auto_stop_required`. See [Pricing](/pricing#concurrency).
</Note>
## What you can do
| You want | Use | Command |
| - | - | - |
| A sandbox that runs until you stop it | [Turn off auto-stop](/long-running-tasks/auto-stop#turn-off-auto-stop) | `boat extend <id> --no-auto-stop` |
| More time, with a deadline | [Extend with a deadline](/long-running-tasks/auto-stop#extend-with-a-deadline) | `boat extend <id> --hours 12` |
| A command that runs longer than 10 minutes | [Background commands](/long-running-tasks/background-commands) | `boat exec <id> --detach "<command>"` |
| The output of a past command, also on a stopped sandbox | [Command history](/long-running-tasks/command-history) | `boat history <id>` |
| The processes in a sandbox | [List processes](/long-running-tasks/command-history#list-processes) | `boat ps <id>` |
| A process that comes back after stop, resume and fork | [Always-on services](/long-running-tasks/always-on-services) | `sudo systemctl enable --now <service>` |
## What comes back after a resume
| Process | After a resume or fork |
| - | - |
| A systemd service that you enabled | Starts again by itself. |
| A process that you started by hand | Does not come back. Start it again. |
| A detached background command | Does not come back. |
## Learn more
<Columns>
<Card title="Auto-stop" icon="clock" href="/long-running-tasks/auto-stop">
Turn off auto-stop, read the deadline, and extend a sandbox.
</Card>
<Card title="Background commands" icon="terminal" href="/long-running-tasks/background-commands">
Start a long command, read its output, attach to it, and stop it.
</Card>
<Card title="Command history" icon="clock-rotate-left" href="/long-running-tasks/command-history">
Read the output of past commands and processes. List the processes.
</Card>
<Card title="Always-on services" icon="server" href="/long-running-tasks/always-on-services">
Make a process come back after stop, resume and fork.
</Card>
</Columns>
## Related
* [Snapshots](/snapshots)
* [Environments](/environments)
* [SSH Access](/ssh-access)
* [Desktop Streaming](/desktop-streaming)
* [Hosting](/hosting)
# Always-on services
Source: https://docs.boat.dev/long-running-tasks/always-on-services
Make a process come back by itself after stop, resume and fork, and restart your work in a repeatable way.
## What comes back after a resume or fork
`boat stop` makes a snapshot of the file system. `boat resume` restores that file system. `boat fork` makes a new sandbox from the latest snapshot. A resume takes a few seconds, for any amount of data in the sandbox.
For what a snapshot saves, restore behavior, retention, and how to look at or download a snapshot, see [Snapshots](/snapshots).
A stop and resume is the same as a server reboot:
| Process | After a resume |
| - | - |
| A systemd service that you enabled | Starts again by itself. |
| A process that you started by hand: a dev server, a background job, a tunnel, a browser session | Does not come back. Start it again, or make it a systemd service. |
## Run an always-on service
To make a process come back after stop, resume and fork with no action from you, run it as an enabled systemd service. The unit file is under `/etc`, which is in the snapshot. Thus a resumed or forked sandbox starts the service by itself.
```bash theme={null}
sudo tee /etc/systemd/system/my-app.service >/dev/null <<'UNIT'
[Unit]
Description=My app
After=network.target
[Service]
User=user
WorkingDirectory=/home/user/my-app
ExecStart=/usr/bin/npm run start
Restart=always
[Install]
WantedBy=multi-user.target
UNIT
sudo systemctl daemon-reload
sudo systemctl enable --now my-app
```
* `Restart=always` also starts the process again if it crashes.
* To check the service, run `systemctl status my-app`.
* To read its logs, run `journalctl -u my-app`.
Run these commands inside the sandbox. Use `boat ssh`, the [command endpoint](/api/reference/agent/execute-sandbox-command), or the `command` method of the SDKs.
If the service serves HTTP, expose it with `host <port>`. After a resume, `host` on the same port gives the same URL and token. Thus links that you gave out continue to work. See [Hosting](/hosting).
## Resume or fork
To continue earlier work, resume the sandbox. To branch earlier work, fork it. Both use the latest snapshot.
<CodeGroup>
```bash CLI theme={null}
boat resume bx_f7k2q9hd
boat fork bx_f7k2q9hd
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/resume" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/fork" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.resume({ sandboxId: "bx_f7k2q9hd" });
const forked = await sandbox.fork({ sandboxId: "bx_f7k2q9hd" });
```
```python Python theme={null}
sandbox.resume("bx_f7k2q9hd")
forked = sandbox.fork("bx_f7k2q9hd")
```
</CodeGroup>
## Repeatable setup
For repeatable workflows, make your setup and start commands idempotent:
<CodeGroup>
```bash CLI theme={null}
boat ssh "$sandbox_id" -- bash -s < ./setup.sh
boat ssh "$sandbox_id" "cd /home/user/ariana-ide-private && npm run dev"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"bash ./setup.sh","cwd":"ariana-ide-private"}'
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"npm run dev","cwd":"ariana-ide-private"}'
```
```ts TypeScript theme={null}
await sandbox.command({ sandboxId, command: "bash ./setup.sh", cwd: "ariana-ide-private" });
await sandbox.command({ sandboxId, command: "npm run dev", cwd: "ariana-ide-private" });
```
```python Python theme={null}
sandbox.command(sandbox_id, CommandRequest(command="bash ./setup.sh", cwd="ariana-ide-private"))
sandbox.command(sandbox_id, CommandRequest(command="npm run dev", cwd="ariana-ide-private"))
```
</CodeGroup>
For command timeouts and retries, see [Background commands](/long-running-tasks/background-commands#timeouts-and-retries).
# Auto-stop
Source: https://docs.boat.dev/long-running-tasks/auto-stop
Turn off auto-stop, read the auto-stop deadline, and extend a sandbox with a timed deadline.
Every sandbox has an auto-stop timer.
* The default is 1 hour.
* The timer counts from creation, not from your last activity.
* A sandbox with a 1 hour TTL stops one hour after it starts, even in the middle of work.
* A resume of a stopped sandbox starts the timer again.
<Note>
Everything on this page needs a payment method on the account. On the free trial, you cannot turn off auto-stop. The TTL also cannot be more than 2 hours. Boat refuses the call with `trial_auto_stop_required`. See [Pricing](/pricing#concurrency).
</Note>
## Turn off auto-stop
Use this when the sandbox must run until you stop it yourself. Examples are demos, browser sessions, long setup jobs and unattended workflows. A stop interrupts this work, and you must then start the processes again.
Turn off auto-stop when you create the sandbox. For a sandbox that exists, set its TTL to `null`.
<CodeGroup>
```bash CLI theme={null}
boat new --no-auto-stop
boat extend bx_f7k2q9hd --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}'
curl -sS -X PATCH "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttlSeconds":null}'
```
```ts TypeScript theme={null}
const created = await sandbox.create({ ttlSeconds: null });
await sandbox.update({
sandboxId: "bx_f7k2q9hd",
ttlSeconds: null,
});
```
```python Python theme={null}
created = sandbox.create(CreateSandboxRequest(ttl_seconds=None))
sandbox.update("bx_f7k2q9hd", UpdateSandboxRequest(ttl_seconds=None))
```
</CodeGroup>
You can also select **No auto-stop** in the dashboard.
### TTL on resume and fork
`resume` and `fork` also accept `ttlSeconds`. Thus a sandbox that comes back does not need a second call to set its lifetime.
| Call | When you do not give `ttlSeconds` |
| - | - |
| Resume | The sandbox keeps its current setting. |
| Fork | The new sandbox gets 1 hour. It does not copy the setting of the source sandbox. |
Thus a fork of a sandbox with auto-stop off does not silently make a second sandbox that never stops. See [Snapshots](/snapshots).
## Read the auto-stop deadline
Each resume sets the deadline again. The new deadline is the resume time plus the TTL of the sandbox.
If you schedule long jobs, do these steps:
1. Read the deadline after each resume.
2. Before a job that runs past the deadline, extend the sandbox.
`archiveAfter` is the deadline. It is `null` when auto-stop is off. `ttlSeconds` is the TTL as you last set it.
<CodeGroup>
```bash CLI theme={null}
boat info bx_f7k2q9hd # shows the deadline and the time left
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd" \
-H "Authorization: Bearer $BOAT_API_KEY" | jq -r .sandbox.archiveAfter
```
```ts TypeScript theme={null}
const info = await sandbox.get({ sandboxId: "bx_f7k2q9hd" });
console.log(info.sandbox.archiveAfter);
```
```python Python theme={null}
info = sandbox.get("bx_f7k2q9hd")
print(info.sandbox.archive_after)
```
</CodeGroup>
At the deadline, the sandbox stops the same as with `boat stop`. The stop starts within about 5 seconds of the deadline. Boat cuts off the jobs that run. See [what a stop does to running work](/snapshots/stop#what-a-stop-does).
There is one exception. While a prompt to the agent of the sandbox runs, Boat moves the deadline forward by one TTL. Your own jobs do not move the deadline. Examples are `boat exec` commands and services. Read `archiveAfter` again each time. Do not keep the first value.
## Extend with a deadline
To keep an auto-stop deadline, extend the sandbox:
<CodeGroup>
```bash CLI theme={null}
boat extend bx_f7k2q9hd --hours 12
boat extend bx_f7k2q9hd --ttl 2592000
```
```bash curl theme={null}
curl -sS -X PATCH "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttlSeconds":43200}'
```
```ts TypeScript theme={null}
await sandbox.update({
sandboxId: "bx_f7k2q9hd",
ttlSeconds: 12 * 60 * 60,
});
```
```python Python theme={null}
sandbox.update("bx_f7k2q9hd", UpdateSandboxRequest(ttl_seconds=12 * 60 * 60))
```
</CodeGroup>
* `2592000` seconds is 30 days.
* 30 days is the maximum numeric TTL that the Boat API accepts.
* Boat caps larger values to 30 days.
# Background commands
Source: https://docs.boat.dev/long-running-tasks/background-commands
Start a command that runs longer than 10 minutes, read its output, attach to it, and stop it.
A synchronous command stops at its `timeoutSeconds` limit. The maximum is 600 seconds (10 minutes). For a longer job, start the command detached, then poll for its result. Examples are builds, installs and data processing.
This replaces the `nohup ... &` pattern for simple cases. You do not keep an SSH session open. You do not write a unit file.
The flow is: start, then poll, then collect.
## Start a command and read its status
<CodeGroup>
```bash CLI theme={null}
pid="$(boat exec bx_f7k2q9hd --detach "npm run build" | jq -r .processId)"
boat exec bx_f7k2q9hd --status "$pid"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"npm run build","detached":true}'
# {"type":"command.started","processId":1234,"pid":1234,"logPath":"/home/user/.ascii/processes/1234.log",...}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands/1234" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"command.status","running":false,"exitCode":0,"stdout":"...","stderr":"...",...}
```
```ts TypeScript theme={null}
const started = await sandbox.command({
sandboxId,
command: "npm run build", detached: true,
});
const status = await sandbox.commandStatus({ sandboxId, processId: started.processId });
```
```python Python theme={null}
from boat_sdk.models.command_request import CommandRequest
started = sandbox.command(sandbox_id, CommandRequest(command="npm run build", detached=True))
status = sandbox.command_status(sandbox_id, started.process_id)
```
</CodeGroup>
* The command continues on the sandbox after the start call returns.
* Boat appends stdout and stderr to `~/.ascii/processes/<pid>.log` on the sandbox.
* The status call gives `running`, the `exitCode` when the command ends, and the last part of each log.
## Read only new output
1. Give `stdoutOffset` and `stderrOffset` to the status call. Start at 0.
2. The answer holds only the output written after those byte offsets.
3. The answer also holds `stdoutNextOffset` and `stderrNextOffset`. Use them in the next call.
4. When `more` is `true`, call again immediately.
<CodeGroup>
```bash CLI theme={null}
# The CLI follows for you: see Attach below.
boat exec bx_f7k2q9hd --attach "$pid"
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands/1234?stdoutOffset=0&stderrOffset=0" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"command.status","running":true,"stdout":"compiling...\n","stdoutNextOffset":13,"stderrNextOffset":0,"more":false,...}
```
```ts TypeScript theme={null}
let stdoutOffset = 0, stderrOffset = 0;
for (;;) {
const r: any = await sandbox.commandStatus({ sandboxId, processId: started.processId, stdoutOffset, stderrOffset });
process.stdout.write(r.stdout);
process.stderr.write(r.stderr);
stdoutOffset = r.stdoutNextOffset;
stderrOffset = r.stderrNextOffset;
if (!r.running && !r.more) break;
if (!r.more) await new Promise((ok) => setTimeout(ok, 1000));
}
```
```python Python theme={null}
import sys, time
out_offset = err_offset = 0
while True:
r = sandbox.command_status(sandbox_id, started.process_id, stdout_offset=out_offset, stderr_offset=err_offset)
sys.stdout.write(r.stdout)
sys.stderr.write(r.stderr)
out_offset, err_offset = r.stdout_next_offset, r.stderr_next_offset
if not r.running and not r.more:
break
if not r.more:
time.sleep(1)
```
</CodeGroup>
## Attach to a background process
Attach opens one stream. The stream sends the output while the command writes it, until the command ends. Use attach instead of polling.
The API allows about 1,000 requests per minute per IP address. One poll per second for each of many processes reaches this limit. One open stream per process does not.
Each line of the stream is one JSON object:
| Line | When |
| - | - |
| `attached` | First. |
| `stdout` / `stderr` | Each chunk of output, with its `nextOffset`. |
| `heartbeat` | After 15 seconds with no output. |
| `reconnect` | After 10 minutes. The stream ends. The line holds `stdoutOffset` and `stderrOffset`. |
| `exit` | Last. It holds the exit code. |
After a `reconnect` line, open the stream again with those offsets. You get no gap and no repeat, for as long as the command runs. The CLI reconnects for you.
<CodeGroup>
```bash CLI theme={null}
boat exec bx_f7k2q9hd --attach "$pid"
# prints the output from its start, then exits with the command's exit code
```
```bash curl theme={null}
curl -sSN "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands/1234/stream?stdoutOffset=0&stderrOffset=0" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"attached","processId":1234,"stdoutOffset":0,"stderrOffset":0}
# {"type":"stdout","data":"compiling...\n","nextOffset":13}
# {"type":"exit","status":"exited","exitCode":0,"signal":null,"stdoutOffset":13,"stderrOffset":0}
```
```ts TypeScript theme={null}
let offsets = { stdout: 0, stderr: 0 };
for (let done = false; !done; ) {
const res = await fetch(`${BOAT_API_BASE}/sandboxes/${sandboxId}/commands/${pid}/stream?stdoutOffset=${offsets.stdout}&stderrOffset=${offsets.stderr}`,
{ headers: { Authorization: `Bearer ${BOAT_API_KEY}` } });
const lines = res.body!.pipeThrough(new TextDecoderStream());
let buf = "";
for await (const chunk of lines) {
buf += chunk;
let i;
while ((i = buf.indexOf("\n")) >= 0) {
const f = JSON.parse(buf.slice(0, i));
buf = buf.slice(i + 1);
if (f.type === "stdout" || f.type === "stderr") { process[f.type].write(f.data); offsets[f.type] = f.nextOffset; }
if (f.type === "reconnect") offsets = { stdout: f.stdoutOffset, stderr: f.stderrOffset };
if (f.type === "exit" || f.type === "error") done = true;
}
}
}
```
```python Python theme={null}
import json, sys, requests
offsets = {"stdout": 0, "stderr": 0}
done = False
while not done:
url = f"{BOAT_API_BASE}/sandboxes/{sandbox_id}/commands/{pid}/stream"
params = {"stdoutOffset": offsets["stdout"], "stderrOffset": offsets["stderr"]}
with requests.get(url, params=params, headers={"Authorization": f"Bearer {BOAT_API_KEY}"}, stream=True) as r:
for line in r.iter_lines():
if not line:
continue
f = json.loads(line)
if f["type"] in ("stdout", "stderr"):
getattr(sys, f["type"]).write(f["data"])
offsets[f["type"]] = f["nextOffset"]
elif f["type"] == "reconnect":
offsets = {"stdout": f["stdoutOffset"], "stderr": f["stderrOffset"]}
elif f["type"] in ("exit", "error"):
done = True
```
</CodeGroup>
Polling and attach both read the sandbox live. Thus the sandbox must run.
* A sandbox on an older agent answers `409 agent_outdated` until its next agent upgrade.
* To read output after the sandbox stops, use the [command history](/long-running-tasks/command-history).
## Stop a background command
Stop the command by its process id. This also stops every process that the command started.
1. Boat sends `SIGTERM` to the whole process group.
2. After 5 seconds, Boat sends `SIGKILL` to the processes that remain.
3. The response holds the [history record](/long-running-tasks/command-history) of the command, with status `killed` and its last output.
<CodeGroup>
```bash CLI theme={null}
boat exec bx_f7k2q9hd --kill "$pid"
```
```bash curl theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands/1234" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"command.stopped","processId":1234,"running":false,"signaled":true,"command":{"commandId":"cmd_...","status":"killed",...}}
```
```ts TypeScript theme={null}
await sandbox.stopCommand({ sandboxId, processId: started.processId });
```
```python Python theme={null}
sandbox.stop_command(sandbox_id, started.process_id)
```
</CodeGroup>
## When the agent restarts
The process runs under the systemd user manager of the sandbox user. Thus a restart of the agent of the sandbox does not interrupt it. A platform upgrade is an example of such a restart.
But the agent forgets the process when it restarts:
* The status changes to `lost`.
* `running` becomes a best-effort check.
* Boat no longer reports `exitCode`.
* Boat reads the logs from the files on disk.
Detached processes do not continue after a stop, resume or fork. For a process that must come back by itself, run it as an [always-on service](/long-running-tasks/always-on-services).
## Timeouts and retries
Synchronous commands accept `timeoutSeconds` from 1 to 600. The default is 30. Boat refuses values outside that range with a 400 `invalid_timeout` error.
Boat never retries a command call automatically. A command is not idempotent. After a timeout (`retryable: false`) or a network failure during the call, the command can already run on the sandbox. You decide what to do next.
# Command history
Source: https://docs.boat.dev/long-running-tasks/command-history
Read the output of past commands and processes in a sandbox, also when the sandbox is stopped, and list the processes.
Boat keeps the output of the processes in a sandbox. You can read it while the sandbox is stopped. A sandbox created with [monitoring off](/data-retention/snapshots-and-monitoring-off#monitoring-off) has no history.
In the dashboard, open the **⋯** menu of a sandbox and select **History**. A background command that runs shows its output live. You can stop it there.
## What Boat keeps
| Source | Mode | Kept for |
| - | - | - |
| A command you run through `boat exec` or the commands endpoint | `sync`, `stream` or `detached` | 90 days |
| Any other process that writes output: an `ssh` session, a systemd service, a docker container, a process that an agent starts | `process` | 72 hours |
The start answer of each command holds the `commandId` of its record.
| Kept | Details |
| - | - |
| The command | Its text (first 64 KiB), working directory, mode, process id |
| The result | `status` (`running`, `exited`, `timed_out`, `failed`, `killed`, `lost`), exit code, signal, start and end time |
| The output | stdout and stderr, compressed. A waiting command keeps up to 8 MiB per stream, the same as its answer. A streamed command adds output every 2 seconds. A detached command adds output every 30 seconds, and one more time when the sandbox stops. |
## Read the history
1. List the history.
2. Read the output of one command.
<CodeGroup>
```bash CLI theme={null}
boat history bx_f7k2q9hd
# cmd_k3v9x2mq7tbw exit 0 detached 2026-10-09 14:02:11 npm run build
boat history bx_f7k2q9hd cmd_k3v9x2mq7tbw # stdout
boat history bx_f7k2q9hd cmd_k3v9x2mq7tbw --stderr
boat history bx_f7k2q9hd cmd_k3v9x2mq7tbw --follow # until it ends
boat history bx_f7k2q9hd --mode commands # only what you ran
boat history bx_f7k2q9hd --mode process # only the other processes
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/command-history?limit=20&mode=commands" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"command.list","commands":[{"commandId":"cmd_k3v9x2mq7tbw","status":"exited","exitCode":0,...}],"nextCursor":null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/command-history/cmd_k3v9x2mq7tbw/logs?stream=stdout&offset=0" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"command.logs","offset":0,"nextOffset":1830,"size":1830,"data":"...","done":true}
```
```ts TypeScript theme={null}
const { commands } = await sandbox.commandHistory({ sandboxId, limit: 20, mode: "commands" });
let offset = 0;
for (;;) {
const page = await sandbox.commandLogs({ sandboxId, commandId: commands[0].commandId, stream: "stdout", offset });
process.stdout.write(page.data);
offset = page.nextOffset;
if (page.done) break;
if (!page.data) await new Promise((r) => setTimeout(r, 2000)); // still running
}
```
```python Python theme={null}
import sys, time
page = sandbox.command_history(sandbox_id, limit=20, mode="commands")
command_id = page.commands[0].command_id
offset = 0
while True:
logs = sandbox.command_logs(sandbox_id, command_id, stream="stdout", offset=offset)
sys.stdout.write(logs.data)
offset = logs.next_offset
if logs.done:
break
if not logs.data:
time.sleep(2) # still running
```
</CodeGroup>
* Each read gives at most 1 MiB.
* Read again from `nextOffset` until `done` is `true`.
* To get the exact bytes of binary output, pass `encoding=base64`.
<Note>
An account keeps at most 10 MiB of compressed command output per hour. This is about 50 MiB of plain text. Boat drops the output past that, and the command shows `outputTruncated: true`.
</Note>
## Every process in the sandbox
Boat records what each process writes to its terminal, to a pipe, or to a socket such as the journal. You do not change your programs for this. Each process is one `process` record, with its command line, its process id and its exit code.
| Rule | Details |
| - | - |
| Rate | Up to 64 KiB/s per process, with bursts up to 1 MiB. Output past that is dropped and the record shows `outputTruncated: true`. |
| Account cap | 10 MiB of compressed process output per hour, separate from the command cap. Output past that is dropped and the record shows `outputTruncated: true`. |
| Not recorded | Writes to regular files and to `/dev/null`, binary output, and the services that Boat itself runs in the sandbox. |
| Delay | New output appears within about 30 seconds. Output still on the sandbox when it stops is saved before the stop. |
Boat records a command that you run through `boat exec` one time, as a command. Its child processes do not show again as `process` records.
<Tip>
A busy sandbox has many short processes, such as shell prompts and login scripts. To see only what you ran, use `--mode commands` (`mode=commands` in the API). To see only the other processes, use `--mode process`.
</Tip>
## Retention and deletion
The history is account data, the same as your sandbox files.
* When you delete the sandbox, Boat deletes its history.
* With [zero data retention](/data-retention/zero-data-retention#enable-zero-data-retention), a stop queues the history for deletion with the rest of the sandbox.
## List processes
List every process in a sandbox, the busiest first.
A stopped sandbox answers with the last sample that Boat kept, and `live: false`. Boat takes the 12 busiest processes every 30 seconds and keeps them for 7 days.
<CodeGroup>
```bash CLI theme={null}
boat ps bx_f7k2q9hd
# PID CPU% MEM MB USER HISTORY COMMAND
# 2210 98.0 812.4 user cmd_k3v9x2mq7tbw node build.js
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes/$BOAT_ID/processes" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"process.list","live":true,"total":64,"processes":[{"pid":2210,"user":"user","cpuPercent":98,"memoryMB":812.4,"command":"node build.js",...}]}
```
```ts TypeScript theme={null}
const { live, processes } = await sandbox.processes({ sandboxId });
```
```python Python theme={null}
listing = sandbox.processes(sandbox_id)
```
</CodeGroup>
On a running sandbox, each process with a history record shows its `commandId` in the HISTORY column. To read its output, run `boat history <sandbox> <commandId>`.
# Machine Capabilities
Source: https://docs.boat.dev/machines
What's pre-installed on every sandbox and what you can do with it.
<video />
Each sandbox is a Linux virtual machine. Its tools are ready when you first connect with SSH. You do not have to install anything before you start.
## Machine types
There are four sizes. All of them are x86\_64. Select one with `--type` when you create the sandbox.
| Size | Per hour | CPU | RAM | Disk |
| - | - | - | - | - |
| `small` | **\$0.018** | 2 vCPU | 4 GB | 12 GB |
| `default` | **\$0.036** | 4 vCPU | 8 GB | 50 GB |
| `large` | **\$0.072** | 8 vCPU | 16 GB | 125 GB |
| `xlarge` \* | **\$0.200** | 16 vCPU | 32 GB | 251 GB |
* "Disk" is the maximum size of your own files. The operating system and the pre-installed tools are not in it.
* Run `df -h /` in a sandbox to see the live figure.
* \* `xlarge` needs the \$100 plan or higher. You do not have to send us a request.
* For plans, concurrency and start limits, see [Pricing & Limits](/pricing).
<CodeGroup>
```bash CLI theme={null}
boat new
boat new --type small
boat new --type large
```
```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 '{"type":"large","ttlSeconds":3600}'
```
```ts TypeScript theme={null}
const created = await sandbox.create({ type: "large", ttlSeconds: 3600 });
```
```python Python theme={null}
created = sandbox.create(CreateSandboxRequest(type="large", ttl_seconds=3600))
```
</CodeGroup>
By default, stop, resume and fork keep the type. A fork gets the type of its source sandbox. To change the type, read [Change size](/machines/change-size).
## The machine
| | |
| - | - |
| OS | Ubuntu 24.04 LTS, Linux 6.8, x86\_64 |
| Access | Full root through passwordless `sudo`, real `systemd` (services, timers, `journalctl`) |
| Containers | Docker with BuildKit, running on the sandbox's own kernel |
| Network | Public IPv4 or IPv6 plus outbound internet; expose ports with [Hosting](/hosting) |
| GPU | None. Graphics run on the CPU (the [desktop](/desktop-streaming) and headless Chrome work) |
## Learn more
<Columns>
<Card title="Change size" icon="up-right-and-down-left-from-center" href="/machines/change-size">
Move a sandbox to a bigger or smaller type with resume or fork.
</Card>
<Card title="Fail fast" icon="bolt" href="/machines/fail-fast">
Get an answer in about 1.5 seconds when no machine is ready.
</Card>
<Card title="Virtualization" icon="microchip" href="/machines/virtualization">
Run KVM, Firecracker or the Android emulator in a sandbox.
</Card>
<Card title="Pre-installed tools" icon="toolbox" href="/machines/tools">
Coding agents, languages, version control and utilities on every sandbox.
</Card>
</Columns>
## Related
* [Desktop Streaming](/desktop-streaming)
* [Hosting](/hosting)
* [SSH Access](/ssh-access)
# Change size
Source: https://docs.boat.dev/machines/change-size
Move a sandbox to a bigger or smaller type when you resume or fork it.
To move a sandbox to a different size, give `--type` to `resume` or `fork`.
| Command | What changes |
| - | - |
| `resume` | The sandbox itself gets the new size. |
| `fork` | The copy gets the new size. The source sandbox does not change. |
Resume and fork already restore a snapshot onto a new machine. So a size change costs nothing more than the resume or fork itself.
<CodeGroup>
```bash CLI theme={null}
boat resume bx_23456789 --type large
boat fork bx_23456789 --type small
```
```bash curl theme={null}
curl -X POST https://boat.dev/api/v1/sandboxes/bx_23456789/resume \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"large"}'
```
```ts TypeScript theme={null}
await sandbox.resume({ sandboxId: "bx_23456789", type: "large" });
```
```python Python theme={null}
sandbox.resume(sandbox_id="bx_23456789", resume_request=ResumeRequest(type="large"))
```
</CodeGroup>
## Grow and shrink
* A move to a bigger size always works.
* A move to a smaller size fails with `type_too_small` when the sandbox holds more data than the smaller size can take.
* After a refused move, the sandbox stays exactly as it was. You do not lose the sandbox.
* To shrink past that limit, delete data. Then let the sandbox make a new snapshot, and try again.
## Cost
A bigger size costs more per hour because you get a bigger machine. The price per hour in [Machine types](/machines#machine-types) is the full price.
# Fail fast
Source: https://docs.boat.dev/machines/fail-fast
Get an answer in about 1.5 seconds when no machine of your type is ready, and fall back right away.
These four calls put the sandbox on a machine that is already running and waiting:
* Create a sandbox.
* Deploy from a named snapshot.
* Fork.
* Resume.
They usually get a machine in less than one second. A burst can use all the ready machines of one type. Then the next calls wait while Boat builds new machines.
## Use fail fast
If you prefer to fall back to something else instead of waiting, pass `failFast` to any of these calls. The call then answers in about 1.5 seconds with one of two results:
| Result | What it means |
| - | - |
| `202` | The usual answer. The sandbox is on a machine that was ready. |
| `503` `no_ready_machine` | Nothing started. See below. |
When you get `503` `no_ready_machine`:
* Boat does not create a sandbox or a fork. A resumed sandbox stays stopped.
* You pay nothing.
* The attempt does not count against your [start limits](/pricing).
* Retry, or fall back, immediately.
<CodeGroup>
```bash CLI theme={null}
boat new --fail-fast --type large
boat new --fail-fast --from ci-runner
boat fork --fail-fast bx_23456789
boat resume --fail-fast bx_23456789
```
```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 '{"failFast":true,"from":"ci-runner"}'
# same field on POST /sandboxes/{id}/fork and /sandboxes/{id}/resume
```
```ts TypeScript theme={null}
try {
const created = await sandbox.create({ failFast: true, from: "ci-runner" });
// also: sandbox.fork({ sandboxId, failFast: true }), sandbox.resume({ sandboxId, failFast: true })
} catch (error) {
// 503 no_ready_machine: nothing was started; fall back or retry.
}
```
```python Python theme={null}
try:
created = sandbox.create(CreateSandboxRequest(fail_fast=True, var_from="ci-runner"))
except ApiException as error:
# 503 no_ready_machine: nothing was started; fall back or retry.
pass
```
</CodeGroup>
# Pre-installed tools
Source: https://docs.boat.dev/machines/tools
The coding agents, languages, version control tools and utilities on every sandbox.
The OS is Ubuntu 24.04. Know these defaults before you run CI jobs:
| Setting | Value | What to do |
| - | - | - |
| `LANG` and `LC_ALL` | `en_US.UTF-8` | `sort` orders lines differently from a `C.UTF-8` machine. To match one, set `LC_ALL=C.UTF-8` in your job. |
| `git` | 2.43 | If your CI actions need a newer version, install it. |
## AI & automation
| Tool | Description |
| - | - |
| `claude` | Claude Code CLI, an AI coding assistant |
| `codex` | OpenAI Codex CLI |
| `pi` | Pi coding agent ([pi.dev](https://pi.dev)) |
| `opencode` | OpenCode terminal coding agent |
| `hermes` | Hermes Agent by Nous Research (browser tools not preinstalled: `hermes` offers to add them) |
| `openclaw` | OpenClaw CLI (gateway not started; run `openclaw gateway` yourself if you want it) |
| `agent` / `cursor-agent` | Cursor CLI agent |
| `prime-agent` | Prime Intellect's Prime Agent |
| `kimi` | Kimi Code CLI by Moonshot AI |
| `vibe` | Mistral Vibe by Mistral AI (`--provider mistral`) |
| `host` | Expose localhost services to the internet |
| `lux` | Desktop and browser automation with demo recording |
| `boat` | Boat CLI inside the sandbox |
* These harnesses are installed system-wide, in `/usr/local` and `/opt`.
* They take no space in your snapshots. They come back after a stop and resume.
* Each harness signs in with its own `login` command.
* Today, `boat prompt` and the Agents page drive `claude` and `codex`.
* You can install your own copy, for example with `npm i -g` or the vendor installer into `~/.local/bin`. Your copy hides the preinstalled one. Your snapshots keep it as usual.
## Languages & runtimes
| Tool | Description |
| - | - |
| `node` / `npm` / `nvm` | Node.js 24 with npm by default (nvm-managed, also linked into `/usr/local/bin` so non-login shells get it); the apt Node.js 20 remains for compatibility, and nvm installs other versions |
| `bun` / `bunx` | Bun JavaScript runtime |
| `deno` | Deno JavaScript/TypeScript runtime |
| `pnpm` | JavaScript package manager |
| `python3` / `pip` / `venv` | Python 3 and standard Python packaging tools |
| `uv` | Python project and dependency manager |
| `go` | Go toolchain |
| `rustc` / `cargo` / `rustup` | Rust compiler, package manager, and toolchain manager |
| `java` / `mvn` / `gradle` | Java/OpenJDK, Maven, and Gradle |
| `kotlin` / `kotlinc` | Kotlin runtime and compiler |
| `scala` / `scalac` / `sbt` | Scala compiler and build tools |
| `ruby` / `gem` / `bundle` | Ruby, RubyGems, and Bundler |
| `php` / `composer` | PHP CLI and Composer |
| `erl` / `elixir` | Erlang and Elixir |
| `dotnet` | .NET SDK |
| `R` | R runtime and development packages |
| `gcc` / `g++` / `clang` / `cmake` / `ninja` | C/C++ build toolchain |
## Version control
| Tool | Description |
| - | - |
| `git` | Git |
| `gh` | GitHub CLI for PR creation, issue management, etc. |
## Utilities
| Tool | Description |
| - | - |
| `rg` | ripgrep for fast code search |
| `jq` | JSON processor |
| `curl` | HTTP client |
| `docker` | Container runtime with BuildKit. Layer cache is per machine; see [Docker builds across resume and fork](/snapshots/whats-saved#docker-builds) |
| `google-chrome-stable` | Chrome browser and headless browser runtime |
| `ffmpeg` | Media processing |
# Virtualization
Source: https://docs.boat.dev/machines/virtualization
Run KVM, Firecracker or the Android emulator inside a sandbox.
You can run virtual machines inside a sandbox: QEMU/KVM, Firecracker, or the Android emulator at full speed.
## Where your sandbox runs
| | Standard machines | Fallback machines |
| - | - | - |
| Hardware | Dedicated AMD Ryzen 9 9950X (Zen 5) hosts | Hetzner cloud VMs with an older AMD CPU |
| When Boat uses them | Normally | When the standard machines are temporarily out of capacity. Boat uses them instead of a queue. |
| `/dev/kvm` | Yes. The CPU virtualization extensions are passed through. | No |
| Price | Same | Same |
| CPU-heavy work | Normal speed | Slower, about 3x on our [build benchmark](/pricing#performance) |
Internally, we call the standard machines "baremetal". Your sandbox is still a full virtual machine with its own kernel. It is not a bare-metal server.
If you need KVM and `/dev/kvm` is missing, create a new sandbox a bit later.
## Check for KVM
Do this check before you rely on KVM:
```bash theme={null}
ls /dev/kvm && echo "KVM available"
```
## Run the Android emulator
This script runs a headless Android emulator. We tested it on a `large` sandbox.
* The install takes about one minute.
* Android 14 then boots in 20 to 30 seconds.
* The emulator needs about 3 GB of RAM. Use `default` or bigger.
```bash theme={null}
sudo apt-get install -y openjdk-17-jre-headless
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 ANDROID_HOME=$HOME/android
mkdir -p $ANDROID_HOME/cmdline-tools && cd /tmp
curl -fsSLo clt.zip https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip -q clt.zip -d $ANDROID_HOME/cmdline-tools && mv $ANDROID_HOME/cmdline-tools/cmdline-tools $ANDROID_HOME/cmdline-tools/latest
SDK=$ANDROID_HOME/cmdline-tools/latest/bin
yes | $SDK/sdkmanager --licenses >/dev/null
$SDK/sdkmanager "platform-tools" "emulator" "system-images;android-34;google_apis;x86_64"
echo no | $SDK/avdmanager create avd -n phone -k "system-images;android-34;google_apis;x86_64" -d pixel_6
if [ ! -e /dev/kvm ]; then
echo "No KVM on this sandbox: the Android emulator cannot start here." >&2
else
$ANDROID_HOME/emulator/emulator -avd phone -no-window -no-audio -gpu swiftshader_indirect &
$ANDROID_HOME/platform-tools/adb wait-for-device
fi
```
To take a screenshot, run `adb exec-out screencap -p > screen.png`.
# OpenTelemetry
Source: https://docs.boat.dev/opentelemetry
Send sandbox and account metrics, and sandbox lifecycle events, to Datadog, Grafana Cloud, Honeycomb, or any OTLP collector.
Boat pushes your account's telemetry to one OTLP/HTTP endpoint that you choose. You do not install an agent in your sandboxes.
| Signal | Path | When |
| - | - | - |
| Sandbox and account metrics | `<endpoint>/v1/metrics` | Every 60 seconds |
| Sandbox lifecycle events, as OTLP log records | `<endpoint>/v1/logs` | When each event occurs |
| | CLI | API | SDKs |
| - | - | - | - |
| Set or replace | `boat telemetry set <endpoint> -H key=value` | `PUT /telemetry` | `setTelemetry` |
| Read status | `boat telemetry` | `GET /telemetry` | `getTelemetry` |
| Remove | `boat telemetry unset` | `DELETE /telemetry` | `deleteTelemetry` |
An account has one endpoint. The headers hold your vendor credentials. So the API needs a key with `account.admin`.
## Set the endpoint
Use the **Webhooks & OTel** tab in the dashboard. You can also use the CLI, the API or an SDK.
1. Give the base URL of the collector. Boat adds `/v1/metrics` and `/v1/logs`.
2. Give the headers that your vendor needs. Read [Vendor settings](#vendor-settings).
If you paste a URL that ends in `/v1/metrics`, Boat removes that part.
<CodeGroup>
```bash CLI theme={null}
boat telemetry set https://otlp.datadoghq.com -H dd-api-key=$DD_API_KEY
# https://otlp.datadoghq.com
# headers dd-api-key
# last export -
# Saved. Test export accepted.
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/telemetry" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"endpoint":"https://otlp.datadoghq.com","headers":{"dd-api-key":"'"$DD_API_KEY"'"}}'
# {"type":"telemetry.updated","telemetry":{"endpoint":"https://otlp.datadoghq.com","headers":["dd-api-key"],...},"test":{"ok":true,"status":202,"message":null}}
```
```ts TypeScript theme={null}
const saved = await sandbox.setTelemetry({
endpoint: "https://otlp.datadoghq.com",
headers: { "dd-api-key": process.env.DD_API_KEY! },
});
console.log(saved.test.ok, saved.test.status);
```
```python Python theme={null}
import os
from boat_sdk.models.telemetry_set_request import TelemetrySetRequest
saved = sandbox.set_telemetry(TelemetrySetRequest(
endpoint="https://otlp.datadoghq.com",
headers={"dd-api-key": os.environ["DD_API_KEY"]},
))
print(saved.test.ok, saved.test.status)
```
</CodeGroup>
When you save, Boat sends one empty metrics export immediately. Boat returns the answer of the collector in `test`. So you see a wrong key or endpoint before you wait for data. The first metrics arrive within 60 seconds.
<Note>
* The endpoint must use HTTPS on port 443 or 4318.
* The endpoint must resolve only to public addresses.
* Boat encrypts the header values at rest and never returns them.
* You can set up to 20 headers.
</Note>
### Vendor settings
| Vendor | Endpoint | Headers |
| - | - | - |
| Datadog | `https://otlp.datadoghq.com` (use the OTLP host of your Datadog site) | `dd-api-key=<API key>` |
| Grafana Cloud | The OTLP endpoint on your stack's OpenTelemetry card, for example `https://otlp-gateway-prod-eu-west-2.grafana.net/otlp` | `Authorization=Basic <base64 of instanceId:token>` |
| Honeycomb | `https://api.honeycomb.io` (EU: `https://api.eu1.honeycomb.io`) | `x-honeycomb-team=<API key>`, `x-honeycomb-dataset=boat` |
| Your own OpenTelemetry Collector | `https://otel.example.com` (port 443 or 4318) | The auth header that your collector checks |
For Grafana Cloud, make the header value like this:
```bash theme={null}
echo -n "$GRAFANA_INSTANCE_ID:$GRAFANA_TOKEN" | base64
```
### Your own collector and Prometheus
1. Run the OpenTelemetry Collector with an OTLP/HTTP receiver behind TLS.
2. Export to Prometheus with remote write, or expose a scrape endpoint:
```yaml otelcol.yaml theme={null}
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
exporters:
prometheus:
endpoint: 0.0.0.0:8889
debug: {}
service:
pipelines:
metrics: { receivers: [otlp], exporters: [prometheus] }
logs: { receivers: [otlp], exporters: [debug] }
```
Prometheus turns `boat.sandbox.cpu.utilization` into `boat_sandbox_cpu_utilization`, with `boat_sandbox_id` and `boat_sandbox_name` labels.
## Metrics
* All metrics are gauges.
* Every point has `boat.sandbox.id` and `boat.sandbox.name`. So each sandbox is its own series in every vendor.
* A sandbox with [monitoring off](/data-retention/snapshots-and-monitoring-off#monitoring-off) sends no sandbox metrics. Boat still sends its lifecycle events.
| Metric | Unit | Meaning |
| - | - | - |
| `boat.sandbox.cpu.utilization` | `1` | Share of CPU time busy, 0 to 1 |
| `boat.sandbox.memory.utilization` | `1` | Share of memory in use, 0 to 1 |
| `boat.sandbox.memory.usage` | `By` | Memory in use |
| `boat.sandbox.filesystem.utilization` | `1` | Share of the disk in use, 0 to 1 |
| `boat.sandbox.filesystem.usage` | `By` | Disk space in use |
| `boat.sandbox.io.pressure` | `1` | Share of time stalled on disk I/O, 0 to 1 |
| `boat.account.sandboxes.active` | `{sandbox}` | Sandboxes running now |
| `boat.account.sandboxes.limit` | `{sandbox}` | Sandboxes your plan lets run at once. Not sent on unlimited plans. |
| `boat.account.credit.balance` | `s` | Machine time left on the account. Not sent on unlimited plans. |
Each sandbox is one resource:
| Resource attribute | Value |
| - | - |
| `service.name` | `boat` |
| `service.instance.id`, `boat.sandbox.id` | The sandbox id |
| `boat.sandbox.name` | The sandbox name |
| `boat.sandbox.size` | The machine size |
| `boat.sandbox.memory.size`, `boat.sandbox.disk.size` | Total memory and disk, in bytes |
| `boat.account.id` | Your account id |
A sandbox sends points only while it runs. Each export holds the samples taken since the previous one.
## Events
Each [lifecycle event](/webhooks#events) is one OTLP log record. Boat puts the event name in two places: the event name field of the record, and the `event.name` attribute.
| Event name | Severity |
| - | - |
| `sandbox.ready` | `INFO` |
| `sandbox.hydrated` | `INFO` |
| `sandbox.error` | `ERROR` |
| `sandbox.archived` | `INFO` |
| `sandbox.degraded` | `WARN` |
| `sandbox.recovered` | `INFO` |
Each record has these attributes:
| Attribute | Value |
| - | - |
| `boat.sandbox.id`, `boat.sandbox.name` | The sandbox |
| `boat.sandbox.state`, `boat.sandbox.previous_state` | The new and the old state, when the event has them |
| `boat.sandbox.reason` | Why, for `sandbox.degraded` and `sandbox.recovered` |
| `boat.event.id` | The same id as the webhook event. Use it to remove duplicates. |
## Delivery and errors
| Collector answer | What Boat does |
| - | - |
| `2xx` | Done. A partial-success answer shows its message in `lastError`. |
| `429`, `502`, `503`, `504`, or no answer | Sends the same data again later. Boat waits for `Retry-After` when the collector sends it. |
| Any other `4xx` or `5xx` | Drops that data and shows the error in `lastError`. Fix the key or the endpoint. Boat sends the next window as usual. |
* Boat sends metrics in time order.
* After an outage, Boat sends at most the last 10 minutes of metrics.
* Boat retries an event like a [webhook delivery](/webhooks#delivery-and-retries), up to 8 attempts.
To read the status, run:
<CodeGroup>
```bash CLI theme={null}
boat telemetry
# https://otlp.datadoghq.com
# headers dd-api-key
# last export 2026-10-09T12:00:10.000Z
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/telemetry" \
-H "Authorization: Bearer $BOAT_API_KEY"
# {"type":"telemetry.info","telemetry":{"endpoint":"...","headers":["dd-api-key"],"lastExportAt":"...","lastError":null,...}}
```
```ts TypeScript theme={null}
const { telemetry } = await sandbox.getTelemetry();
console.log(telemetry?.lastExportAt, telemetry?.lastError);
```
```python Python theme={null}
status = sandbox.get_telemetry()
print(status.telemetry.last_export_at if status.telemetry else None)
```
</CodeGroup>
## Remove the endpoint
<CodeGroup>
```bash CLI theme={null}
boat telemetry unset
```
```bash curl theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/telemetry" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.deleteTelemetry();
```
```python Python theme={null}
sandbox.delete_telemetry()
```
</CodeGroup>
Boat stops the export. Boat deletes the queued data immediately.
## Related
* [Webhooks](/webhooks): the same lifecycle events, signed, to your own HTTPS endpoint.
* [Command history](/long-running-tasks/command-history): the output of the processes in a sandbox.
# Organizations & teams
Source: https://docs.boat.dev/organizations
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.
<video />
An organization is a team account. It has one plan, one balance, and members who run sandboxes on it.
| What | Who sees or uses it |
| - | - |
| Sandboxes the organization pays for | Every member sees them all. |
| Sandboxes that hold no personal logins | Every member can use them. |
| Snapshots and personal environments | Only the person who made them. |
| Organization environments and credential profiles | Every member uses them. Owners change them. See [Shared sandboxes](/organizations/shared-sandboxes#shared-environments-and-ai-credentials). |
## Members and invites
The owner invites people by email.
1. The person opens the link in the email.
2. The person signs in with any sign-in method.
3. The organization shows in their `boat org list` and in the **Viewing** dropdown of the dashboard.
<CodeGroup>
```bash CLI theme={null}
boat org create acme # you become its owner
boat org switch acme
boat org invite dana@example.com # owner only
boat org members # members and pending invites
boat org transfer dana # make dana the owner; you become a member
```
</CodeGroup>
To remove a member, change roles or set per-member caps, use the [Organization](https://boat.dev/dashboard?tab=org) tab of the dashboard. When a member leaves, the sandboxes that they created go back to their personal billing.
## Where to do what
| | CLI | API | SDKs | Dashboard |
| - | - | - | - | - |
| See your organizations | `boat org list` | `GET /orgs` | `listOrganizations` | **Viewing** dropdown |
| Set the active wallet | `boat org switch <org>` | `PATCH /orgs/active` | `setActiveOrganization` | sidebar **Active wallet > Change** |
| Bill one sandbox elsewhere | `boat --org acme new` | `org` on `POST /sandboxes`, or `X-Boat-Org` | `org` on `create` | change the active wallet |
| Create, transfer, delete | `boat org create` / `transfer` / `delete` | not available | not available | [Organization](https://boat.dev/dashboard?tab=org) |
| Members and invites | `boat org members` / `boat org invite` | not available | not available | [Organization](https://boat.dev/dashboard?tab=org) |
| Remove members, caps | not available | not available | not available | [Organization](https://boat.dev/dashboard?tab=org) |
| See and share team sandboxes | `boat list` / `boat share` | `GET /sandboxes` / `POST /sandboxes/{id}/share` | `sandboxes` / `share` | [Sandboxes](https://boat.dev/dashboard?tab=sandboxes), row menu |
| Org plan, extra time, auto-refill | `boat --org acme billing …` | `/billing/*` with `teamId` | not available | [Billing](https://boat.dev/dashboard?tab=billing) viewing the org |
Plans, credit packs and running out work the same on an organization as on a personal account. Read [Billing details](/billing).
## Learn more
<Columns>
<Card title="Which wallet a sandbox bills" icon="wallet" href="/organizations/active-wallet">
Set the active wallet, or bill one sandbox to another wallet.
</Card>
<Card title="Sandboxes your team shares" icon="users" href="/organizations/shared-sandboxes">
What each member can do with a sandbox. Share a sandbox that holds your logins.
</Card>
<Card title="Seats, limits and caps" icon="gauge" href="/organizations/seats-and-limits">
Buy seats, share start and concurrency limits, and cap each member.
</Card>
<Card title="Move a personal plan in" icon="right-left" href="/organizations/move-personal-plan">
Move your personal sandboxes and plan to the organization.
</Card>
</Columns>
# Which wallet a sandbox bills
Source: https://docs.boat.dev/organizations/active-wallet
Set the active wallet for your account, or bill one sandbox to an organization without switching.
Every account has one **active wallet**. It is your personal account until you change it.
* A new sandbox bills the wallet that the request names.
* A request that names no wallet bills the active wallet.
* The active wallet is one setting on the account. The dashboard, the CLI and a bare API key all bill the same place.
* `GET /limits` reads the wallet that a create would bill.
* Boat fixes the wallet of a sandbox when it creates the sandbox.
## Name an organization
| Value | Means |
| - | - |
| The id (`team_…`) | That organization. |
| The name, as `GET /orgs` / `boat org list` show it | That organization. Case does not matter. |
| `personal` | Your own account. |
You need the id only when two organizations have the same name. Then a name gives `409 ambiguous_org`.
## Set or override the wallet
<CodeGroup>
```bash CLI theme={null}
boat org # the wallet in effect right now
boat org list # organizations you belong to, ids and names
boat org switch acme # active wallet = acme, for the CLI, the dashboard and the API
boat org switch personal # back to your own account
boat --org acme new # bill one create to acme without switching
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/orgs" -H "Authorization: Bearer $BOAT_API_KEY"
# -> orgs: [{ id, name, type, role, active }, ...]
curl -sS -X PATCH "$BOAT_API_BASE/orgs/active" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{ "org": "acme" }' # or the team_… id, or "personal"
# one call elsewhere: header, query, or body
curl -sS -X POST "$BOAT_API_BASE/sandboxes" -H "X-Boat-Org: acme" ...
curl -sS "$BOAT_API_BASE/limits?org=acme" ...
curl -sS -X POST "$BOAT_API_BASE/sandboxes" -d '{ "org": "acme" }' ...
```
```ts TypeScript theme={null}
const { orgs } = await sandbox.listOrganizations(); // ids, names, active
await sandbox.setActiveOrganization({ org: "acme" });
await sandbox.create({ org: "acme" }); // one sandbox elsewhere
```
```python Python theme={null}
from boat_sdk.models.active_org_update_request import ActiveOrgUpdateRequest
from boat_sdk.models.create_sandbox_request import CreateSandboxRequest
orgs = sandbox.list_organizations().orgs # ids, names, active
sandbox.set_active_organization(ActiveOrgUpdateRequest(org="acme"))
sandbox.create(CreateSandboxRequest(org="acme")) # one sandbox elsewhere
```
</CodeGroup>
## In the dashboard
| Control | What it does |
| - | - |
| Sidebar, active wallet, **Change** | Sets the active wallet for the account. The CLI and the API follow. |
| **Viewing** dropdown at the top of a page | Changes only what that page shows. It opens on the active wallet. |
# Move a personal plan in
Source: https://docs.boat.dev/organizations/move-personal-plan
Move the sandboxes and plan you paid for personally to your organization, without stopping them.
Did you pay personally before the organization existed? Then do not cancel the personal plan by hand. The sandboxes that bill your personal account would stop with it. Move the plan instead.
When you move:
* Every sandbox billed to your personal account bills the organization from that moment.
* Your personal plan ends the same day.
* Boat refunds the unused share of the month to your card.
* Credit packs that you bought stay on your personal account.
<CodeGroup>
```bash CLI theme={null}
boat --org acme billing plan 20 --move-personal # first org plan, move included once it is paid
boat --org acme org migrate # org already on a plan
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/billing/move-to-org" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"teamId": "team_..."}'
```
</CodeGroup>
The dashboard offers the same move in two places:
* The Billing tab of the organization.
* The cancel-plan dialog of your personal plan.
# Seats, limits and caps
Source: https://docs.boat.dev/organizations/seats-and-limits
Buy organization seats, share the plan's start and concurrency limits, and cap each member's usage.
## Seats
An organization pays for the larger of two numbers:
* Its members.
* The seats that the owner bought.
You do not need one person or one email for each seat. To get more starts and concurrency without more people, set the seat count. Use the [Billing](https://boat.dev/dashboard?tab=billing) tab with the organization selected, or call the API:
```bash theme={null}
curl -X PUT https://boat.dev/api/boat/teams/acme/seats \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"seats": 5}'
```
| Change | Result |
| - | - |
| Raise the count | The organization card pays the prorated difference at once. If the card fails, the seat count does not change. |
| A member joins | The member takes an empty seat at no extra cost. |
| Lower the count | You get credit on the next invoice, not a card refund. You cannot go below the number of members. |
## Shared limits
The start-rate and concurrency numbers of the plan are **one shared pool for the whole organization**. Boat multiplies them by the number of seats.
Example: a 5-seat organization on the \$20 plan gets:
| Limit | Value |
| - | - |
| Concurrent sandboxes | 500 |
| Starts per minute | 60 |
| Starts per hour | 300 |
| Starts per day | 1000 |
* If one member uses all of the hourly start budget, Boat refuses every other member's `new`, `fork` and `resume` billed to the organization. This lasts until the window rolls.
* Personal sandboxes use the member's own personal limits.
* The seat multiplier applies only while the organization's plan is active. Without a plan, remaining credit packs still run sandboxes, at the limits of a single seat.
## Per-member caps
One shared balance means one member can spend all of it. So the owner can cap each member on the [Organization](https://boat.dev/dashboard?tab=org) tab. Both caps are unlimited by default.
| Cap | Limits |
| - | - |
| Usage cap | That member's organization-billed machine time per billing window |
| Concurrent sandboxes | How many organization-billed sandboxes that member can run at once |
* Caps apply only to organization-billed sandboxes.
* A sandbox counts against the caps of its **creator**. This is also true when a teammate resumes it.
| Over the cap | `new`, `fork` and `resume` answer |
| - | - |
| Usage cap | `402 team_member_cap_reached` |
| Concurrent-sandbox cap | `429 member_limit_reached` |
In both cases, Boat snapshots and stops the member's organization sandboxes within about a minute. Nothing is lost. The sandboxes can resume again when the owner raises the cap or the billing window renews.
# Sandboxes your team shares
Source: https://docs.boat.dev/organizations/shared-sandboxes
Every member sees the sandboxes the organization pays for. What each member can do with them, and how to share a sandbox that holds your logins.
In the scope of an organization, `boat list`, `GET /sandboxes` and the dashboard show two sets of sandboxes:
* Your own sandboxes.
* **Every sandbox the organization pays for**, whoever created it.
Each sandbox shows who created it (`createdBy`) and what you can do with it (`access`).
## Access levels
| `access` | Who | What you can do |
| - | - | - |
| `owner` | You created it | Everything |
| `use` | A teammate's sandbox that holds none of their personal logins | Open it, SSH, run commands, read and write files, prompt its agent, open ports, resume and stop it |
| `view` | A teammate's sandbox that still holds their personal logins | See it, its usage, and stop it |
## Why `view` exists
A sandbox can get these from its creator, when its environment passes them:
* GitHub token.
* Claude and Codex logins.
* Environment secrets.
Anyone with a shell in that sandbox could act as that person. So a teammate gets a shell only when none of these are on the sandbox.
A sandbox created with `--no-env` is `use` for every member from the start. So is a sandbox created on an environment that passes nothing: marked [safe for third parties](/environments/access#safe-for-third-parties) without the AI credentials proxy, or with every section turned off. Such a sandbox never receives personal logins later: an environment upgrade skips it, and a resume or fork onto an environment that passes logins returns `409 environment_passes_logins`. Pick this setup for agents that the whole team runs. Give these agents the team's own model keys with `--env`. Do not give them the logins of one person.
## Share a sandbox that holds your logins
The creator of the sandbox runs `share`. Then:
* Boat never sends the creator's GitHub token, model logins, secret files or the sandbox's own CLI key to it again. The sandbox becomes `noEnv`.
* Boat deletes these from its disk when the sandbox next starts.
* Files and installs stay.
* You cannot undo a share.
A sandbox that runs when you share it still has your logins in the memory of its programs. It stays `view` for your team until you stop it and resume it. The response then shows `restartRequired: true`.
<CodeGroup>
```bash CLI theme={null}
boat org switch acme # the org's scope: boat list shows its sandboxes too
boat list
# bx_7k2m9qpd running 2h 10m research-agent [org: acme] by alex view only: holds alex's logins
# bx_4tr8wz3c running - support-agent [org: acme] by alex
boat stop bx_7k2m9qpd # alex, the creator
boat share bx_7k2m9qpd
boat resume bx_7k2m9qpd # comes back without alex's logins: every member can use it
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/sandboxes" -H "Authorization: Bearer $BOAT_API_KEY" -H "X-Boat-Org: acme"
# -> sandboxes: [{ id, name, state, createdBy, access, holdsCreatorLogins, team, ... }]
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_7k2m9qpd/share" -H "Authorization: Bearer $BOAT_API_KEY"
# -> { sandbox: { ... }, restartRequired: true } when it was running: stop + resume it
```
```ts TypeScript theme={null}
const { sandboxes } = await sandbox.sandboxes({ org: "acme" });
for (const s of sandboxes) console.log(s.name, s.createdBy, s.access);
await sandbox.share({ sandboxId: "bx_7k2m9qpd" }); // creator only
```
```python Python theme={null}
page = sandbox.sandboxes(org="acme")
for s in page.sandboxes:
print(s.name, s.created_by, s.access)
sandbox.share(sandbox_id="bx_7k2m9qpd") # creator only
```
</CodeGroup>
## In the dashboard
| Row label | Means |
| - | - |
| **by alex** | A teammate, alex, created this sandbox. |
| **view only** | The sandbox still holds alex's logins. |
| **private** | Your own sandbox, not shared yet. To share it, pick **Share with org** in the row menu. |
## Errors
| Error | When |
| - | - |
| `403 sandbox_private` | A teammate tries to use a `view` sandbox. The error names whose logins the sandbox holds. |
| `403 owner_only` | A teammate tries an action that stays with the creator. |
These actions stay with the creator:
* Fork.
* Delete.
* Change its settings: name, subdomain, auto-stop.
* Any stop that deletes data: `--force`, or any stop of a sandbox with snapshots off. The organization owner can also do this.
## Shared environments and AI credentials
Give the team's sandboxes the team's own model keys, not a person's logins.
| | Members | Owners |
| - | - | - |
| [Organization environments](/environments/named-environments#organization-environments) (`?org=` on environment routes, `boat env --org`) | Read and use | Owners and admins change them |
| [Organization credential profiles](/ai-credentials#organization-profiles) | Use | Create and change |
| [AI credentials proxy](/ai-credentials#the-ai-credentials-proxy) switch of the organization | See | Turn on or off |
<CodeGroup>
```bash CLI theme={null}
boat --org acme ai profile new team-claude
echo "$ANTHROPIC_API_KEY" | boat ai profile set-key team-claude anthropic-api-key
boat --org acme ai proxy on
boat env new agents --org acme
boat env set agents --org acme --credential-profile team-claude
boat --org acme new --environment agents
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/credential-profiles" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"team-claude","org":"acme"}'
curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID?org=acme" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"credentialProfileId":"team-claude"}'
```
```ts TypeScript theme={null}
await sandbox.createCredentialProfile({ name: "team-claude", org: "acme" });
await sandbox.updateEnvironment({ environmentId: envId, org: "acme", credentialProfileId: "team-claude" });
```
```python Python theme={null}
from boat_sdk.models.create_credential_profile_request import CreateCredentialProfileRequest
from boat_sdk.models.update_sandbox_environment_request import UpdateSandboxEnvironmentRequest
sandbox.create_credential_profile(CreateCredentialProfileRequest(name="team-claude", org="acme"))
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(credential_profile_id="team-claude"), org="acme")
```
</CodeGroup>
A sandbox billed to the organization can name an organization environment. When the creator has an environment of the same name, the creator's own environment wins.
# Build a Platform on Boat
Source: https://docs.boat.dev/platform-guide
Run your users' agents, previews, and workspaces on Boat: architectures, costs, and provisioning patterns.
<video />
This guide is for builders of products like Lovable, Devin, or agent platforms. In these products, your product makes a sandbox for each of your own users.
The [Terms of Service](https://boat.dev/terms#tos-8) allow this, and you do not need our approval. You are responsible for what your users do in their sandboxes.
Such a platform needs:
* Persistent files and context for each user or project.
* An agent that works inside the workspace and can debug anything. Each sandbox has five. See [Integrated agents](/integrated-agents).
* A private preview URL of what the user builds.
* A controlled sandbox cost for each user.
In all cases, you run your own backend and database. You control Boat through the [API](/api/v1) or the [SDKs](/sdks/overview).
## The two rules
1. **Always create user sandboxes with `--no-env`** (`noEnv: true`). A no-env sandbox gets none of the secrets or credentials of your account. It cannot act on your account or on other sandboxes. Give the sandbox what it needs explicitly with `--env`. See [No-env sandboxes](/environments#safe-for-third-parties).
2. **Tag each sandbox** with per-sandbox environment variables. Your backend then knows which sandbox is which.
<Tip>
You do not have to remember `--no-env` on every call. Mark an environment as safe for third parties once, and use it for your user sandboxes. Every sandbox that uses it then gets the same protection. The protection stays after forks and resumes, and your backend does not pass a flag.
```bash theme={null}
boat env new users
boat env set users --safe-for-third-parties true
boat new --environment users --env TENANT_ID=acme
```
See [Environments](/environments).
</Tip>
<CodeGroup>
```bash CLI theme={null}
boat new --no-env --no-auto-stop --env TENANT_ID=acme
```
```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,"noEnv":true,"env":{"TENANT_ID":"acme"}}'
```
```ts TypeScript theme={null}
await sandbox.create({ ttlSeconds: null, noEnv: true, env: { TENANT_ID: "acme" } });
```
```python Python theme={null}
sandbox.create(CreateSandboxRequest(ttl_seconds=None, no_env=True, env={"TENANT_ID": "acme"}))
```
</CodeGroup>
Wait for the sandbox to reach `ready` or `idle` before you run commands in it. Boat enforces this:
| When you send a command | Boat answers |
| - | - |
| While the sandbox provisions | A retryable 409 `sandbox_starting` error |
| Earlier in provisioning | 409 `machine_not_running` |
Do not race the start. A command sent too early also runs before Boat applies your `env`.
## Choose a pattern
| Pattern | Isolation | Cost | Use it when |
| - | - | - | - |
| [1. One always-on sandbox per project](/platform-guide/patterns#pattern-1-one-always-on-sandbox-per-project) | Full | About \$26/month per project on `default` | The project has real traffic, or the user pays enough to cover it. |
| [2. One always-on sandbox per user](/platform-guide/patterns#pattern-2-one-always-on-sandbox-per-user) | Projects of one user share a machine | About \$26/month per user | A user has up to 5 to 10 fullstack projects. |
| [3. Stop and resume around usage](/platform-guide/patterns#pattern-3-stop-and-resume-around-usage) | Full | \$1 to \$5 per month for a typical user | Most platforms end up here. |
## Learn more
<Columns>
<Card title="Patterns" icon="diagram-project" href="/platform-guide/patterns">
Three ways to run sandboxes for your users, with costs, delete and refused stops.
</Card>
<Card title="Agents in your product" icon="robot" href="/platform-guide/agents">
Use the integrated agents, or bring your own harness with a daemon.
</Card>
<Card title="Templates and sizing" icon="layer-group" href="/platform-guide/templates-and-sizing">
Build your stack once and fork it for each user. Plan concurrency and start limits.
</Card>
</Columns>
## Related
* [Integrated agents](/integrated-agents)
* [Environments](/environments)
* [Pricing](/pricing)
* [Billing details](/billing)
* [Snapshots](/snapshots)
* [Hosting](/hosting)
* [FAQ](/faq)
# Agents in your product
Source: https://docs.boat.dev/platform-guide/agents
Use the integrated agents in your product, or bring your own harness with a daemon in the sandbox.
## Use the integrated agents
Before you write an agent loop, look at what the sandbox already runs.
* `boat prompt` drives five coding agents: Claude Code, Codex, pi, OpenCode and Prime Agent.
* It has memory, parallel conversations, streaming events and a model choice for each prompt.
* For most platforms, it replaces the [daemon](#bring-your-own-harness-the-daemon-pattern).
[Integrated agents](/integrated-agents) explains how it works and every way to customize it. These tips matter when you build a product on it:
* **Use your user's key, not yours.** Create the sandbox with `--no-env`. Pass the user's key as a per-sandbox variable: `-e ANTHROPIC_API_KEY=…`, `-e OPENAI_API_KEY=…`. Every harness reads it. Nothing of your account is on the sandbox. Keys are per sandbox. So users whose keys must stay apart get their own sandbox ([patterns 1 and 3](/platform-guide/patterns)). A sandbox that you pay for can serve many users through conversations ([pattern 2](/platform-guide/patterns#pattern-2-one-always-on-sandbox-per-user)).
* **Use one conversation for each user session.** `POST /prompt` with `new: true` returns a `conversationId`. Store it with the session. Send it back as `conversationId` with each later message. Conversations run in parallel on one sandbox, and each one has its own memory. They stay after a stop and resume. So pattern 3 works without changes: resume the sandbox, then prompt the same conversation.
* **Add an agent and model picker.** A selector in your UI maps directly to the `provider` and `model` fields of `POST /prompt`. A switch in the middle of a conversation keeps the history. Users can change their choice for each message.
* **Stream to your UI.** `GET /events` with a cursor gives structured events for prompts, responses and tool calls. Each event has its `conversationId`. Filter with `conversation` to show each user only their own session.
* **Add a stop button.** `POST /interrupt` with `conversation` stops the turn of one user. The other conversations keep running.
* **Add house rules, tools and MCP servers.** The agents read usual config files from the sandbox home: `AGENTS.md`, `CLAUDE.md`, MCP registrations and skills. Put yours in the [template](/snapshots/templates) once, and every fork starts with them. Put per-user rules in the prompt or in per-user sandboxes. See [Customize the harness](/integrated-agents/customize).
* **Send attachments.** `boat prompt --attach` puts the user's files under `~/attachments` on the sandbox. It sends images inline to vision models. From a backend, write the file with the [file endpoint](/api/reference/agent/write-sandbox-file), and give its path in the prompt.
## Bring your own harness: the daemon pattern
You do not have to use the integrated agents. Your harness can run in your own infrastructure, or you can want full control of the agent loop. Then put a small HTTP daemon in the sandbox and talk to it directly:
1. **Install it.** Copy the binary in with `boat scp`, or put it in your [template](/snapshots/templates).
2. **Keep it alive.** Run it as an [always-on systemd service](/long-running-tasks/always-on-services#run-an-always-on-service). It then survives stop, resume and fork.
3. **Expose it.** `host <port> --private` gives it a stable HTTPS URL that a `_token` protects. Use that token as the credential of the daemon. Store it in your backend.
4. **Drive it** from your backend over plain HTTPS. Your harness sends work. The daemon runs it with full access to the machine and streams the results back.
### Without a daemon
You can also work without a daemon:
| Task | Endpoint |
| - | - |
| Run any command in the sandbox | [`POST /sandboxes/{sandboxId}/commands`](/api/reference/agent/execute-sandbox-command) |
| Read and write data | File endpoints: [read](/api/reference/agent/read-sandbox-file), [write](/api/reference/agent/write-sandbox-file) |
| Lifecycle, prompts, events, desktop, snapshots | Dedicated endpoints |
| In-sandbox tools such as `host` | Run their commands through the commands endpoint |
A daemon is useful when you need streaming, concurrency, or less latency than one-shot commands give.
# Patterns
Source: https://docs.boat.dev/platform-guide/patterns
Three ways to run sandboxes for your users: always on per project, always on per user, or stop and resume around usage.
## Pattern 1: one always-on sandbox per project
This pattern is the simplest, and each project is fully isolated.
1. Make a sandbox for each user project with `--no-auto-stop`.
2. Clone or copy the user's code into it.
3. Run the user's dev server.
4. Expose the dev server.
<CodeGroup>
```bash CLI theme={null}
boat ssh <id> "cd ~/project && npm run dev -- --host 0.0.0.0 --port 3000 &"
boat ssh <id> "host 3000 --private"
# prints https://<subdomain>-3000.on.boat.dev?_token=...
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/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":"project"}'
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"host 3000 --private"}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId,
command: "npm run dev -- --host 0.0.0.0 --port 3000 &", cwd: "project",
});
const hosted = await sandbox.command({ sandboxId, command: "host 3000 --private" });
console.log(hosted.stdout); // https://<subdomain>-3000.on.boat.dev?_token=...
```
```python Python theme={null}
sandbox.command(sandbox_id, CommandRequest(
command="npm run dev -- --host 0.0.0.0 --port 3000 &",
cwd="project",
))
hosted = sandbox.command(sandbox_id, CommandRequest(command="host 3000 --private"))
print(hosted.stdout) # https://<subdomain>-3000.on.boat.dev?_token=...
```
</CodeGroup>
* Only the people you give the `_token` URL to can open it.
* The preview stays up while the sandbox runs.
| Size | Cost when it runs 24/7 |
| - | - |
| `default` | About \$26/month (\$0.00001 per second) |
| `large` | Two times the `default` cost |
Use this pattern when the project has real traffic, or when the user pays you enough to cover the cost.
## Pattern 2: one always-on sandbox per user
This pattern is like pattern 1. The difference is that one sandbox holds all the projects of one user.
* Each project has its own folder and its own port.
* You install a small daemon in the sandbox. It multiplexes the agent sessions.
* This works well for up to 5 to 10 fullstack projects per user.
The cost is about \$26/month for each user, not for each project. Be careful with isolation: the projects of one user share a machine.
## Pattern 3: stop and resume around usage
This pattern is the cheapest, and each sandbox is isolated. Most platforms end up with it. The sandbox runs only while the user works.
1. The user sends a message.
2. If the sandbox of the user is stopped, run `boat resume` on it. This takes a few seconds.
3. At the same time, start your daemon and the preview again.
4. Send the message to the agent.
5. When the agent finishes, wait a short countdown.
6. Run `boat stop`. The stop makes a snapshot of the file system and pauses billing.
| After a stop and resume | Comes back? |
| - | - |
| Files | Yes |
| Installed packages | Yes |
| Enabled systemd services | Yes |
| Processes you started by hand | No. Your daemon starts them again, or [run it as an always-on service](/long-running-tasks/always-on-services#run-an-always-on-service). |
See [Snapshots](/snapshots).
### When the user is done for good
A stop is a pause. A **delete** is the end.
* To delete, use `DELETE /sandboxes/{sandboxId}`, `boat delete`, or the `⋯` menu in the dashboard.
* A delete force-stops the sandbox. It permanently deletes the snapshots that only this sandbox uses.
* Boat keeps snapshot data that a fork, a resume or a named template still reads.
* You cannot undo a delete. You cannot resume the sandbox after it.
Connect delete to an explicit "delete my project" action. Never connect it to an idle timeout. If the user can come back, stop the sandbox instead.
See [Snapshots](/snapshots/download-and-delete#delete-a-sandbox).
### When a stop is refused
A stop saves the disk of the sandbox first. If that save fails, Boat **refuses the stop**. The sandbox keeps running, so the user does not lose work.
**You do not pay for that time.** The meter pauses by itself from the first failed attempt. A stuck sandbox never shows on your invoice, and you have nothing to claim back. See [When a stop is refused](/snapshots/stop#when-a-stop-is-refused).
What your backend sees:
1. Treat a refused stop as retryable, not as fatal.
2. The stop stays pending. Boat retries it until a save succeeds.
3. Then the sandbox stops by itself.
4. Boat also sends an email to the sandbox owner.
To stop the sandbox now, pass `force`.
* The sandbox stops with its last successful snapshot.
* Everything written after that snapshot is lost.
* You cannot undo it. Offer it only after a stop has already failed.
* Without `force`, the sandbox stops this way by itself after 3 days of failed saves. Boat sends an email to the owner before that.
<CodeGroup>
```bash CLI theme={null}
boat stop bx_23456789 --force
```
```bash curl theme={null}
curl -sS -X POST "https://boat.dev/api/v1/sandboxes/bx_23456789/stop" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"force":true}'
```
```ts TypeScript theme={null}
await sandbox.stop({ sandboxId: "bx_23456789", force: true });
```
```python Python theme={null}
sandbox.stop(sandbox_id="bx_23456789", stop_request=StopRequest(force=True))
```
</CodeGroup>
### Cost
| | Cost |
| - | - |
| \$1 buys | About 27 hours of `default` machine time, or half that on `large` |
| Typical user | \$1 to \$5 per month |
| Power user | \$10 to \$20 per month |
To charge this cost to your users, read the meter of each sandbox for the billing period.
* Use `GET /sandboxes/{sandboxId}/usage`, or `boat usage <id>`.
* It works on running and stopped sandboxes.
* It counts exactly what Boat charged your balance for that sandbox.
See [Per-sandbox usage](/billing#per-sandbox-usage).
### Two improvements
* **No preview downtime.** Publish successful builds to a static host or a CDN. The sandbox is only for the agent and the dev preview. Production traffic never depends on a running sandbox.
* **No agent latency.** Run a copy of the agent without tools on your own server. It answers immediately and stalls while the sandbox resumes. For a working implementation, see [optibox](https://github.com/ariana-dot-dev/optibox).
# Templates and sizing
Source: https://docs.boat.dev/platform-guide/templates-and-sizing
Build your stack once and fork it for each user. Plan concurrent sandboxes and start limits.
## Provision from a template
Do not install your stack on a new sandbox for each user. Build it once, then fork it:
1. Create a sandbox. Install the runtimes, the dependencies and your daemon.
2. Stop it. Its snapshot is now your template.
3. Fork the template for each user. This takes a few seconds.
<CodeGroup>
```bash CLI theme={null}
boat new # install runtimes, deps, your daemon
boat stop <template-id> # its snapshot is now your template
boat fork <template-id> --no-env # per user, a few seconds
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/<template-id>/fork" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"noEnv":true,"env":{"TENANT_ID":"acme"}}'
```
```ts TypeScript theme={null}
const forked = await sandbox.fork({
sandboxId: templateId,
noEnv: true, env: { TENANT_ID: "acme" },
});
```
```python Python theme={null}
forked = sandbox.fork(template_id, ForkRequest(no_env=True, env={"TENANT_ID": "acme"}))
```
</CodeGroup>
* The per-fork `env` replaces the per-sandbox variables that the fork gets from the source. This is the same in the CLI (`boat fork <id> -e KEY=V`), the API and the SDKs.
* A fork gets the whole file system of the template.
* A fork is usable in seconds, at an almost constant cost, whatever the template holds.
* A fork always uses the latest snapshot of the template.
To update the template:
1. Resume it.
2. Change it.
3. Stop it again.
See [Template Sandboxes](/snapshots/templates).
## Sizing
The number of concurrent sandboxes follows your daily active users, not your signups. A rough rule from platforms on Boat:
| Signups | Active users on an average day | Concurrent sandboxes |
| - | - | - |
| 10,000 | About 100 | 10 to 100 |
On a launch day, the peak is several times higher.
Plan against two different limits:
| Limit | What it controls |
| - | - |
| Concurrent-sandbox cap of your plan | How many sandboxes exist at the same time |
| Machine start limits | How fast you can start them |
Create, fork and resume each count as one start. So pattern 3 uses starts each time a user comes back, not only at signup. See [Pricing](/pricing#concurrency).
# Pricing & Limits
Source: https://docs.boat.dev/pricing
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.
<video />
You pay for machine time, per second, only while a sandbox runs. A stopped sandbox costs nothing.
Storage is also free:
* Automatic snapshots keep the disk of a stopped sandbox. They cost nothing and have no count limit.
* [Named snapshots](/snapshots/templates#automatic-and-named-snapshots) are free up to 10. Each one after that costs \$1.70 a month.
One option costs extra: the [AI credentials proxy](/ai-credentials#pricing), which keeps your real AI keys out of your sandboxes. It costs \$1 for each day it is on, plus \$1 per 1,000 proxied requests, paid in Boat time.
## Price
| Size | Per hour | CPU | RAM | Disk |
| - | - | - | - | - |
| `small` | **\$0.018** | 2 vCPU | 4 GB | 12 GB |
| `default` | **\$0.036** | 4 vCPU | 8 GB | 50 GB |
| `large` | **\$0.072** | 8 vCPU | 16 GB | 125 GB |
| `xlarge` \* | **\$0.200** | 16 vCPU | 32 GB | 251 GB |
* "Disk" is the space for your own files. The OS and the pre-installed tools are not in it.
* One `default` sandbox that runs a full month (730 h) costs \$26.
* Every size is a full Linux VM with the same tools, snapshots, hosting and desktop. Only the machine changes.
\* `xlarge` needs the \$100 plan or higher. Subscribe from [Dashboard > Billing](https://boat.dev/dashboard?tab=billing), then pass `--type xlarge`. You do not need to contact us.
Pick the size when you create a sandbox. Change it when you resume or fork:
```bash theme={null}
boat new --type small
boat resume bx_23456789 --type large
```
## Concurrency
A plan sets how many sandboxes you can **run at once**. The plan price is not a fee. Every dollar comes back as sandbox time at the rates above. Example: the \$20 plan gives \$20 of time (555 hours of `default`) and the right to run 100 sandboxes at the same time.
| Plan | Run at once | Time included | Starts per min / hour / day |
| - | - | - | - |
| \$20/mo | 100 | \$20 worth (555 h of `default`) | 12 / 60 / 200 |
| \$100/mo | 300 | \$100 worth (2,777 h of `default`) | 30 / 210 / 840 |
| \$500/mo | 1,000 | \$500 worth (13,888 h of `default`) | 65 / 420 / 1,680 |
| \$2000/mo | 2,000 | \$2000 worth (55,555 h of `default`) | 90 / 600 / 2,400 |
* Boat grants the included time each month. It expires at the end of the month.
* For more time in a month, buy **credit packs** or turn on **auto-refill**. A pack costs \$20, uses the same rates and never expires.
* Boat spends plan time first, then packs.
* Concurrency and start limits are per plan. On an organization, Boat multiplies them by the number of seats.
* **Trial**: 25 free hours, 2 sandboxes at once, `small` and `default` only. The trial lasts until your first payment.
Change plans from [Dashboard > Billing](https://boat.dev/dashboard?tab=billing) or with `boat billing plan 100`. Upgrades are prorated and start at once.
## Compared to others
<img alt="One default sandbox per hour, boat versus other sandbox providers" />
<img alt="One default sandbox per hour, boat versus other sandbox providers" />
This table prices the same machine on every provider, at their public list prices. The sizes are the ones in the table above.
| \$/hour | `small` | `default` | `large` | `xlarge` |
| - | - | - | - | - |
| **boat** | **\$0.018** | **\$0.036** | **\$0.072** | **\$0.200** |
| Novita | \$0.117 (6x) | \$0.233 (6x) | \$0.467 (6x) | \$0.933 (5x) |
| Freestyle | \$0.132 (7x) | \$0.264 (7x) | \$0.529 (7x) | \$1.06 (5x) |
| exe.dev † | \$0.140 (8x) | \$0.280 (8x) | \$0.560 (8x) | \$1.12 (6x) |
| E2B | \$0.166 (9x) | \$0.331 (9x) | \$0.662 (9x) | \$1.32 (7x) |
| Daytona | \$0.166 (9x) | \$0.331 (9x) | \$0.662 (9x) | \$1.32 (7x) |
| Blaxel † | \$0.166 (9x) | \$0.331 (9x) | \$0.662 (9x) | \$1.32 (7x) |
| Cloudflare † | \$0.180 (10x) | \$0.360 (10x) | \$0.720 (10x) | \$1.44 (7x) |
| AWS AgentCore † | \$0.217 (12x) | \$0.434 (12x) | \$0.867 (12x) | \$1.73 (9x) |
| Islo | \$0.300 (17x) | \$0.600 (17x) | \$1.20 (17x) | \$2.40 (12x) |
| Deno Sandbox † | \$0.300 (17x) | \$0.600 (17x) | \$1.20 (17x) | \$2.40 (12x) |
| Fly.io Sprites † | \$0.315 (18x) | \$0.630 (18x) | \$1.26 (18x) | \$2.52 (13x) |
| Runloop | \$0.317 (18x) | \$0.634 (18x) | \$1.27 (18x) | \$2.53 (13x) |
| Vercel Sandbox † | \$0.341 (19x) | \$0.682 (19x) | \$1.36 (19x) | \$2.73 (14x) |
| Modal | \$0.380 (21x) | \$0.760 (21x) | \$1.52 (21x) | \$3.04 (15x) |
| Railway † | \$0.417 (23x) | \$0.833 (23x) | \$1.67 (23x) | \$3.33 (17x) |
† exe.dev: Cloud Pool rate; Cloudflare: active CPU only; Vercel Sandbox: active CPU only; Blaxel: CPU included in the RAM price; Railway: active CPU and used RAM only; Fly.io Sprites: active CPU and used RAM only; AWS AgentCore: active CPU and used RAM only; Deno Sandbox: active CPU only.
### "Active CPU" billing
Some providers bill only the CPU time that your code uses. They bill RAM in addition. Some bill the RAM that you reserve. Others (‡) bill the RAM in use. Their claim is "you will rarely max the box". This is what it means for you:
* **You cannot know the price before you run.** The same job costs a different amount each time. Builds, test suites, browsers and agents use mostly CPU.
* **RAM bills while you are idle.** Reserved or in use, you pay for it every second that the sandbox runs.
* **They do not publish what their users use.** So you cannot check what "rarely max the box" saves you.
The table above prices them at full use. That is the only rate they publish. boat has one price per size, per hour. You know it before you run anything.
We publish our usage. This table shows how much CPU and RAM boat sandboxes used over the last 30 days. Each column prices that usage at the list rates of one provider.
<img alt="One default sandbox per hour at real boat usage, boat versus active-CPU providers" />
<img alt="One default sandbox per hour at real boat usage, boat versus active-CPU providers" />
| Sandbox | **boat** | AWS AgentCore ‡ | Cloudflare | Fly.io Sprites ‡ | Railway ‡ | Vercel Sandbox | Deno Sandbox |
| - | - | - | - | - | - | - | - |
| quietest 1%: CPU 0.37% busy, RAM 14.77% used | **\$0.036** | \$0.012 (0.3x) | \$0.073 (2.0x) | \$0.053 (1.5x) | \$0.083 (2.3x) | \$0.171 (5x) | \$0.201 (6x) |
| median: CPU 8.79% busy, RAM 18.89% used | **\$0.036** | \$0.046 (1.3x) | \$0.097 (2.7x) | \$0.091 (2.5x) | \$0.129 (4x) | \$0.215 (6x) | \$0.235 (7x) |
| average: CPU 11.11% busy, RAM 22.97% used | **\$0.036** | \$0.057 (1.6x) | \$0.104 (2.9x) | \$0.112 (3x) | \$0.158 (4x) | \$0.226 (6x) | \$0.244 (7x) |
| busiest 1%: CPU 92.06% busy, RAM 36.1% used | **\$0.036** | \$0.357 (10x) | \$0.337 (9x) | \$0.384 (11x) | \$0.456 (13x) | \$0.641 (18x) | \$0.568 (16x) |
‡ bills RAM used, not RAM reserved.
A sandbox that is almost idle can cost less with a provider that bills only busy CPU and used RAM. From the median sandbox up, boat is the cheapest.
Are your sandboxes idle most of the time? Then stop them, and resume them when work arrives. Use `boat stop` / `boat resume`, or the API. A stopped sandbox costs nothing and keeps its disk.
## Performance
<video />
We ran the [hpc-sandbox-benchmarks](https://github.com/AnicetNgrt/hpc-sandbox-benchmarks) suite on the 4 vCPU / 8 GB machine of every provider. This is our `default` size. The main job is a Node.js build and test loop: bundle, lint, test, repeat. For the full results, read the [2026-08-24 leaderboard](https://github.com/AnicetNgrt/hpc-sandbox-benchmarks/blob/provider/ascii-box/docs/results/2026-08-24-cpu/leaderboard.md).
<img alt="The same Node.js build and test loop, 1,000 runs, time it takes per provider" />
<img alt="The same Node.js build and test loop, 1,000 runs, time it takes per provider" />
| 4 vCPU / 8 GB | Runs per second | Seconds per 1,000 runs | \$/hour | \$ per million runs |
| - | - | - | - | - |
| **boat** | **27.7** | **36** s | **\$0.036** | **\$0.36** |
| Daytona | 18.6 | 54 s (1.5x slower) | \$0.331 | \$4.95 (14x) |
| Vercel Sandbox | 13.0 | 77 s (2.1x slower) | \$0.682 | \$14.61 (40x) |
| E2B | 11.2 | 89 s (2.5x slower) | \$0.331 | \$8.19 (23x) |
| Freestyle | 9.6 | 104 s (2.9x slower) | \$0.264 | \$7.62 (21x) |
| Modal † | 9.6 | 105 s (2.9x slower) | \$0.760 | \$22.07 (61x) |
That boat row is our standard machine, where sandboxes normally run. When standard capacity is temporarily exhausted, a sandbox falls back to an older Hetzner cloud VM at the same price; that fallback did 8.9 runs per second in the same run (113 s per 1,000, \$1.13 per million).
† Modal: default runtime, cpu=4 in Modal units (the guest sees 4 CPUs; billed as 4 Modal cores) + 8 GiB. Its beta VM runtime did 15.1 runs per second. Priced as Modal bills that machine.
Measured on 2026-09-29: Vercel Sandbox · 2026-08-24: boat, Freestyle · 2026-07-23: Daytona, Modal, E2B. Rows from different runs are indicative, not a like-for-like race.
* The boat row is our standard machine: AMD Ryzen 9 9950X hosts, called "baremetal" internally. Each sandbox is still a full VM.
* We measured it with the same suite on 2026-08-24.
* Values are medians over several machines per provider. The 95% intervals are within ±20% of the medians.
## Worked examples
| You run | Per month |
| - | - |
| One `default` sandbox, 8 hours a day, 22 days | 176 h × \$0.036 = **\$6.34**, covered by the \$20 plan |
| One `default` sandbox 24/7 | 730 h × \$0.036 = **\$26**: the \$20 plan plus one \$20 pack |
| 50 `default` sandboxes, 4 hours a day, 22 days | 4,400 h × \$0.036 = **\$158**: the \$100 plan (300 at once) plus three packs |
| 200 `small` sandboxes, 1 hour each, once | 200 h × \$0.018 = **\$3.60**, covered by any plan |
## For the API
`GET /limits` reports balances as **seconds of `default` time**. One dollar is 100,000 of these seconds.
| Size | Balance seconds used per second of run time |
| - | - |
| `small` | 0.5 |
| `default` | 1 |
| `large` | 2 |
| `xlarge` | 5.56 |
* `creditBalanceHours` and `packBalanceDollars` give the same balance in hours and in dollars.
* `boat usage <id>` and `GET /sandboxes/{id}/usage` give the bill of one sandbox. The size is already applied.
For what happens when you run out, read [Billing details](/billing). For team plans and caps, read [Organizations & teams](/organizations).
# Quickstart
Source: https://docs.boat.dev/quickstart
Install Boat and start your first cloud sandbox in two minutes.
<video />
## 1. Install
<CodeGroup>
```bash macOS / Linux theme={null}
curl -fsSL https://boat.dev/install | sh
```
```powershell Windows theme={null}
irm https://boat.dev/install.ps1 | iex
```
</CodeGroup>
The installer does these steps:
1. It opens your browser to sign you in. Use GitHub, Google, or a code that Boat sends by email.
2. It asks if the sandboxes are for you or for your users.
3. It opens checkout for a plan. Each plan starts with a free 7-day trial.
Go back to the terminal. You can now start a sandbox.
## 2. Start a sandbox
```bash theme={null}
boat new
```
| Property | Value |
| - | - |
| Type | Full Linux virtual machine |
| Size | 4 vCPU, 8 GB |
| Installed | Docker, Node, Python, Go, Rust and the usual coding agents |
| Auto-stop | After one hour, unless you set a different time |
## 3. Use it
```bash theme={null}
boat ssh # a shell inside
boat prompt "add tests" # run Claude Code or Codex inside it
boat stop # snapshot and pause billing; boat resume brings it back
```
Each command takes the sandbox id. Use `current` for the sandbox that you started last.
## From code
Do the same steps over HTTP. You need an [API key](/api-keys).
<CodeGroup>
```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({ 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>
## Next
<CardGroup>
<Card title="Pricing" icon="tag" href="/pricing">
The cost per hour of each size, and what a plan gives you.
</Card>
<Card title="Build a platform on Boat" icon="layer-group" href="/platform-guide">
Give each user or agent a sandbox of their own.
</Card>
<Card title="Environments" icon="key" href="/environments">
The repositories, secrets and credentials that each new sandbox starts with.
</Card>
<Card title="Long-running tasks" icon="clock" href="/long-running-tasks">
Keep a sandbox up for days. Resume and fork it.
</Card>
<Card title="Accounts & sign-in" icon="user" href="/account">
Sign-in methods, a second computer, and which surface does what.
</Card>
<Card title="API & SDKs" icon="brackets-curly" href="/api/v1">
Auth, envelopes, errors, and the typed Python and TypeScript clients.
</Card>
</CardGroup>
# Boat SDKs
Source: https://docs.boat.dev/sdks/overview
Use Boat from Python and TypeScript/JavaScript services.
<video />
A Boat SDK gives you typed calls for these tasks:
* Create sandboxes.
* Prompt sandboxes.
* Read events.
* List API key metadata.
* Manage secrets.
* Open desktop or SSH access.
| SDK | Package | Method names |
| - | - | - |
| [Python](/sdks/python) | `boat-sdk` from PyPI | snake\_case |
| [TypeScript / JavaScript](/sdks/typescript) | `@boatdev/sdk` from npm | camelCase |
## Install
<CodeGroup>
```bash Python theme={null}
python -m pip install boat-sdk
```
```bash TypeScript / JavaScript theme={null}
npm install @boatdev/sdk
```
</CodeGroup>
## Configure
1. Create a Boat API key. Run `boat api-key create` or use the [dashboard](https://boat.dev/dashboard?tab=api-keys).
2. Store the key as `BOAT_API_KEY`.
3. Give the key to the SDK `Configuration` object.
The base URL is:
```text theme={null}
https://boat.dev/api/v1
```
<Warning>
Keep these values secret: Boat API keys, Boat secrets, SSH keys, and the desktop or VNC URLs that Boat returns. Do not log or store them without redaction.
</Warning>
## Next steps
<Columns>
<Card title="Python SDK guide" icon="python" href="/sdks/python">
Configure the client, run the create and prompt example, and read the Python method and type reference.
</Card>
<Card title="TypeScript / JavaScript SDK guide" icon="js" href="/sdks/typescript">
Configure the client, run the create and prompt example, and read the TypeScript method and type reference.
</Card>
</Columns>
# Python SDK
Source: https://docs.boat.dev/sdks/python
Install, configure, and use the boat-sdk Python package.
<video />
Install the Python package:
```bash theme={null}
python -m pip install boat-sdk
```
Import `BoatApi` and configure authentication. Then call snake\_case methods like `sandbox.create`, `sandbox.prompt`, and `sandbox.events`.
## Configure
```python theme={null}
import os
from boat_sdk import ApiClient, Configuration
from boat_sdk.api.boat_api import BoatApi
config = Configuration(
host=os.getenv("BOAT_BASE_URL", "https://boat.dev/api/v1"),
access_token=os.environ["BOAT_API_KEY"],
)
with ApiClient(config) as client:
sandbox = BoatApi(client)
```
The request models are in `boat_sdk.models`.
Before you send a prompt, configure the selected provider (harness) for the authenticated account.
* The providers are `codex`, `claude-code` (alias `claude`), `pi`, `opencode`, `prime-agent` (alias `prime`), `kimi`, and `mistral`.
* Without `provider`, the SDK uses the dashboard default of the account.
* If the credentials of the selected provider are missing, `sandbox.prompt(...)` raises `ApiException` with code `provider_not_configured`.
A sandbox runs [many conversations in parallel](/integrated-agents). To start a new one, pass `new=True`. To continue a specific one, pass `conversation_id`. The response gives `conversation_id` back.
## Create, prompt, and clean up
```python theme={null}
import os
import time
from boat_sdk import ApiClient, Configuration
from boat_sdk.api.boat_api import BoatApi
from boat_sdk.models.create_sandbox_request import CreateSandboxRequest
from boat_sdk.models.prompt_request import PromptRequest
from boat_sdk.models.update_sandbox_request import UpdateSandboxRequest
from boat_sdk import wait_until_ready, wait_for_prompt
config = Configuration(
host=os.getenv("BOAT_BASE_URL", "https://boat.dev/api/v1"),
access_token=os.environ["BOAT_API_KEY"],
)
sandbox_id = None
with ApiClient(config) as client:
sandbox = BoatApi(client)
try:
created = sandbox.create(CreateSandboxRequest(ttl_seconds=1800))
sandbox_id = created.sandbox.id
sandbox.update(sandbox_id, UpdateSandboxRequest(name="sdk-demo"))
wait_until_ready(sandbox, sandbox_id)
queued = sandbox.prompt(
sandbox_id,
PromptRequest(
provider="codex",
prompt="Inspect the repository and summarize the test command.",
),
)
run = wait_for_prompt(sandbox, sandbox_id, queued.prompt_id)
print(run.status)
events = sandbox.events(sandbox_id, limit=50, type="prompt,response")
print(events.events)
finally:
if sandbox_id:
sandbox.stop(sandbox_id)
```
## Machine size
To create a bigger sandbox, pass `type`. `large` uses machine time at 2x. `small` uses it at half
rate. A fork gets the type of its source sandbox. To move a sandbox to a different size, pass `type`
to `resume` or `fork`.
```python theme={null}
created = sandbox.create(CreateSandboxRequest(type="large", ttl_seconds=3600))
info = sandbox.get(created.sandbox.id)
print(info.sandbox.type, info.sandbox.vcpu, info.sandbox.memory_gb)
```
See [Machine Capabilities](/machines) and [Pricing](/pricing).
## Per-sandbox environment variables
To add variables to one sandbox, pass `env`. They come on top of the secrets of your account.
When two variables have the same name, the value for this sandbox wins. The maximum is 100
variables and 64KB total.
```python theme={null}
created = sandbox.create(CreateSandboxRequest(
ttl_seconds=3600,
env={"DATABASE_URL": "postgres://user:pass@host:5432/app", "FEATURE_FLAG": "1"},
))
```
A fork gets the `env` of its source sandbox, unless you give the fork its own `env`.
## No-env sandboxes
When you give a sandbox to your own end users, create it with `no_env=True`. Then none of
your account secrets go to it. Boat withholds model keys, the GitHub token, dashboard
environment variables, the SSH identity, and secret files. SSH, desktop, snapshots, public
URLs, and forks still work. A fork of a no-env sandbox is always no-env. You cannot change
that.
```python theme={null}
created = sandbox.create(CreateSandboxRequest(ttl_seconds=1800, no_env=True))
sandbox.resume(sandbox_id, ResumeRequest(no_env=True))
forked = sandbox.fork(sandbox_id, ForkRequest(no_env=True))
```
## Methods
Call all methods on `BoatApi`. Request bodies use model classes from `boat_sdk.models`.
| Method | Arguments | Returns | Use |
| - | - | - | - |
| `me()` | none | `MeResponse` | Get the authenticated Boat account user. |
| `limits()` | none | `LimitsResponse` | Check whether the account can create or operate sandboxes before starting work. |
| `repos(sync=None, limit=None, cursor=None, sort=None, q=None, selected=None)` | optional sync, pagination, search, and selected-only filters | `ReposResponse` | List GitHub installations, repositories, and selected repositories. |
| `select_repo(RepoSelectionRequest)` | `repository_id`, optional `base_branch` | `RepoSelectionResponse` | Select a repository for future sandboxes. Use `database_id` from `repos()` as `repository_id`. |
| `api_keys()` | none | `ApiKeysResponse` | List API key metadata, including 30-day request totals and live resource counts. Raw secrets are not returned. |
| `secrets()` | none | `SecretsResponse` | Read the current environment variables and secret files configured for sandboxes. |
| `update_secrets(SecretsUpdateRequest)` | `env_contents`, `secret_files` | `SecretsResponse` | Replace the complete secret setup. Send every env var and file that should remain. |
| `sandboxes(limit=None, cursor=None, sort=None, state=None)` | optional pagination and state filter | `SandboxListResponse` | List the sandboxes of the account. |
| `create(CreateSandboxRequest)` | optional `type`, `ttl_seconds`, `env`, `environment`, `no_env`, `setup_script`, `var_from`, `org` | `CreateSandboxResponse` | Create a sandbox. Use `ttl_seconds=None` to disable auto-stop. Set `no_env=True` to withhold all account secrets (for sandboxes you give to your users). `var_from` starts the sandbox from a named snapshot. `org` bills it to an organization wallet. |
| `get(sandbox_id)` | Sandbox id | `SandboxInfoResponse` | Fetch the latest sandbox state and connection fields. |
| `usage(sandbox_id, since=None, until=None)` | Sandbox id, optional window as ISO 8601 or Unix seconds | `SandboxUsageResponse` | Billable machine time one sandbox consumed, and its cost at list price, for per-sandbox billing of your own users. Omit the window for the sandbox's whole life. See [Per-sandbox usage](/billing#per-sandbox-usage). |
| `update(sandbox_id, UpdateSandboxRequest)` | Sandbox id plus `name`, `ttl_seconds`, and/or `subdomain` | `SandboxInfoResponse` | Rename a sandbox, change its auto-stop TTL, or rename its subdomain (re-points every live URL with no downtime). |
| `stop(sandbox_id, StopRequest=None)` | Sandbox id, optional `force` | `SandboxActionResponse` | Stop (archive) a sandbox. A stop first makes a snapshot of the disk. If that snapshot fails, the stop stays pending and the sandbox keeps running until a save succeeds. Boat does not bill you for that time. To stop anyway, pass `StopRequest(force=True)`. The sandbox keeps its last successful snapshot, and all data written after it is lost permanently. |
| `get_stop(sandbox_id, stop_id)` | Sandbox id and the stop id that `stop()` returned | `StopOperationResponse` | Read one stop by id: `pending`, `failing`, `completed` or `superseded`. Old stops stay readable after a resume or a later stop. |
| `resume(sandbox_id, ResumeRequest)` | Sandbox id, optional `type`, `env`, `environment`, `ttl_seconds`, `no_env` | `SandboxActionResponse` | Resume an archived sandbox. Pass `ResumeRequest(no_env=True)` to convert it to no-env while scrubbing inherited owner secrets, or `type` to resume it onto a different machine size. `ttl_seconds` omitted keeps the sandbox's current auto-stop. Poll `get()` until it is ready. |
| `fork(sandbox_id, ForkRequest)` | Sandbox id, optional `env`, `environment`, `type`, `ttl_seconds`, `no_env` | `SandboxActionResponse` | Create a new sandbox from the snapshot of the source sandbox. Pass `ForkRequest(no_env=True)` to create a no-env fork, or `type` to fork onto a different machine size. A fork does not inherit the source's auto-stop: omit `ttl_seconds` and it gets the 1 hour default. The source sandbox is never modified. |
| `delete_sandbox(sandbox_id)` | Sandbox id | `SandboxActionResponse` | **Permanently delete a sandbox and its snapshots.** Force-stops it, then deletes every snapshot chain only this sandbox uses. It cannot be resumed or forked afterwards and there is no undo, so use `stop()` if you want the data back later. Snapshot data a fork, a resume or a named snapshot still reads is kept. See [Snapshots](/snapshots/download-and-delete#delete-a-sandbox). |
| `prompt(sandbox_id, PromptRequest)` | Sandbox id plus `provider`, `prompt`, optional `model`, optional `reasoning_effort`, optional `fast`, optional `new`, optional `conversation_id` | `PromptResponse` | Queue work inside a sandbox. Returns `prompt_id`, `prompt_run.status`, and the `conversation_id` it ran in. Set `new=True` for a new [conversation](/integrated-agents) or `conversation_id` to continue one. Set `fast=True` to run in fast mode. |
| `prompt_run_status(sandbox_id, prompt_id)` | Sandbox id and prompt id | `PromptRunResponse` | Read first-class prompt run status, including its `conversation_id`. |
| `events(sandbox_id, limit=None, cursor=None, sort=None, type=None, conversation=None)` | Sandbox id plus optional pagination/filtering | `EventsResponse` | Read typed event history for a sandbox. Streams all [conversations](/integrated-agents) by default. To filter, pass `conversation=<id>`. Each event carries `conversation_id`. |
| `read_file(sandbox_id, path, encoding="utf8")` | Sandbox id and relative path | `FileReadResponse` | Deterministically read a text/base64 file from the sandbox work directory. |
| `write_file(sandbox_id, FileWriteRequest)` | Sandbox id plus relative path/content | `FileWriteResponse` | Deterministically write a text/base64 file. |
| `command(sandbox_id, CommandRequest)` | Sandbox id plus command/cwd/timeout | `CommandResponse` | Execute a bounded command in the sandbox work directory. |
| `artifact(sandbox_id, path)` | Sandbox id and relative path | bytes response | Download an artifact as bytes. |
| `interrupt(sandbox_id, conversation=None)` | Sandbox id, optional conversation id | `SandboxActionResponse` | Interrupt current work in a running sandbox. Stops all [conversations](/integrated-agents) by default. To stop only one, pass `conversation=<id>`. The others keep running. |
| `desktop(sandbox_id, vnc=None, theme=None, request_body=None)` | Sandbox id plus optional desktop parameters. For VNC, send `request_body={"publicAccess": True}` to return a URL without `_token`. | `DesktopResponse` | Create or fetch a desktop streaming URL. Treat returned URLs as secrets. If `provisioning` is true, poll again. |
| `ssh_key(sandbox_id, SshKeyRequest)` | Sandbox id plus public SSH key | `SshKeyResponse` | Add a public SSH key for sandbox SSH access. |
| `list_snapshots(limit=None, cursor=None, sort=None)` | optional pagination | `SnapshotListResponse` | List completed snapshots of all sandboxes. Each item has its `sandbox_id`. |
| `list_sandbox_snapshots(sandbox_id, limit=None, cursor=None, sort=None)` | Sandbox id plus optional pagination | `SnapshotListResponse` | List completed snapshots for one sandbox. |
| `get_latest_sandbox_snapshot(sandbox_id)` | Sandbox id | `SnapshotLatestResponse` | Most recent completed snapshot for a sandbox, or `None`. |
| `get_snapshot_tree(snapshot_id)` | Snapshot id | `SnapshotTreeResponse` | Flat file/folder listing with sizes for a snapshot. Works with the sandbox stopped or archived. |
| `get_snapshot_file(snapshot_id, path=None)` | Snapshot id plus a path from the tree (empty for the whole snapshot) | bytes response | Download one file's bytes, or a folder as a `.tar` archive, straight from the snapshot. Works with the sandbox stopped or archived. |
| `get_snapshot_download(snapshot_id)` | Snapshot id | `SnapshotDownloadResponse` | Signed chunk URLs to rebuild the snapshot's full filesystem client-side. |
### Browse a stopped sandbox's filesystem
Snapshot reads do not use the machine. So they work while the sandbox is archived:
```python theme={null}
latest = sandbox.get_latest_sandbox_snapshot(sandbox_id)
tree = sandbox.get_snapshot_tree(latest.snapshot.id)
data = sandbox.get_snapshot_file(latest.snapshot.id, path="projects/app/.env")
```
## Waiters and helpers
The package exports waiters, and helper functions for files and commands:
```python theme={null}
from boat_sdk import wait_until_ready, wait_until_idle, wait_for_desktop, wait_for_prompt, wait_for_prompt_done, stop_and_remove, read_text, write_text, exec_command
wait_until_ready(sandbox, sandbox_id)
queued = sandbox.prompt(sandbox_id, PromptRequest(provider="codex", prompt="Run tests"))
# fast mode instead: PromptRequest(provider="codex", model="gpt-6.1-sol", fast=True, prompt="Run tests")
wait_for_prompt(sandbox, sandbox_id, queued.prompt_id)
public_vnc = wait_for_desktop(sandbox, sandbox_id, public_access=True)
write_text(sandbox, sandbox_id, "notes/result.txt", "done\n")
result = exec_command(sandbox, sandbox_id, "cat notes/result.txt")
stop_and_remove(sandbox, sandbox_id) # stop, keep the snapshots
stop_and_remove(sandbox, sandbox_id, delete=True) # delete the sandbox and its snapshots
```
To know when a prompt is done, use `wait_for_prompt` or `wait_for_prompt_done`. Do not guess from `sandbox.state` and event polling. To get response and tool-call events while the work runs, use `stream_prompt` or `stream_events`.
## Types
Python models use snake\_case attributes. The JSON uses the camelCase field names of the API.
| Type | Fields | Notes |
| - | - | - |
| `ApiKey` | `id`, `name`, `key_prefix`, `key_last_four`, `created_at`, `last_used_at`, `usage`, `resources` | Metadata only, not the raw secret. Includes 30-day request total and live resource counts. |
| `ApiKeysResponse` | `ok`, `type`, `api_keys` | API key metadata response. Raw secrets are not returned. |
| `Sandbox` | `id`, `name`, `state`, `type`, `vcpu`, `memory_gb`, `billing_multiplier`, `url`, `ip`, `created_at`, `updated_at`, `archive_after`, `desktop_available`, `desktop_url`, `snapshot_available`, `snapshot_completed_at` | `desktop_url` can contain a token. Redact it. |
| `SandboxActionResponse` | `ok`, `type`, `id`, `status`, `sandbox` | Returned by lifecycle actions such as stop, resume, fork, and interrupt. |
| `SandboxInfoResponse` | `ok`, `type`, `sandbox` | Returned by `get()` and `update()`. |
| `SandboxUsageResponse` | `ok`, `type`, `sandbox_id`, `sandbox_type`, `billing_multiplier`, `since`, `until`, `seconds`, `dollars`, `seconds_per_dollar`, `running` | Returned by `usage()`. `seconds` includes the type multiplier. `running` means that the value still increases. |
| `SandboxListResponse` | `ok`, `type`, `sandboxes`, `page_info` | Returned by `sandboxes()`. Use `page_info.next_cursor` when `page_info.has_more` is true. |
| `SandboxEvent` | `id`, `type`, `timestamp`, `task_id`, `data`, plus additional fields | Extensible event object returned inside `EventsResponse.events`. Branch on each event `type`. |
| `CommandRequest` | `command`, `cwd`, `timeout_seconds` | Bounded command execution request. `timeout_seconds` defaults to 30 and is capped by the API. |
| `CommandResponse` | `ok`, `type`, `success`, `exit_code`, `signal`, `stdout`, `stderr`, `stdout_truncated`, `stderr_truncated`, `timed_out`, `cwd`, `started_at`, `finished_at` | Returned by `command()` and `exec_command()`. |
| `CompletionEvent` | `id`, `type`, `timestamp`, `task_id`, `data` | Completion-style event such as `task_notification` or `compaction_complete`. `data` is extensible. |
| `CreateSandboxRequest` | `type`, `ttl_seconds`, `env`, `environment`, `no_env`, `setup_script`, `var_from`, `org` | `type` is `small`, `default` or `large` (see Machine size). `ttl_seconds` is the delay before auto-stop. `None` disables it. `var_from` names a snapshot to start from. `org` bills the sandbox to an organization wallet. |
| `CreateSandboxResponse` | `ok`, `type`, `status`, `ttl_seconds`, `sandbox` | Returned immediately after creation starts. |
| `DesktopResponse` | `ok`, `type`, `success`, `desktop_url`, `ip`, `mode`, `provisioning`, `message` | If `provisioning` is true, poll `desktop()` again. |
| `ErrorEnvelope` | `ok`, `type`, `status`, `code`, `message`, `request_id`, `error` | Non-2xx response body. Include `request_id` in support logs. |
| `ErrorEnvelopeError` | `code`, `message`, `status`, `details` | Structured error details. |
| `ErrorEvent` | `id`, `type`, `timestamp`, `task_id`, `data` | Error/protection event such as `usage_limit` or `shield`. `data` is extensible. |
| `EventsResponse` | `ok`, `type`, `id`, `events`, `page_info` | `events` contains sandbox event objects. Use `page_info.next_cursor` when `page_info.has_more` is true. |
| `FileReadResponse` | `ok`, `type`, `success`, `path`, `encoding`, `size`, `content` | Returned by `read_file()` and `read_text()`. `encoding` is `utf8` or `base64`. |
| `FileWriteRequest` | `path`, `content`, `encoding` | Write a UTF-8 string or base64 payload to a relative sandbox work-directory path. |
| `FileWriteResponse` | `ok`, `type`, `success`, `path`, `encoding`, `size` | Returned by `write_file()` and `write_text()`. |
| `LimitsFields` | `access_tier`, `blocked_reason`, `current_limits`, `standard_limits`, `trial_limits`, `upgrade_effects`, `can_start`, `checkout_required`, `start_blocked_reason`, `contact_message`, `active_sandboxes`, `active_states`, `max_active_sandboxes`, `max_creation_requests_per_minute`, `max_creation_requests_per_day`, `start_limits`, `starts`, `has_payment_history`, `package`, `subscription_quota_seconds`, `subscription_remaining_seconds`, `pack_balance_seconds`, `pack_balance_hours`, `pack_balance_dollars`, `credit_purchased_seconds`, `credit_used_seconds`, `live_usage_seconds`, `credit_seconds_per_dollar`, `billing_status`, `subscription_status`, `subscription_cancel_at_period_end`, `has_subscription`, `subscription_trial_ends_at`, `subscription_current_period_end`, `credit_balance_seconds`, `credit_balance_hours` | Shared limit and billing-access fields. Use `can_start` and `start_blocked_reason` before creating sandboxes. `starts.*.remaining` is remaining machine starts in each rolling window. |
| `LimitsFieldsCurrentLimits` | `active_sandboxes`, `creation_rate_per_minute`, `creation_requests_per_day` | Numeric quota limits. |
| `LimitsResponse` | `ok`, `type`, plus all `LimitsFields` fields | Returned by `limits()`. |
| `MeResponse` | `ok`, `type`, `user` | Authenticated account response. |
| `MeResponseAllOfUser` | `login`, `email` | User identity fields. |
| `PageInfo` | `next_cursor`, `has_more`, `limit` | Pagination metadata on list responses. |
| `PromptEvent` | `id`, `type`, `timestamp`, `task_id`, `conversation_id`, `data` | Prompt lifecycle event. `data` includes `prompt`, `status`, and optionally `is_reverted`. |
| `PromptRequest` | `provider`, `model`, `reasoning_effort`, `fast`, `new`, `conversation_id`, `prompt` | `provider` is `codex`, `claude-code` (alias `claude`), `pi`, `opencode`, `prime-agent` (alias `prime`), `kimi`, or `mistral`. Omit it for the dashboard default. Omit `model`/`reasoning_effort`/`fast` to use saved defaults (the live catalog is `GET /provider-models`). `fast=True` runs in fast mode at the provider's higher fast rate. Only models with `fastMode: true` accept it. Others return `fast_mode_not_supported`. Set `new=True` or `conversation_id` to control the [conversation](/integrated-agents). |
| `PromptResponse` | `ok`, `type`, `id`, `prompt_id`, `conversation_id`, `prompt_run`, `status`, `provider`, `model`, `reasoning_effort`, `fast` | Returned after work is queued. `conversation_id` is the conversation the prompt runs in. |
| `PromptRun` | `id`, `prompt_id`, `sandbox_id`, `status`, `done`, `created_at`, `model`, `reasoning_effort`, `fast`, `conversation_id` | First-class prompt run state. `status` is `sending`, `queued`, `running`, `finished`, `failed`, or `interrupted` (a turn stopped by `boat interrupt`). |
| `PromptRunResponse` | `ok`, `type`, `id`, `prompt_run` | Returned by `prompt_run_status()`. |
| `StopOperationResponse` | `ok`, `type`, `id`, `stop` | Returned by `get_stop()`. `stop` has `id`, `status`, `requested_at`, `last_attempt_at`, `error`, `ended_at`. |
| `ResponseEvent` | `id`, `type`, `timestamp`, `task_id`, `conversation_id`, `data` | Agent response event. `data` includes `content`, optional `model`, optional `tools`, and optional `is_streaming`. |
| `RepoSelectionRequest` | `repository_id`, `base_branch` | `repository_id` is a `database_id` from `repos()`. |
| `RepoSelectionResponse` | `ok`, `type`, `success`, `environment_id`, `selected_repositories` | Returned by `select_repo()`. |
| `ReposResponse` | `ok`, `type`, `installations`, `environment_id`, `selected_repositories`, `page_info` | Repository inventory and current selections. Use `page_info.next_cursor` when `page_info.has_more` is true. |
| `Repository` | `id`, `database_id`, `name`, `full_name`, `private`, `permissions`, `pushed_at` | Use `database_id` when selecting a repository. |
| `RepositoryInstallation` | `type`, `account_login`, `account_avatar_url`, `repositories` | Group of repositories available through one installation/account. |
| `SecretFile` | `path`, `contents` | Treat `contents` as sensitive. |
| `SecretsResponse` | `ok`, `type`, `success`, `environment_id`, `env_contents`, `secret_files`, `pushed` | Current secret setup. Treat `env_contents` and `secret_files` as sensitive. |
| `SecretsUpdateRequest` | `env_contents`, `secret_files` | Full replacement request for secrets. |
| `SelectedRepository` | `id`, `database_id`, `name`, `full_name`, `private`, `permissions`, `pushed_at`, `base_branch`, `setup_routine_id`, `setup_script`, `setup_blocking` | Repository selected for future sandboxes. |
| `SshKeyRequest` | `key` | Public SSH key in OpenSSH format. |
| `SshKeyResponse` | `ok`, `type`, `success`, `machine_ip`, `ssh_user` | Returned after adding an SSH key. |
| `SuccessBase` | `ok`, `type` | Base success-envelope fields. |
| `UnknownEvent` | `type` plus additional fields | Forward-compatible event shape for event types not modeled by the current SDK. |
| `UpdateSandboxRequest` | `name`, `ttl_seconds` | Send only fields you want to change. `ttl_seconds=None` disables auto-stop. |
## Errors
Methods raise `ApiException` for non-2xx responses. When you debug, log the status, the reason, and the response body. Redact API keys, Boat secrets, SSH keys, and desktop URLs.
```python theme={null}
from boat_sdk.exceptions import ApiException
try:
sandbox.get("bx_missing")
except ApiException as exc:
print(exc.status)
print(exc.reason)
print(exc.body)
```
## Streaming responses and tool calls
The Python helper module exports `stream_events` and `stream_prompt` to stream responses. They long-poll the v1 events cursor API of the sandbox. You do not need a separate SSE or WebSocket endpoint.
| Event | Where to read it |
| - | - |
| Response text | `event.data.content` on `response` events |
| Partial streaming output | `event.data.is_streaming` is set |
| Tool calls | `response` events with `event.data.tools` |
```python theme={null}
from boat_sdk import stream_prompt
from boat_sdk.models.prompt_request import PromptRequest
for event in stream_prompt(
sandbox,
sandbox_id,
PromptRequest(provider="codex", prompt="Run pwd and ls, then summarize the result."),
):
if event.type != "response":
continue
data = event.data
tools = data.get("tools") if isinstance(data, dict) else getattr(data, "tools", None)
content = data.get("content") if isinstance(data, dict) else getattr(data, "content", "")
if tools:
print("tools", tools)
if content:
print(content, end="")
```
For a feed like the dashboard, not limited to one prompt, use `stream_events(sandbox, sandbox_id, type="prompt,response")`.
# TypeScript and JavaScript SDK
Source: https://docs.boat.dev/sdks/typescript
Install, configure, and use the @boatdev/sdk npm package.
<video />
Install the npm package:
```bash theme={null}
npm install @boatdev/sdk
```
Import `BoatApi` and configure authentication. Then call methods like `sandbox.create`, `sandbox.prompt`, and `sandbox.events`.
## Configure
```ts theme={null}
import { BoatApi, Configuration, waitUntilReady, waitForPrompt } from "@boatdev/sdk";
const sandbox = new BoatApi(new Configuration({
basePath: process.env.BOAT_BASE_URL ?? "https://boat.dev/api/v1",
accessToken: process.env.BOAT_API_KEY ?? (() => {
throw new Error("Set BOAT_API_KEY from the Boat dashboard API keys tab.");
})(),
}));
```
In TypeScript projects, use modern Node resolution and DOM fetch types:
```json theme={null}
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022", "DOM"],
"types": ["node"],
"strict": true
}
}
```
Node 18+ has `fetch`. Older runtimes need a fetch polyfill. For the ESM examples, set `"type": "module"` in `package.json`. CommonJS projects can use the [`require` example](#commonjs).
## Create, prompt, and clean up
```ts theme={null}
import { BoatApi, Configuration } from "@boatdev/sdk";
const sandbox = new BoatApi(new Configuration({
basePath: process.env.BOAT_BASE_URL ?? "https://boat.dev/api/v1",
accessToken: process.env.BOAT_API_KEY ?? (() => {
throw new Error("Set BOAT_API_KEY from the Boat dashboard API keys tab.");
})(),
}));
async function main() {
let sandboxId: string | undefined;
try {
const created = await sandbox.create({ ttlSeconds: 1800 });
sandboxId = created.sandbox.id;
await sandbox.update({
sandboxId,
name: "sdk-demo",
});
await waitUntilReady(sandbox, sandboxId);
const queued = await sandbox.prompt({
sandboxId,
provider: "codex",
prompt: "Inspect the repository and summarize the test command.",
});
const run = await waitForPrompt(sandbox, sandboxId, queued.promptId);
console.log(run.status);
const events = await sandbox.events({ sandboxId, limit: 50, type: "prompt,response" });
console.log(events.events);
} finally {
if (sandboxId) await sandbox.stop({ sandboxId });
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
```
<Note>
Use `ttlSeconds` when you create a sandbox. Set a name after that with `sandbox.update`.
</Note>
## Machine size
To create a bigger sandbox, pass `type`. `large` uses machine time at 2x. `small` uses it at half
rate. A fork gets the type of its source sandbox. To move a sandbox to a different size, pass `type`
to `resume` or `fork`.
```ts theme={null}
const created = await sandbox.create({ type: "large", ttlSeconds: 3600 });
const info = await sandbox.get({ sandboxId: created.sandbox.id });
console.log(info.sandbox.type, info.sandbox.vcpu, info.sandbox.memoryGB);
```
See [Machine Capabilities](/machines) and [Pricing](/pricing).
## Per-sandbox environment variables
To add variables to one sandbox, pass `env`. They come on top of the secrets of your account.
When two variables have the same name, the value for this sandbox wins. The maximum is 100
variables and 64KB total.
```ts theme={null}
const created = await sandbox.create({
ttlSeconds: 3600,
env: { DATABASE_URL: "postgres://user:pass@host:5432/app", FEATURE_FLAG: "1" },
});
```
A fork gets the `env` of its source sandbox, unless you give the fork its own `env`.
## No-env sandboxes
When you give a sandbox to your own end users, create it with `noEnv: true`. Then none of
your account secrets go to it. Boat withholds model keys, the GitHub token, dashboard
environment variables, the SSH identity, and secret files. SSH, desktop, snapshots, public
URLs, and forks still work. A fork of a no-env sandbox is always no-env. You cannot change
that.
```ts theme={null}
const created = await sandbox.create({ ttlSeconds: 1800, noEnv: true });
await sandbox.resume({
sandboxId,
noEnv: true,
});
const forked = await sandbox.fork({
sandboxId,
noEnv: true,
});
```
## CommonJS
```js theme={null}
const { BoatApi, Configuration } = require("@boatdev/sdk");
const sandbox = new BoatApi(new Configuration({
basePath: process.env.BOAT_BASE_URL || "https://boat.dev/api/v1",
accessToken: process.env.BOAT_API_KEY,
}));
```
## Methods
Call all methods on `BoatApi` with one object. Some methods take a request body. For these, put the fields of the body (`...body` in the table) directly in that object, next to the path and query parameters:
```ts theme={null}
saveNamedSnapshot({ sandboxId, name })
fork({ sandboxId, type: "small" })
```
The SDK also accepts the wrapped form, as it always did. It sends the same request:
```ts theme={null}
fork({ sandboxId, forkRequest: { type: "small" } })
```
The flat form needs @boatdev/sdk 1.1.0 or later. On 1.0.x, use the wrapped form.
| Method | Arguments | Returns | Use |
| - | - | - | - |
| `me()` | none | `Promise<MeResponse>` | Get the authenticated Boat account user. |
| `limits()` | none | `Promise<LimitsResponse>` | Check whether the account can create or operate sandboxes before starting work. |
| `repos({ sync, limit, cursor, sort, q, selected }?)` | optional sync, pagination, search, and selected-only filters | `Promise<ReposResponse>` | List GitHub installations, repositories, and selected repositories. |
| `selectRepo({ ...body })` | `repositoryId`, optional `baseBranch` | `Promise<RepoSelectionResponse>` | Select a repository for future sandboxes. Use `databaseId` from `repos()` as `repositoryId`. |
| `apiKeys()` | none | `Promise<ApiKeysResponse>` | List API key metadata, including 30-day request totals and live resource counts. Raw secrets are not returned. |
| `secrets()` | none | `Promise<SecretsResponse>` | Read the current environment variables and secret files configured for sandboxes. |
| `updateSecrets({ ...body })` | `envContents`, `secretFiles` | `Promise<SecretsResponse>` | Replace the complete secret setup. Send every env var and file that should remain. |
| `sandboxes({ limit, cursor, sort, state }?)` | optional pagination and state filter | `Promise<SandboxListResponse>` | List the sandboxes of the account. |
| `create({ ...body }?)` | optional `type`, `ttlSeconds`, `env`, `environment`, `noEnv`, `setupScript`, `from`, `org` | `Promise<CreateSandboxResponse>` | Create a sandbox. Use `ttlSeconds: null` to disable auto-stop. Set `noEnv: true` to withhold all account secrets (for sandboxes you give to your users). `from` starts the sandbox from a named snapshot. `org` bills it to an organization wallet. |
| `get({ sandboxId })` | Sandbox id | `Promise<SandboxInfoResponse>` | Fetch the latest sandbox state and connection fields. |
| `usage({ sandboxId, since, until })` | Sandbox id, optional window as ISO 8601 or Unix seconds | `Promise<SandboxUsageResponse>` | Billable machine time one sandbox consumed, and its cost at list price, for per-sandbox billing of your own users. Omit the window for the sandbox's whole life. See [Per-sandbox usage](/billing#per-sandbox-usage). |
| `update({ sandboxId, ...body })` | Sandbox id plus `name`, `ttlSeconds`, and/or `subdomain` | `Promise<SandboxInfoResponse>` | Rename a sandbox, change its auto-stop TTL, or rename its subdomain (re-points every live URL with no downtime). |
| `stop({ sandboxId, ...body }?)` | Sandbox id, optional `force` | `Promise<SandboxActionResponse>` | Stop (archive) a sandbox. A stop first makes a snapshot of the disk. If that snapshot fails, the stop stays pending and the sandbox keeps running until a save succeeds. Boat does not bill you for that time. To stop anyway, pass `force: true`. The sandbox keeps its last successful snapshot, and all data written after it is lost permanently. |
| `getStop({ sandboxId, stopId })` | Sandbox id and the stop id that `stop()` returned | `Promise<StopOperationResponse>` | Read one stop by id: `pending`, `failing`, `completed` or `superseded`. Old stops stay readable after a resume or a later stop. |
| `resume({ sandboxId, ...body })` | Sandbox id, optional `type`, `env`, `environment`, `ttlSeconds`, `noEnv` | `Promise<SandboxActionResponse>` | Resume an archived sandbox. Set `noEnv: true` to convert it to no-env while scrubbing inherited owner secrets, or `type` to resume it onto a different machine size. Omit `ttlSeconds` to keep the current auto-stop of the sandbox. Poll `get()` until it is ready. |
| `fork({ sandboxId, ...body })` | Sandbox id, optional `env`, `environment`, `type`, `ttlSeconds`, `noEnv` | `Promise<SandboxActionResponse>` | Create a new sandbox from the snapshot of the source sandbox. Set `noEnv: true` to create a no-env fork, or `type` to fork onto a different machine size. A fork does not inherit the source's auto-stop: omit `ttlSeconds` and it gets the 1 hour default. The source sandbox is never modified. |
| `deleteSandbox({ sandboxId })` | Sandbox id | `Promise<SandboxActionResponse>` | **Permanently delete a sandbox and its snapshots.** Force-stops it, then deletes every snapshot chain only this sandbox uses. It cannot be resumed or forked afterwards and there is no undo, so use `stop()` if you want the data back later. Snapshot data a fork, a resume or a named snapshot still reads is kept. See [Snapshots](/snapshots/download-and-delete#delete-a-sandbox). |
| `prompt({ sandboxId, ...body })` | Sandbox id plus `provider`, `prompt`, optional `model`, optional `reasoningEffort`, optional `fast`, optional `new`, optional `conversationId` | `Promise<PromptResponse>` | Queue work inside a sandbox. Returns `promptId`, `promptRun.status`, and the `conversationId` it ran in. Set `new: true` for a new [conversation](/integrated-agents) or `conversationId` to continue one. Set `fast: true` to run in fast mode. |
| `promptRunStatus({ sandboxId, promptId })` | Sandbox id and prompt id | `Promise<PromptRunResponse>` | Read first-class prompt run status, including its `conversationId`. |
| `events({ sandboxId, limit, cursor, sort, type, conversation })` | Sandbox id plus optional pagination/filtering | `Promise<EventsResponse>` | Read typed event history for a sandbox. Streams all [conversations](/integrated-agents) by default. To filter, pass `conversation`. Each event carries `conversationId`. |
| `readFile({ sandboxId, path, encoding })` | Sandbox id and relative path | `Promise<FileReadResponse>` | Deterministically read a text/base64 file from the sandbox work directory. |
| `writeFile({ sandboxId, ...body })` | Sandbox id plus relative path/content | `Promise<FileWriteResponse>` | Deterministically write a text/base64 file. |
| `command({ sandboxId, ...body })` | Sandbox id plus command/cwd/timeout | `Promise<CommandResponse>` | Execute a bounded command in the sandbox work directory. |
| `artifact({ sandboxId, path })` | Sandbox id and relative path | `Promise<Blob>` | Download an artifact as bytes. |
| `interrupt({ sandboxId })` | Sandbox id | `Promise<SandboxActionResponse>` | Interrupt current work in a running sandbox. |
| `desktop({ sandboxId, vnc, theme, requestBody })` | Sandbox id plus optional desktop parameters. For VNC, send `requestBody: { publicAccess: true }` to return a URL without `_token`. | `Promise<DesktopResponse>` | Create or fetch a desktop streaming URL. Treat returned URLs as secrets. If `provisioning` is true, poll again. |
| `sshKey({ sandboxId, ...body })` | Sandbox id plus public SSH key | `Promise<SshKeyResponse>` | Add a public SSH key for sandbox SSH access. |
| `listSnapshots({ limit, cursor, sort }?)` | optional pagination | `Promise<SnapshotListResponse>` | List completed snapshots of all sandboxes. Each item has its `sandboxId`. |
| `listSandboxSnapshots({ sandboxId, limit, cursor, sort })` | Sandbox id plus optional pagination | `Promise<SnapshotListResponse>` | List completed snapshots for one sandbox. |
| `getLatestSandboxSnapshot({ sandboxId })` | Sandbox id | `Promise<SnapshotLatestResponse>` | Most recent completed snapshot for a sandbox, or `null`. |
| `getSnapshotTree({ snapshotId })` | Snapshot id | `Promise<SnapshotTreeResponse>` | Flat file/folder listing with sizes for a snapshot. Works with the sandbox stopped or archived. |
| `getSnapshotFile({ snapshotId, path })` | Snapshot id plus a path from the tree (empty for the whole snapshot) | `Promise<Blob>` | Download one file's bytes, or a folder as a `.tar` archive, straight from the snapshot. Works with the sandbox stopped or archived. |
| `getSnapshotDownload({ snapshotId })` | Snapshot id | `Promise<SnapshotDownloadResponse>` | Signed chunk URLs to rebuild the snapshot's full filesystem client-side. |
### Browse a stopped sandbox's filesystem
Snapshot reads do not use the machine. So they work while the sandbox is archived:
```ts theme={null}
const latest = await sandbox.getLatestSandboxSnapshot({ sandboxId });
const tree = await sandbox.getSnapshotTree({ snapshotId: latest.snapshot.id });
const blob = await sandbox.getSnapshotFile({ snapshotId: latest.snapshot.id, path: "projects/app/.env" });
```
## Waiters and helpers
The package exports waiters, and helper functions for files and commands:
```ts theme={null}
import { waitUntilReady, waitUntilIdle, waitForDesktop, waitForPrompt, waitForPromptDone, streamEvents, streamPrompt, stopAndRemove, readText, writeText, execCommand } from "@boatdev/sdk";
await waitUntilReady(sandbox, sandboxId);
const queued = await sandbox.prompt({ sandboxId, provider: "codex", prompt: "Run tests" });
// fast mode instead: { sandboxId, provider: "codex", model: "gpt-6.1-sol", fast: true, prompt: "Run tests" }
await waitForPrompt(sandbox, sandboxId, queued.promptId);
const publicVnc = await waitForDesktop(sandbox, sandboxId, { publicAccess: true });
await writeText(sandbox, sandboxId, "notes/result.txt", "done\n");
const result = await execCommand(sandbox, sandboxId, "cat notes/result.txt");
await stopAndRemove(sandbox, sandboxId); // stop, keep the snapshots
await stopAndRemove(sandbox, sandboxId, { delete: true }); // delete the sandbox and its snapshots
```
To know when a prompt is done, use `waitForPrompt` or `waitForPromptDone`. Do not guess from `sandbox.state` and event polling. To get response and tool-call events while the work runs, use `streamPrompt` or `streamEvents`.
## Streaming responses and tool calls
The SDK exports `streamEvents` and `streamPrompt` to stream responses. They use the v1 events cursor API of the sandbox. You do not need a separate SSE or WebSocket endpoint.
| Event | Where to read it |
| - | - |
| Response text | `event.data.content` on `response` events |
| Partial streaming output | `event.data.isStreaming` is set |
| Tool calls | `response` events with `event.data.tools` |
```ts theme={null}
import { BoatApi, Configuration, streamPrompt } from "@boatdev/sdk";
const sandbox = new BoatApi(new Configuration({
basePath: "https://boat.dev/api/v1",
accessToken: process.env.BOAT_API_KEY!,
}));
const stream = streamPrompt(sandbox, sandboxId, {
provider: "codex",
prompt: "Run pwd and ls, then summarize the result.",
});
for await (const event of stream) {
if (event.type !== "response") continue;
const data = event.data;
if (data.tools?.length) console.log("tools", data.tools);
if (data.content) process.stdout.write(data.content);
if (data.isStreaming) process.stdout.write("\n[partial]\n");
}
```
For a feed like the dashboard, not limited to one prompt, use `streamEvents(sandbox, sandboxId, { type: "prompt,response" })`. Stop it with an `AbortController`.
## Operation request types
These exported interfaces wrap the parameters of `BoatApi` methods.
| Type | Fields | Used by |
| - | - | - |
| `ArtifactRequest` | `sandboxId`, `path` | `artifact()` |
| `SandboxesRequest` | `limit`, `cursor`, `sort`, `state` | `sandboxes()` |
| `CommandOperationRequest` | `sandboxId`, `commandRequest` | `command()` |
| `CreateRequest` | `createSandboxRequest` | `create()` |
| `DesktopRequest` | `sandboxId`, `vnc`, `theme`, `requestBody` | `desktop()`. For a VNC URL without a token, set `requestBody.publicAccess`. |
| `EventsRequest` | `sandboxId`, `limit`, `cursor`, `sort`, `type`, `conversation` | `events()`. `conversation` filters to one [conversation](/integrated-agents). |
| `ForkRequest` | `env`, `environment`, `type`, `ttlSeconds`, `noEnv` | `fork()` |
| `GetRequest` | `sandboxId` | `get()` |
| `UsageRequest` | `sandboxId`, `since`, `until` | `usage()` |
| `InterruptRequest` | `sandboxId`, `conversation` | `interrupt()`. Omit `conversation` to stop the whole sandbox. Pass one to stop only that conversation. |
| `PromptOperationRequest` | `sandboxId`, `promptRequest` | `prompt()` |
| `PromptRunStatusRequest` | `sandboxId`, `promptId` | `promptRunStatus()` |
| `ReadFileRequest` | `sandboxId`, `path`, `encoding` | `readFile()` |
| `RemoveRequest` | `sandboxId` | `remove()` |
| `ReposRequest` | `sync`, `limit`, `cursor`, `sort`, `q`, `selected` | `repos()` |
| `ResumeRequest` | `type`, `env`, `environment`, `ttlSeconds`, `noEnv` | `resume()` |
| `SelectRepoRequest` | `repoSelectionRequest` | `selectRepo()` |
| `SshKeyOperationRequest` | `sandboxId`, `sshKeyRequest` | `sshKey()` |
| `StopRequest` | `sandboxId` | `stop()` |
| `GetStopRequest` | `sandboxId`, `stopId` | `getStop()` |
| `UpdateRequest` | `sandboxId`, `updateSandboxRequest` | `update()` |
| `UpdateSecretsRequest` | `secretsUpdateRequest` | `updateSecrets()` |
| `WriteFileRequest` | `sandboxId`, `fileWriteRequest` | `writeFile()` |
| `SandboxesSortEnum` | `"asc"`, `"desc"` | `sandboxes({ sort })` |
| `DesktopVncEnum` | `1` | `desktop({ vnc })` |
| `DesktopThemeEnum` | `"light"`, `"dark"` | `desktop({ theme })` |
| `EventsSortEnum` | `"asc"`, `"desc"` | `events({ sort })` |
| `ReadFileEncodingEnum` | `"utf8"`, `"base64"` | `readFile({ encoding })` |
| `ReposSortEnum` | `"asc"`, `"desc"` | `repos({ sort })` |
## Model types
TypeScript models use camelCase fields.
| Type | Fields | Notes |
| - | - | - |
| `ApiKey` | `id`, `name`, `keyPrefix`, `keyLastFour`, `createdAt`, `lastUsedAt`, `usage`, `resources` | Metadata only, not the raw secret. Includes 30-day request total and live resource counts. |
| `ApiKeysResponse` | `ok`, `type`, `apiKeys` | API key metadata response. Raw secrets are not returned. |
| `Sandbox` | `id`, `name`, `state`, `type`, `vcpu`, `memoryGB`, `billingMultiplier`, `url`, `ip`, `createdAt`, `updatedAt`, `archiveAfter`, `desktopAvailable`, `desktopUrl`, `snapshotAvailable`, `snapshotCompletedAt` | `desktopUrl` can contain a token. Redact it. |
| `SandboxActionResponse` | `ok`, `type`, `id`, `status`, `sandbox` | Returned by lifecycle actions such as stop, resume, fork, and interrupt. |
| `SandboxInfoResponse` | `ok`, `type`, `sandbox` | Returned by `get()` and `update()`. |
| `SandboxUsageResponse` | `ok`, `type`, `sandboxId`, `sandboxType`, `billingMultiplier`, `since`, `until`, `seconds`, `dollars`, `secondsPerDollar`, `running` | Returned by `usage()`. `seconds` includes the type multiplier. `running` means that the value still increases. |
| `SandboxEvent` | `id`, `type`, `timestamp`, `taskId`, `conversationId`, `data`, plus additional fields | Extensible event object returned inside `EventsResponse.events`. `conversationId` tells you which [conversation](/integrated-agents) the event belongs to. Branch on each event `type`. |
| `SandboxListResponse` | `ok`, `type`, `sandboxes`, `pageInfo` | Returned by `sandboxes()`. |
| `CommandRequest` | `command`, `cwd`, `timeoutSeconds` | Bounded command execution request. |
| `CommandResponse` | `ok`, `type`, `success`, `exitCode`, `signal`, `stdout`, `stderr`, `stdoutTruncated`, `stderrTruncated`, `timedOut`, `cwd`, `startedAt`, `finishedAt` | Returned by `command()` and `execCommand()`. |
| `CompletionEvent` | `id`, `type`, `timestamp`, `taskId`, `data` | Event subtype for `task_notification` and `compaction_complete`. |
| `CreateSandboxRequest` | `type`, `ttlSeconds`, `env`, `environment`, `noEnv`, `setupScript`, `from`, `org` | `type` is `small`, `default` or `large` (see Machine size). `ttlSeconds` is the delay before auto-stop. `null` disables it. `from` names a snapshot to start from. `org` bills the sandbox to an organization wallet. |
| `CreateSandboxResponse` | `ok`, `type`, `status`, `ttlSeconds`, `sandbox` | Returned immediately after creation starts. |
| `DesktopResponse` | `ok`, `type`, `success`, `desktopUrl`, `ip`, `mode`, `provisioning`, `message` | If `provisioning` is true, poll `desktop()` again. |
| `ErrorEnvelope` | `ok`, `type`, `status`, `code`, `message`, `requestId`, `error` | Non-2xx response body. Include `requestId` in support logs. |
| `ErrorEnvelopeError` | `code`, `message`, `status`, `details` | Structured error details. |
| `ErrorEvent` | `id`, `type`, `timestamp`, `taskId`, `data` | Event subtype for `usage_limit` and `shield`. |
| `EventsResponse` | `ok`, `type`, `id`, `events`, `pageInfo` | `events` contains sandbox event objects. |
| `FileReadResponse` | `ok`, `type`, `success`, `path`, `encoding`, `size`, `content` | Returned by `readFile()` and `readText()`. |
| `FileWriteRequest` | `path`, `content`, `encoding` | Write a UTF-8 string or base64 payload. |
| `FileWriteResponse` | `ok`, `type`, `success`, `path`, `encoding`, `size` | Returned by `writeFile()` and `writeText()`. |
| `LimitsFields` | `accessTier`, `blockedReason`, `currentLimits`, `standardLimits`, `trialLimits`, `upgradeEffects`, `canStart`, `checkoutRequired`, `startBlockedReason`, `contactMessage`, `activeSandboxes`, `activeStates`, `maxActiveSandboxes`, `maxCreationRequestsPerMinute`, `maxCreationRequestsPerDay`, `startLimits`, `starts`, `accountPlan`, `plan`, `planName`, `serviceAccount`, `unlimited`, `hasPaymentHistory`, `_package`, `subscriptionQuotaSeconds`, `subscriptionRemainingSeconds`, `packBalanceSeconds`, `packBalanceHours`, `packBalanceDollars`, `creditPurchasedSeconds`, `creditUsedSeconds`, `liveUsageSeconds`, `creditSecondsPerDollar`, `billingStatus`, `subscriptionStatus`, `subscriptionCancelAtPeriodEnd`, `hasSubscription`, `subscriptionTrialEndsAt`, `subscriptionCurrentPeriodEnd`, `creditBalanceSeconds`, `creditBalanceHours` | Shared limit and billing-access fields. Use `canStart` and `startBlockedReason` before creating sandboxes. `starts.*.remaining` is remaining machine starts in each rolling window. `serviceAccount`/`unlimited` identify admin-created automation accounts. |
| `LimitsFieldsCurrentLimits` | `activeSandboxes`, `creationRatePerMinute`, `creationRequestsPerDay` | Numeric quota limits. |
| `LimitsResponse` | `ok`, `type`, plus all `LimitsFields` fields | Returned by `limits()`. |
| `MeResponse` | `ok`, `type`, `user` | Authenticated account response. |
| `MeResponseAllOfUser` | `login`, `email` | User identity fields. |
| `PageInfo` | `nextCursor`, `hasMore`, `limit` | Optional pagination metadata on list responses. |
| `PromptEvent` | `id`, `type`, `timestamp`, `taskId`, `conversationId`, `data` | Event subtype for `prompt`. |
| `PromptEventData` | `prompt`, `status`, `isReverted` | Prompt event payload. |
| `PromptRequest` | `provider`, `model`, `reasoningEffort`, `fast`, `new`, `conversationId`, `prompt` | `provider` is `codex`, `claude-code` (alias `claude`), `pi`, `opencode`, `prime-agent` (alias `prime`), `kimi`, or `mistral`. Omit it for the dashboard default. Omit `model`/`reasoningEffort`/`fast` to use saved defaults (live catalog: `GET /provider-models`). `fast: true` runs in fast mode at the provider's higher fast rate. Only models with `fastMode: true` accept it. Others return `fast_mode_not_supported`. Set `new: true` or `conversationId` to control the [conversation](/integrated-agents). |
| `PromptResponse` | `ok`, `type`, `id`, `promptId`, `conversationId`, `promptRun`, `status`, `provider`, `model`, `reasoningEffort`, `fast` | Returned after work is queued. `conversationId` is the conversation the prompt runs in. |
| `PromptRun` | `id`, `promptId`, `sandboxId`, `status`, `done`, `createdAt`, `model`, `reasoningEffort`, `fast`, `conversationId` | First-class prompt run state. |
| `PromptRunResponse` | `ok`, `type`, `id`, `promptRun` | Returned by `promptRunStatus()`. |
| `StopOperationResponse` | `ok`, `type`, `id`, `stop` | Returned by `getStop()`. `stop` has `id`, `status`, `requestedAt`, `lastAttemptAt`, `error`, `endedAt`. |
| `ResponseEvent` | `id`, `type`, `timestamp`, `taskId`, `conversationId`, `data` | Event subtype for `response`. |
| `ResponseEventData` | `content`, `model`, `tools`, `isStreaming` | Response event payload. |
| `RepoSelectionRequest` | `repositoryId`, `baseBranch` | `repositoryId` is a `databaseId` from `repos()`. |
| `RepoSelectionResponse` | `ok`, `type`, `success`, `environmentId`, `selectedRepositories` | Returned by `selectRepo()`. |
| `ReposResponse` | `ok`, `type`, `installations`, `environmentId`, `selectedRepositories`, `pageInfo` | Repository inventory and current selections. |
| `Repository` | `id`, `databaseId`, `name`, `fullName`, `_private`, `permissions`, `pushedAt` | Use `databaseId` when selecting a repository. |
| `RepositoryInstallation` | `type`, `accountLogin`, `accountAvatarUrl`, `repositories` | Group of repositories available through one installation/account. |
| `SecretFile` | `path`, `contents` | Treat `contents` as sensitive. |
| `SecretsResponse` | `ok`, `type`, `success`, `environmentId`, `envContents`, `secretFiles`, `pushed` | Current secret setup. Treat `envContents` and `secretFiles` as sensitive. |
| `SecretsUpdateRequest` | `envContents`, `secretFiles` | Full replacement request for secrets. |
| `SelectedRepository` | `id`, `databaseId`, `name`, `fullName`, `_private`, `permissions`, `pushedAt`, `baseBranch`, `setupRoutineId`, `setupScript`, `setupBlocking` | Repository selected for future sandboxes. |
| `SshKeyRequest` | `key` | Public SSH key in OpenSSH format. |
| `SshKeyResponse` | `ok`, `type`, `success`, `machineIp`, `sshUser` | Returned after adding an SSH key. |
| `SuccessBase` | `ok`, `type` | Base success-envelope fields. |
| `UnknownEvent` | `type`, plus additional properties | Forward-compatible fallback for event types the SDK does not model yet. |
| `UpdateSandboxRequest` | `name`, `ttlSeconds` | Send only fields you want to change. `ttlSeconds: null` disables auto-stop. |
## Errors
Non-2xx responses reject with a `ResponseError`. Read the status. Parse the JSON body to get the structured Boat error envelope. Redact API keys, Boat secrets, SSH keys, and desktop URLs.
```ts theme={null}
import { ResponseError } from "@boatdev/sdk";
try {
await sandbox.get({ sandboxId: "bx_missing" });
} catch (error) {
if (error instanceof ResponseError) {
console.error(error.response.status);
console.error(await error.response.json());
}
}
```
# Setup & Scripts
Source: https://docs.boat.dev/setup
Run code inside a sandbox: setup scripts and driving setup from your own program.
<video />
There are three ways to run code in a sandbox. The first needs no code of your own. The last one runs fully from your backend. You can use them together, and most setups use more than one.
| | Runs | Best for |
| - | - | - |
| [Repository setup script](#repository-setup-scripts) | Once at start, in one repository's folder | `npm install`, migrations, anything per repository |
| [`--setup-file`](#per-sandbox-setup-file) | Once at start, per sandbox, in the background | A one-off script that differs between sandboxes |
| [Commands from your code](#driving-setup-from-your-code) | Whenever you call | Orchestration your backend controls |
Do not script heavy or slow installs. Put them in a [template sandbox](/snapshots/templates) instead. Then they are already installed when the sandbox starts.
## Repository setup scripts
You attach this script to a repository in [Dashboard > Environment](https://boat.dev/dashboard?tab=environment).
* It runs once when the sandbox starts.
* It runs inside the folder of that repository.
* Your environment variables and secret files are already in place.
```bash theme={null}
#!/bin/bash
npm install
npm run db:migrate
```
Mark the script **blocking** if the sandbox is not usable until the script finishes.
| Mode | Effect |
| - | - |
| Blocking | The sandbox reaches ready only after the script finishes. |
| Non-blocking | The script runs at the same time as everything else. |
## Talking back to the sandbox
Setup scripts can control the agent that runs in the sandbox:
| Call | Effect |
| - | - |
| `queuePrompt "your instruction"` | Sends a message to the sandbox, as if you had typed it |
| `stopAgent` | Halts the agent |
Thus a failed step becomes an instruction to the agent, and the setup does not stop there:
```bash theme={null}
#!/bin/bash
npm install || queuePrompt "npm install failed, fix the install then continue"
```
## Per-sandbox setup file
Use this when the work is different for each sandbox. Pass a local script when you create the sandbox. The limit is 64KB, UTF-8.
```bash theme={null}
boat new --setup-file ./setup.sh
```
The script runs in the background after the sandbox is ready. It never delays `ready`. Watch it with `boat info`:
| Field | Values |
| - | - |
| `setupStatus` | `pending`, `running`, `done`, `failed` |
| `setupError` | Why it failed |
## Driving setup from your code
1. Configure your secrets in the environment.
2. Run the commands that you need.
The script reads normal environment variables. It reads the secret files at their configured paths. No sensitive data goes through the command line.
<CodeGroup>
```bash CLI theme={null}
sandbox_id="$(boat new --json | jq -r 'select(.event == "ready") | .id')"
boat exec "$sandbox_id" --cwd my-repo "bash ./setup.sh"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"bash -lc ./setup.sh","cwd":"my-repo","timeoutSeconds":60}'
```
```ts TypeScript theme={null}
await sandbox.command({
sandboxId,
command: "bash -lc './setup.sh'",
cwd: "my-repo",
timeoutSeconds: 60,
});
```
```python Python theme={null}
from boat_sdk.models.command_request import CommandRequest
sandbox.command(
sandbox_id,
CommandRequest(command="bash -lc './setup.sh'", cwd="my-repo", timeout_seconds=60),
)
```
</CodeGroup>
* Wait until the sandbox is `ready`. Before that, Boat refuses calls with a retryable `boat_starting`.
* Synchronous commands stop at 600 seconds. For longer work, detach the command and poll it. Read [Long-Running Tasks](/long-running-tasks).
To pipe a script that is not on the sandbox yet, use SSH. SSH streams stdin, stdout and stderr. You do not have to copy the script to a temporary path first.
```bash theme={null}
boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```
<Note>
On Windows, run this from Node, Python, WSL, Git Bash or `cmd.exe`. Native PowerShell pipelines can keep stdin open for native executables. Then the command hangs.
</Note>
## Related
* [Environments](/environments)
* [Snapshots & Copies](/snapshots)
* [Long-Running Tasks](/long-running-tasks)
* [SSH Access](/ssh-access)
# Snapshots
Source: https://docs.boat.dev/snapshots
Boat saves the disk of your sandbox all the time. Use these saves to resume, fork, copy or download a sandbox.
<video />
A snapshot is a saved copy of the disk of your sandbox. Boat makes snapshots for you. You do not have to do anything.
* Boat saves the disk every minute while the sandbox runs.
* Boat saves it one more time when the sandbox stops.
* Each save keeps only what changed, so saves are small and fast.
## What you can do with a snapshot
| You want | Use | Command |
| - | - | - |
| Your sandbox back after a stop | [Resume](/snapshots/resume-and-fork#resume) | `boat resume <id>` |
| A second sandbox that copies this one now | [Fork](/snapshots/resume-and-fork#fork) | `boat fork <id>` |
| A fixed starting point for many sandboxes | [Template](/snapshots/templates) | `boat snapshot <id> <name>`, then `boat new --from <name>` |
| The files on your computer | [Download](/snapshots/download-and-delete) | `boat snapshot pull <snapshotId>` |
```mermaid theme={null}
flowchart LR
A[Sandbox disk] -->|every minute, and on stop| B[(Snapshots)]
B -->|boat resume| C[Same sandbox, new machine]
B -->|boat fork| D[New sandbox, copy of the disk now]
B -->|boat snapshot id name| E[Template, kept under a name]
E -->|boat new --from name| F[New sandbox, copy of the template]
B -->|boat snapshot pull| G[Files on your computer]
```
## What comes back
* Your files, your installed packages and your system settings come back.
* Your Docker volumes come back.
* Services that you enabled with systemd start again by themselves.
* Programs that you started by hand do not come back. Start them again.
* Memory and open connections do not come back.
For the full list, read [What a snapshot saves](/snapshots/whats-saved).
## A stop is safe
A stop saves the disk before Boat removes the machine. If the save fails, Boat does not stop the sandbox. You do not lose work.
Some apps keep recent changes in memory. Chrome is an example. To save these changes before a stop, use a pre-stop command. Read [Stop a sandbox](/snapshots/stop).
## Cost
* Automatic snapshots are free. Boat keeps them for the life of the sandbox.
* Named snapshots (templates) are free up to 10. Each one after that costs \$1.70 a month. Read [Named snapshot pricing](/snapshots/templates#named-snapshot-pricing).
## Learn more
<Columns>
<Card title="What a snapshot saves" icon="hard-drive" href="/snapshots/whats-saved">
Which folders come back, Docker builds, caches, and how to leave files out.
</Card>
<Card title="Stop a sandbox" icon="stop" href="/snapshots/stop">
What a stop does, how to save app state first, and what happens when a stop is refused.
</Card>
<Card title="Resume and fork" icon="code-fork" href="/snapshots/resume-and-fork">
Get your sandbox back, or make a copy. How fast a sandbox comes back.
</Card>
<Card title="Templates" icon="layer-group" href="/snapshots/templates">
Save a sandbox under a name. Deploy many sandboxes from it. Share it with another account.
</Card>
<Card title="Download and delete" icon="download" href="/snapshots/download-and-delete">
Look inside a snapshot, download its files, and delete a sandbox and its data.
</Card>
</Columns>
# Download and delete
Source: https://docs.boat.dev/snapshots/download-and-delete
Look inside a snapshot, download its files, see how long Boat keeps snapshots, and delete a sandbox and its data.
## Look inside and download
<CodeGroup>
```bash CLI theme={null}
boat snapshots # across your sandboxes
boat snapshot latest bx_f7k2q9hd
boat snapshot tree <snapshotId> # files + sizes
boat snapshot pull <snapshotId> -o ./restore # download and reassemble
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/snapshots" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/snapshots/latest" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/tree" \
-H "Authorization: Bearer $BOAT_API_KEY"
# grab one file (or a folder as .tar) straight from a snapshot; sandbox can be stopped
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/files?path=projects/app/.env" \
-H "Authorization: Bearer $BOAT_API_KEY" -o .env
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/files?path=projects/app" \
-H "Authorization: Bearer $BOAT_API_KEY" -o app.tar
```
```ts TypeScript theme={null}
await sandbox.listSnapshots(); // across your sandboxes
await sandbox.listSandboxSnapshots({ sandboxId: "bx_f7k2q9hd" }); // one sandbox's history
await sandbox.getLatestSandboxSnapshot({ sandboxId: "bx_f7k2q9hd" });
await sandbox.getSnapshotTree({ snapshotId: "<snapshotId>" }); // files + sizes
const file = await sandbox.getSnapshotFile({
snapshotId: "<snapshotId>",
path: "projects/app/.env",
});
const archive = await sandbox.getSnapshotDownload({ snapshotId: "<snapshotId>" });
```
```python Python theme={null}
sandbox.list_snapshots() # across your sandboxes
sandbox.list_sandbox_snapshots("bx_f7k2q9hd") # one sandbox's history
sandbox.get_latest_sandbox_snapshot("bx_f7k2q9hd")
sandbox.get_snapshot_tree("<snapshotId>") # files + sizes
file = sandbox.get_snapshot_file("<snapshotId>", path="projects/app/.env")
archive = sandbox.get_snapshot_download("<snapshotId>")
```
</CodeGroup>
`pull` writes two folders:
* `home_user/`: your `/home/user`.
* `docker/`: your Docker named volumes.
They hold the files exactly as they were at that snapshot.
The SDKs have no `pull`. Use `getSnapshotDownload`, then put the files together on your computer.
You can also see the files, and download them, in the [Snapshots](https://boat.dev/dashboard?tab=snapshots) tab of the dashboard.
For all calls, read the [Snapshots API](/api/reference/snapshots/list-snapshots).
## How long Boat keeps snapshots
* Boat keeps the snapshots of a stopped sandbox for the life of the sandbox. You can resume or fork it after one day or after many months.
* Boat removes old snapshots when new ones replace them.
* With [zero data retention](/data-retention), Boat deletes the data of stopped sandboxes and named snapshots. It does not keep them.
## Delete a sandbox
A stop keeps the snapshots. A **delete** removes them.
<Warning>
A delete stops the sandbox and deletes its snapshots for good. You cannot resume it, fork it or get it back. There is no list of deleted sandboxes.
**If you want to use the data later, stop the sandbox. Do not delete it.** A stopped sandbox costs nothing and keeps its disk.
</Warning>
<CodeGroup>
```bash CLI theme={null}
boat stop bx_f7k2q9hd # keeps the data; `boat resume` brings it back
boat delete bx_f7k2q9hd # deletes the sandbox AND its snapshots, permanently
boat delete bx_f7k2q9hd --yes # same, without the confirmation prompt
```
```bash curl theme={null}
curl -sS -X DELETE "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "X-Ascii-Confirm-Delete: bx_f7k2q9hd"
```
```ts TypeScript theme={null}
await sandbox.deleteSandbox({
sandboxId: "bx_f7k2q9hd",
xAsciiConfirmDelete: "bx_f7k2q9hd",
});
```
```python Python theme={null}
sandbox.delete_sandbox(
x_ascii_confirm_delete="bx_f7k2q9hd",
sandbox_id="bx_f7k2q9hd",
)
```
</CodeGroup>
* Each delete must name its sandbox. `X-Ascii-Confirm-Delete` must be the exact sandbox id. If it is not, Boat refuses the request with `409` and deletes nothing.
* A delete gives you an operation to follow. Read [Data retention and deletion](/data-retention).
* You can also delete a sandbox from the `⋯` menu on its row in the [dashboard](https://boat.dev/dashboard?tab=sandboxes).
* The sandbox leaves your account at once. Boat deletes the snapshot data when the machine has shut down.
### What a delete keeps
Sandboxes can share snapshot data. A fork, a resume and a template deploy read the same data as their source. So a delete removes only the data that nothing else uses. Boat keeps:
* The data that a fork or a resume of this sandbox still needs.
* Your **named snapshots** from this sandbox. They exist to outlive it. To remove one, run `boat snapshot rm <name>`.
Boat frees the storage when no sandbox and no named snapshot uses it.
When you remove a named snapshot, Boat deletes its data at least six hours later. This lets upload links that Boat already gave out expire first.
# Resume and fork
Source: https://docs.boat.dev/snapshots/resume-and-fork
Get a stopped sandbox back, or make a copy of a sandbox. How fast a sandbox comes back from a snapshot.
Resume and fork both start a machine from the latest snapshot of a sandbox.
| | Resume | Fork |
| - | - | - |
| You get | The same sandbox, with the same id | A new sandbox, with a new id |
| The source sandbox | Is the sandbox | Keeps running. Boat does not change it |
| Use it to | Continue your work after a stop | Try something risky, start a second branch of work, give one sandbox to each of your users |
If you fork the same sandbox again and again, make it a [template](/snapshots/templates) instead.
## Resume
A resume brings a stopped sandbox back on a new machine. The sandbox keeps its id and its disk.
<CodeGroup>
```bash CLI theme={null}
boat resume bx_f7k2q9hd
boat resume bx_f7k2q9hd --type large # different machine size
boat resume bx_f7k2q9hd --ttl 7200 # new lifetime, in seconds
boat resume bx_f7k2q9hd --no-auto-stop # runs until you stop it
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/resume" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"large","ttlSeconds":7200}'
```
```ts TypeScript theme={null}
await sandbox.resume({
sandboxId: "bx_f7k2q9hd",
type: "large", ttlSeconds: 7200,
});
```
```python Python theme={null}
sandbox.resume(sandbox_id="bx_f7k2q9hd", resume_request=ResumeRequest(type="large", ttl_seconds=7200))
```
</CodeGroup>
* A resume needs a complete snapshot. You get one when you stop the sandbox with `boat stop`.
* You can resume on a smaller machine. If the sandbox has more data than the smaller machine can hold, Boat refuses the resume and does not change the sandbox. Read [Machines](/machines).
* If you do not send `ttlSeconds`, the sandbox keeps its current lifetime.
* To turn auto-stop off, send `null` (`--no-auto-stop`).
## Fork
A fork copies a sandbox into a new sandbox. Boat uses the latest snapshot of the source. The source keeps running, and Boat does not change it.
<CodeGroup>
```bash CLI theme={null}
boat fork bx_f7k2q9hd
boat fork bx_f7k2q9hd --type small
boat fork bx_f7k2q9hd --ttl 600 # lifetime for the fork, in seconds
boat fork bx_f7k2q9hd --no-auto-stop # runs until you stop it
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/fork" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"small","ttlSeconds":600}'
```
```ts TypeScript theme={null}
const forked = await sandbox.fork({
sandboxId: "bx_f7k2q9hd",
type: "small", ttlSeconds: 600,
});
```
```python Python theme={null}
forked = sandbox.fork(sandbox_id="bx_f7k2q9hd", fork_request=ForkRequest(type="small", ttl_seconds=600))
```
</CodeGroup>
What the fork gets from the source:
* The whole disk.
* The per-sandbox variables of the source. If you send your own `env`, the fork uses yours.
* The exact environment version of the source. Read [Environments](/environments).
What the fork does not get:
* The lifetime of the source. A fork stops after 1 hour by default, even if the source has auto-stop turned off. To change this, send `ttlSeconds` or use `--no-auto-stop`.
## How fast a sandbox comes back
A resume, a fork or a deploy is ready in **a few seconds, whatever the size of the disk**. You see all your files at once. Boat downloads their content in the background.
| What | What happens |
| - | - |
| Every resume, fork and deploy | It runs on a new machine. Boat downloads your files again in the background, even if the sandbox had all its files before the stop. `hydrated` is `false` until the download ends. |
| During the download | `GET /v1/sandboxes/{id}` returns `hydration`: the step, `entriesDone` of `entriesTotal` (files, folders and links) and a `percent`. Use `hydrated` as the end signal, not `percent`. |
| A file that is not downloaded yet | When you open or read it, Boat gets that file first. Then you get the right bytes. |
| End of the download | `hydrated` becomes `true`, `hydratedAt` is set, and the `sandbox.hydrated` webhook fires. |
| Files of the machine image | They are already on every machine. Boat downloads only the files that differ from the image. |
| Paths in `.boxignore` | Boat does not save them, so it does not download them. Read [Leave files out](/snapshots/whats-saved#leave-files-out-with-boxignore). |
A restore does not need space for a second copy of your disk. Boat removes each downloaded part when it has used it. The [restore limits of each machine](/machines) count the size of your files, not the smaller download size.
Permissions, owners, times and extended attributes come back with your files and folders. Two of them come back later:
* **Extended attributes of a file** come back when the content of that file arrives. Folders have theirs from the start.
* **Folder modification times** come back when the download ends. Each new file in a folder changes the time of that folder, so Boat sets the time last.
## Make the first start faster
When a sandbox starts from a snapshot, it records which files open first. It keeps this list in `.ascii/playbook.json`. At the next start, Boat downloads these files first. Your app then works before the rest of the disk arrives. `ready` does not wait for these files.
The list is a normal file. It goes into the snapshot, so forks and deploys get it too.
The list is recorded **only while a sandbox starts from a snapshot**. Do these steps in this order:
<Steps>
<Step title="Start the sandbox from a snapshot">
Resume a stopped sandbox, or deploy one from the template that you want to update. A new, empty sandbox has nothing to record.
```bash theme={null}
boat resume bx_f7k2q9hd
```
</Step>
<Step title="Start your app at once">
Run your normal start command at once, while files still download. Boat records each file that your app opens, in order. Boat does not record files that open after the download ends.
```bash theme={null}
boat exec bx_f7k2q9hd "cd my-repo && npm run dev"
```
</Step>
<Step title="Wait for the download to end, then save">
Boat writes the list when the download ends. Save after that. If you save too early, the template does not have this run.
```bash theme={null}
boat snapshot bx_f7k2q9hd web-stack
```
</Step>
</Steps>
Each run adds to the list. It does not replace it. The newest run counts most. Each time you repeat these steps, the template starts a little faster. The list holds the first 5,000 paths.
# Stop a sandbox
Source: https://docs.boat.dev/snapshots/stop
What a stop does, how to save app state before a stop, and what happens when a stop is refused.
A stop saves the disk, then removes the machine. A stopped sandbox costs nothing. Run `boat resume` to get it back.
## What a stop does
Boat does these steps in this order:
1. Boat runs your [pre-stop command](#save-app-state-before-a-stop), if you have one.
2. Boat stops your Docker containers. Each container gets 30 seconds to exit.
3. Boat takes the last snapshot of the disk.
4. Boat turns off the machine and removes it.
Boat does not shut down the operating system. Only Docker containers get a stop signal. Your other programs get no signal.
A program that runs during the stop does not run its cleanup code. Its files go into the snapshot as they are at that moment.
To clean up, use one of these:
* Clean up when the sandbox starts again. An enabled systemd service with an `ExecStartPre=` step runs at every resume. Read [Long-Running Tasks](/long-running-tasks/always-on-services#run-an-always-on-service).
* Run your own cleanup first, then run `boat stop`.
## Save app state before a stop
Some apps keep recent changes in memory. They write them to disk later.
Chrome is an example. Chrome writes new cookies to disk every 30 seconds, or when it closes. If you stop the sandbox a few seconds after a login, the snapshot has the old cookies. A kill signal does not help, because Chrome then exits without saving.
To fix this, put a command in the file `~/.boat/pre-stop`. Boat runs it at every stop, before the last snapshot.
The example below closes Chrome. It needs Chrome to have a debug port. Start Chrome with `--remote-debugging-port=9222`.
```bash theme={null}
mkdir -p ~/.boat
cat > ~/.boat/pre-stop <<'EOF'
#!/bin/bash
# Ask Chrome to close over its debug port, so it writes its cookies.
node -e '
fetch("http://127.0.0.1:9222/json/version").then(r => r.json()).then(v => {
const ws = new WebSocket(v.webSocketDebuggerUrl);
ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: "Browser.close" }));
ws.onclose = () => process.exit(0);
}).catch(() => process.exit(0));'
# Then wait for it to exit.
for i in $(seq 30); do pgrep -f remote-debugging-port=9222 >/dev/null || exit 0; sleep 1; done
EOF
chmod +x ~/.boat/pre-stop
```
A Chrome that you started without the flag does not answer, so the command does not close it. A Chrome that you opened from the desktop is an example. Start it again with the flag.
How the pre-stop command runs:
* It runs as `user`, in your home folder.
* It has 60 seconds. After that, Boat stops it.
* It runs on `boat stop` and on auto-stop.
* It does not run on `boat stop --force`. It does not run when you save a named snapshot.
* If it fails or takes too long, the stop continues.
* The file is on the disk. Resumes, forks and templates keep it.
## When a stop is refused
A stop saves the disk first. If the save fails, Boat refuses the stop. The sandbox keeps running, so you do not lose work. Boat tries again by itself and sends you an email.
**You do not pay while the stop waits.** Billing pauses at the first refused stop. Your balance and your invoice both show the pause. You do not need to ask for a refund.
* The pause continues while the stop waits, even if you or your scripts use the sandbox.
* The pause ends when the sandbox stops.
* The pause also ends when you resume the sandbox, because a resume cancels the stop.
* If the refused stop was an auto-stop, the pause ends when you use the sandbox again.
The stop waits until a save works. Then the sandbox stops by itself.
If this happens again and again, snapshots fail on that sandbox. We get an alert. Please also [contact us](/support), so that we look at your sandbox.
To stop the sandbox now, run `boat stop --force`. The sandbox stops with its last good snapshot. **You lose everything written after that snapshot.**
After 3 days of failed saves, Boat does a forced stop by itself. Boat sends you an email before it does this.
## Stop without saving
To never save a sandbox, turn [snapshots off](/data-retention/snapshots-and-monitoring-off#snapshots-off) for your account or for one sandbox. Boat then never saves it, and a stop erases it.
# Templates
Source: https://docs.boat.dev/snapshots/templates
Save a sandbox under a name, deploy many sandboxes from it, and share it with another account.
A template is a sandbox that you save under a name. This saved copy is a **named snapshot**. Each new sandbox that you deploy from it starts with the same disk.
Use a template when many sandboxes need the same tools. You install the tools one time. You do not install them in each new sandbox.
## Automatic and named snapshots
| | Automatic snapshot | Named snapshot |
| - | - | - |
| Who makes it | Boat, every minute and at each stop | You, with `boat snapshot <id> <name>` |
| Belongs to | One sandbox | Your account or your organization |
| Kept | For the life of the sandbox. New ones replace old ones | Until you remove it, even after the sandbox is gone |
| Used by | `boat resume`, `boat fork`, `boat snapshot pull` | `boat new --from <name>` |
| Price | Free, no limit | 10 free, then \$1.70 a month each ([details](#named-snapshot-pricing)) |
## Make a template
1. Create a sandbox. Install everything: runtimes, packages, your app.
2. Save it with `boat snapshot <id> <name>`. This saves the disk as it is now, under the name.
3. Deploy each new sandbox with `boat new --from <name>`.
Each deploy is ready in a few seconds. The time and the cost stay about the same, whatever the template holds.
<CodeGroup>
```bash CLI theme={null}
boat new # install your stack, then:
boat snapshot current web-stack # freeze it under a name
boat new --from web-stack # deploy as many as you want
boat snapshots # your named snapshots, then capture history
boat snapshot rm web-stack # remove it and release its storage
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/named-snapshots" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sandboxId":"bx_23456789","name":"web-stack"}'
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"web-stack","environment":"users","env":{"TENANT_ID":"acme"}}'
```
```ts TypeScript theme={null}
await sandbox.saveNamedSnapshot({ sandboxId: "bx_23456789", name: "web-stack" });
// poll until it settles at "ready"
const saved = await sandbox.getNamedSnapshot({ name: "web-stack" });
await sandbox.create({ from: "web-stack", environment: "users", env: { TENANT_ID: "acme" } });
await sandbox.listNamedSnapshots();
await sandbox.deleteNamedSnapshot({ name: "web-stack" });
```
```python Python theme={null}
from boat_sdk.models.named_snapshot_save_request import NamedSnapshotSaveRequest
sandbox.save_named_snapshot(NamedSnapshotSaveRequest(sandbox_id="bx_23456789", name="web-stack"))
# poll until it settles at "ready"
saved = sandbox.get_named_snapshot("web-stack")
sandbox.create(CreateSandboxRequest.from_dict({
"from": "web-stack",
"environment": "users",
"env": {"TENANT_ID": "acme"},
}))
sandbox.list_named_snapshots()
sandbox.delete_named_snapshot("web-stack")
```
</CodeGroup>
<Note>
In Python, `from` is a reserved word. Build this request with `from_dict`, as above. Do not use keyword arguments.
</Note>
* If the sandbox runs, the save takes a new snapshot of its disk. This takes a moment.
* If the sandbox is stopped, the save uses its last snapshot.
* `boat snapshots` shows the size of each named snapshot.
### A template does not depend on its sandbox
A named snapshot is a full copy. The source sandbox can change, stop or be deleted. The name still deploys the exact disk that you saved.
A named snapshot does not expire.
## Update a template
Save the same name again:
1. Resume the sandbox, or use any sandbox that has the setup you want.
2. Update your tools.
3. Run `boat snapshot <id> <name>` with the same name.
The name now deploys the new disk. Boat removes the old copy. Sandboxes that you already deployed do not change.
If the new save fails, the name keeps the last good save.
## Templates and environments
A template holds the **disk**. An [environment](/environments) holds the **settings**. Most setups use both.
| | Template | Environment |
| - | - | - |
| Holds | Installed packages, builds, caches | Repositories to clone, secrets, logins |
| Answers | "What is already on this machine?" | "What can this machine use?" |
| Costs | Storage, and a few seconds per deploy | Nothing |
| To change it | Save the name again. Deployed sandboxes do not change | Boat makes a new version. Running sandboxes change only when you upgrade them |
| Used at | Deploy, one time | Every start, resume and fork |
A simple rule: what you put in a Dockerfile goes in a template. What you put in a `.env` file goes in an environment. Use both together:
```bash theme={null}
boat new --from web-stack --environment users --env TENANT_ID=acme
```
This sandbox starts with your tools installed, none of your logins, and one variable of its own.
<Warning>
A deploy from a template does **not** get the **named environment** of the source sandbox. It gets the environment from `--environment`, or your default environment. So a template that you built while logged in to your GitHub does not give that access to its deploys.
A deploy **does** get the **per-sandbox variables** of the source, the same as a fork. Each `--env KEY=VALUE` that you gave the source is set on every deploy, unless the deploy sends its own `env`. Do not put a secret in `--env` on a sandbox that you will save as a template.
</Warning>
## Named snapshot pricing
Each account and each organization has 10 free named snapshots. You can keep more. Each named snapshot after the first 10 costs \$1.70 a month.
* Boat takes this cost each day, from your Boat time (about \$0.06 a day for each one). Boat uses your plan's included usage first, then your credit packs. Sandbox time works the same way.
* When you remove a named snapshot, it stops costing from the next day.
* A save goes to your active organization, or to the one that you pass with `--org`. All members of an organization share its 10 free named snapshots.
* If a member leaves an organization, they keep their named snapshots. These then count on the member's own account.
* To save a new named snapshot after the first 10, you need credit. Without credit, the save fails with `credit_required`.
`boat snapshots` shows how many named snapshots you keep and their monthly cost. The API gives the same numbers in `allowance` on `GET /named-snapshots`.
### When your balance is empty
1. Your sandboxes get the usual grace period.
2. Your named snapshots after the first 10 get 7 days.
3. Boat sends you an email. It lists these named snapshots and the date that Boat deletes them. Boat sends a reminder one day before.
4. If your balance is still empty on that date, Boat deletes them.
Boat never deletes your 10 most recent named snapshots.
To cancel the deletion, add funds. You can also remove named snapshots until you have 10 or fewer.
## Share a template with another account
A share code lets another Boat account deploy one of your named snapshots. The other account runs `boat new --from <code>`. The new sandbox is in their account, and they pay for it.
1. Create the source sandbox.
2. Install your tools and save them: `boat snapshot <id> <name>`.
3. Make a code: `boat snapshot share <name>`. Give the code to the other account.
<CodeGroup>
```bash CLI theme={null}
boat snapshot share web-stack # prints bsh_... one time only
boat snapshot shares web-stack # list codes, use counts, status
boat snapshot unshare web-stack shr_... # revoke one code
# in the other account
boat new --from bsh_...
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/named-snapshots/web-stack/shares" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/named-snapshots/web-stack/shares" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X DELETE "$BOAT_API_BASE/named-snapshots/web-stack/shares/shr_..." \
-H "Authorization: Bearer $BOAT_API_KEY"
# in the other account
curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"bsh_..."}'
```
```ts TypeScript theme={null}
const { shareCode, share } = await sandbox.createSnapshotShare({ name: "web-stack" });
await sandbox.listSnapshotShares({ name: "web-stack" });
await sandbox.revokeSnapshotShare({ name: "web-stack", shareId: share.id });
// in the other account
await sandbox.create({ from: shareCode });
```
```python Python theme={null}
created = sandbox.create_snapshot_share("web-stack")
sandbox.list_snapshot_shares("web-stack")
sandbox.revoke_snapshot_share("web-stack", created.share.id)
# in the other account
sandbox.create(CreateSandboxRequest.from_dict({"from": created.share_code}))
```
</CodeGroup>
* Boat shows the code one time only, when you make it. Boat keeps only a hash of the code.
* If you lose a code, revoke it and make a new one.
* A code has 256 random bits. Nobody can guess it.
<Warning>
Before the other account can use its sandbox, Boat removes these from the disk: your logins and API keys, the secret files of your environment, your repository clones, and your SSH authorized keys.
Boat shares everything else on the disk. This includes secrets that you wrote into files yourself.
</Warning>
The other account gets:
* A sandbox in their account, which they pay for.
* None of your per-sandbox variables. Their own environment applies, as with any `boat new`. To use no environment, they send `noEnv: true` (`--no-env`).
What happens to a code over time:
| You do this | Result |
| - | - |
| Save the same name again | The code deploys the new save |
| Revoke the code | New deploys with the code fail. Sandboxes made before keep their copy |
| Remove the name | Boat removes its codes too. Sandboxes made before keep their copy |
| Delete your account | Sandboxes made from your codes keep their copy |
A wrong or revoked code fails with `404 snapshot_not_found`.
API keys need these scopes:
| Action | Scope |
| - | - |
| Make or revoke a code | `snapshot.write` |
| List codes | `snapshot.read` |
| Deploy from a code | `box.create` and `snapshot.read`, the same as any `from` |
# What a snapshot saves
Source: https://docs.boat.dev/snapshots/whats-saved
Which folders a snapshot saves, which it does not, and how to keep Docker builds and tool caches.
A snapshot saves the parts of the disk that you changed. It does not save the operating system that every machine already has.
## Saved and not saved
<Columns>
<Card title="Saved" icon="check">
`/home/user`: your code, files and settings
Docker **named volumes** (`/var/lib/docker/volumes`)
**Your changes** in `/etc`, `/usr`, `/opt`, `/root` and `/srv`, cron tables, and the apt package list. This means installed packages, systemd services and system settings.
</Card>
<Card title="Not saved" icon="xmark">
The operating system and the tools that come with every machine
The identity of the machine: hostname, network settings, [SSH host keys](/ssh-access#verify-the-host-key)
Your cache folder `~/.cache` ([read more](#tool-caches))
Running programs, memory and open ports
The Docker **build cache**, and images that no container uses ([read more](#docker-builds))
</Card>
</Columns>
## Deleted files stay deleted
A deletion is a change, so the snapshot saves it too. For example, remove a coding agent that comes with the machine:
```bash theme={null}
sudo rm -rf /opt/kimi-code /usr/local/bin/kimi
sudo npm uninstall -g @openai/codex
```
The agent stays gone after every resume, fork and template deploy. The same is true for an apt package that you remove.
If you install your own copy of a tool, your copy is used, not the one that comes with the machine.
## A restore is like a reboot
When a sandbox comes back from a snapshot, it is like a server that restarts.
* Your files, packages and system settings are there.
* **Systemd services that you enabled start again by themselves.**
* Programs that you started by hand are not running. Start them again, or make them a service.
* Snap packages are reinstalled.
To keep a program running across stops, read [Long-Running Tasks](/long-running-tasks).
## Docker builds
Docker and BuildKit are installed. While a sandbox runs, `docker build` uses its layer cache as usual. A rebuild with no change takes less than one second.
The layer cache is in `/var/lib/docker`, and a snapshot does not save it. After a resume, or on a fork, the first build starts from zero. It downloads its base images again.
Your running containers come back with the image they used. Only the build cache is lost.
To keep the build cache, save it in your home folder:
```bash theme={null}
docker buildx build \
--cache-to type=local,dest=$HOME/.buildcache,mode=max \
--cache-from type=local,src=$HOME/.buildcache \
--load -t myapp .
```
We measured this on a Node app with a slow dependency install:
| Build | Time |
| - | - |
| First build, no cache | 38 s |
| Rebuild on the same machine | 0.4 s |
| Rebuild on a fork, with the saved cache | 8 s |
Named volumes keep their data in all cases.
## Tool caches
A snapshot does not save `~/.cache`. Tools that download files into it download them again after a resume or a fork.
Playwright is the most common case. By default, it installs its browsers in `~/.cache/ms-playwright`.
To keep these files, install them in a different folder. For Playwright, set `PLAYWRIGHT_BROWSERS_PATH`. Put it on the **first line** of `~/.bashrc`. Then `boat ssh`, `boat ssh <id> "<command>"` and `boat exec` all use it.
```bash theme={null}
sed -i '1i export PLAYWRIGHT_BROWSERS_PATH=$HOME/.local/share/ms-playwright' ~/.bashrc
export PLAYWRIGHT_BROWSERS_PATH=$HOME/.local/share/ms-playwright
npx playwright install chromium
```
A service that runs Playwright needs the same variable. In a systemd unit, add `Environment=PLAYWRIGHT_BROWSERS_PATH=...`.
## Leave files out with `.boxignore`
Build output and dependency folders slow down every restore, and you can make them again. To leave them out of snapshots, write a `.boxignore` file. The next snapshot uses it.
```bash theme={null}
cd ~/myapp
printf 'node_modules/\n.next/\n' > .boxignore
```
* It uses the same rules as `.gitignore`.
* Its rules apply to the folder that it is in. A `.boxignore` in a repo applies to that repo. A `.boxignore` in your home folder applies to the whole sandbox.
* Boat looks for it up to six folders below your home folder. It does not look inside `node_modules`, `.next`, `target` or `vendor`.
* Put the file at the top of the folder that you want to leave out, not inside it.
* `.git` is always saved, because you cannot make it again.
* Older sandboxes also read the old name, `.oneignore`.
**Boat does not read your `.gitignore`.** A `.gitignore` lists files that you do not commit. That is not the same as files that you can lose. Also, a tool that you install with `git clone` has its own `.gitignore`. For example, the `.gitignore` of `~/.nvm` lists every Node version that you install.
# SSH Access
Source: https://docs.boat.dev/ssh-access
Connect to a sandbox over SSH from your terminal or external tools.
<video />
Sandboxes accept standard SSH connections. The Boat CLI does the usual setup for you. This includes the SSH key that it uses to connect.
## Connect with the CLI
* For an interactive shell, run `boat ssh` from your computer.
* For non-interactive commands, use the CLI, curl, the API or an SDK:
<CodeGroup>
```bash CLI theme={null}
boat ssh bx_f7k2q9hd
boat ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
boat ssh bx_f7k2q9hd -- bash -lc "cd /home/user/my-repo && npm test"
boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```
```bash curl theme={null}
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 test","cwd":"my-repo","timeoutSeconds":60}'
```
```ts TypeScript theme={null}
const result = await sandbox.command({
sandboxId: "bx_f7k2q9hd",
command: "npm test", cwd: "my-repo", timeoutSeconds: 60,
});
console.log(result.stdout);
```
```python Python theme={null}
from boat_sdk.models.command_request import CommandRequest
result = sandbox.command(
"bx_f7k2q9hd",
CommandRequest(command="npm test", cwd="my-repo", timeout_seconds=60),
)
print(result.stdout)
```
</CodeGroup>
The CLI keeps its SSH key here:
```text theme={null}
~/.ssh/ascii_box_ed25519
```
If the key is missing, the CLI creates or refreshes it. Then the CLI authorizes it on the sandbox and connects.
<Note>
* SSH works only while the machine of the sandbox runs.
* If the sandbox is archived, resume it.
* If the sandbox is still provisioning, wait until it is ready.
* In the first seconds of a resume, SSH can answer with a `sandbox_restoring` error. This error is retryable. Try again a moment later.
</Note>
## Use another SSH client
To connect from an external SSH client:
1. Authorize a public key on the sandbox.
2. Get the IP address of the sandbox.
3. Connect with your client.
<CodeGroup>
```bash CLI theme={null}
boat info bx_f7k2q9hd
ssh -i ~/.ssh/ascii_box_ed25519 user@<sandbox-ip>
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/sshkey" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"ssh-ed25519 AAAAC3Nza... you@example.com"}'
curl -sS "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.sshKey({
sandboxId: "bx_f7k2q9hd",
key: "ssh-ed25519 AAAAC3Nza... you@example.com",
});
const info = await sandbox.get({ sandboxId: "bx_f7k2q9hd" });
console.log(info.sandbox.ip);
```
```python Python theme={null}
from boat_sdk.models.ssh_key_request import SshKeyRequest
sandbox.ssh_key("bx_f7k2q9hd", SshKeyRequest(key="ssh-ed25519 AAAAC3Nza... you@example.com"))
info = sandbox.get("bx_f7k2q9hd")
print(info.sandbox.ip)
```
</CodeGroup>
## Verify the host key
Every resume and every fork runs the sandbox on a new machine. Each new machine has a new SSH host key. With strict host key checking, your client refuses the key that you saved before a stop.
`boat ssh` and `boat scp` do this for you:
1. They get the current host key through your authenticated Boat session.
2. They pin the key.
3. They connect with strict checking.
For another SSH client, get the key the same way:
1. Call the SSH key endpoint. It returns `hostKey`. This is the public host key of the machine that runs the sandbox now.
2. Save the key under a fixed alias.
3. Get the key again after each resume.
<CodeGroup>
```bash CLI theme={null}
boat ssh bx_f7k2q9hd # fetches and pins the current host key itself
```
```bash curl theme={null}
resp="$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/sshkey" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}")"
echo "bx_f7k2q9hd $(echo "$resp" | jq -r .hostKey)" > ~/.ssh/known_hosts_bx_f7k2q9hd
# sshEndpoint ("host:port") is set when the machine has no public IPv4 of its own
endpoint="$(echo "$resp" | jq -r '.sshEndpoint // empty')"
host="${endpoint%:*}"; port="${endpoint##*:}"
[ -n "$endpoint" ] || { host="$(echo "$resp" | jq -r .machineIp)"; port=22; }
ssh -p "$port" \
-o StrictHostKeyChecking=yes \
-o UserKnownHostsFile=~/.ssh/known_hosts_bx_f7k2q9hd \
-o HostKeyAlias=bx_f7k2q9hd \
user@"$host"
```
```ts TypeScript theme={null}
const { hostKey, machineIp, sshEndpoint } = await sandbox.sshKey({
sandboxId: "bx_f7k2q9hd",
key: "ssh-ed25519 AAAAC3Nza... you@example.com",
});
// write `bx_f7k2q9hd ${hostKey}` to a known_hosts file, then connect with HostKeyAlias=bx_f7k2q9hd
// to sshEndpoint ("host:port") when it is set, else to machineIp on port 22
```
```python Python theme={null}
from boat_sdk.models.ssh_key_request import SshKeyRequest
resp = sandbox.ssh_key("bx_f7k2q9hd", SshKeyRequest(key="ssh-ed25519 AAAAC3Nza... you@example.com"))
# write f"bx_f7k2q9hd {resp.host_key}" to a known_hosts file, then connect with HostKeyAlias=bx_f7k2q9hd
# to resp.ssh_endpoint ("host:port") when it is set, else to resp.machine_ip on port 22
```
</CodeGroup>
The key comes over your API connection, not over SSH. So you can trust it without a first-connection prompt.
## Copy files
* From a terminal, use `boat scp` with the sandbox ID as the remote host.
* In an integration, use the file and artifact API calls.
<CodeGroup>
```bash CLI theme={null}
boat scp ./local-file.txt bx_f7k2q9hd:/home/user/
boat scp bx_f7k2q9hd:/home/user/output.zip ./output.zip
```
```bash curl theme={null}
curl -sS -X PUT "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path":"notes/input.txt","content":"hello\n","encoding":"utf8"}'
curl -L -o output.zip "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/artifacts?path=output.zip" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.writeFile({
sandboxId: "bx_f7k2q9hd",
path: "notes/input.txt", content: "hello\n", encoding: "utf8",
});
const artifact = await sandbox.artifact({ sandboxId: "bx_f7k2q9hd", path: "output.zip" });
```
```python Python theme={null}
from boat_sdk.models.file_write_request import FileWriteRequest
sandbox.write_file("bx_f7k2q9hd", FileWriteRequest(
path="notes/input.txt",
content="hello\n",
encoding="utf8",
))
artifact = sandbox.artifact("bx_f7k2q9hd", "output.zip")
```
</CodeGroup>
File read and write paths follow these rules:
| Path | Rule |
| - | - |
| Relative | Boat resolves it from the sandbox work directory, `/home/user`. |
| Absolute | It must resolve under `/home/user` or `/tmp`. |
| Absolute, outside these roots | Boat refuses it with a 400 `invalid_path` error. The error names the allowed roots. |
### Large files
The JSON file calls stop at 5 MiB. For a larger file, ask for a signed URL and send the bytes straight to the sandbox. The sandbox serves the URL itself, so there is no size limit of ours and no Authorization header on the transfer.
<CodeGroup>
```bash curl theme={null}
# Upload: get a URL, then PUT the raw file to it
url=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files/upload-url" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"path":"data/dataset.parquet"}' | jq -r .url)
curl -sS -X PUT --data-binary @dataset.parquet "$url"
# Download: get a URL, then GET it
url=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files/download-url" \
-H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
-d '{"path":"output/model.bin"}' | jq -r .url)
curl -sS -o model.bin "$url"
```
```ts TypeScript theme={null}
const up = await sandbox.createUploadUrl({ sandboxId: "bx_f7k2q9hd", path: "data/dataset.parquet" });
await fetch(up.url, { method: "PUT", body: await fs.readFile("dataset.parquet") });
const down = await sandbox.createDownloadUrl({ sandboxId: "bx_f7k2q9hd", path: "output/model.bin" });
const bytes = await (await fetch(down.url)).arrayBuffer();
```
```python Python theme={null}
import requests
from boat_sdk.models.file_url_request import FileUrlRequest
up = sandbox.create_upload_url("bx_f7k2q9hd", FileUrlRequest(path="data/dataset.parquet"))
with open("dataset.parquet", "rb") as f:
requests.put(up.url, data=f)
down = sandbox.create_download_url("bx_f7k2q9hd", FileUrlRequest(path="output/model.bin"))
open("model.bin", "wb").write(requests.get(down.url).content)
```
</CodeGroup>
* A URL works for one path and one direction (download or upload).
* It expires after 15 minutes. Pass `ttlSeconds` (up to 3600) to change that.
* An upload creates missing directories. It replaces an existing file only when the upload completes.
* Anyone who has the URL can use it until it expires. Do not log it or share it.
* Getting a download URL needs `file.read`; getting an upload URL needs `file.write`.
For all `scp` options, read [CLI Reference](/cli-reference#boat-scp).
## Related
* [Environments](/environments)
* [Long-Running Tasks](/long-running-tasks)
* [Desktop Streaming](/desktop-streaming)
* [Hosting](/hosting)
# Support
Source: https://docs.boat.dev/support
How to reach the Boat team, and what to send so we can help on the first reply.
## Contact
| Channel | Use it for |
| - | - |
| Email [support@ascii.dev](mailto:support@ascii.dev) | Account, billing, a sandbox that misbehaves, anything private. |
| [Discord](https://discord.gg/Y3TFTmE89g) | Questions, ideas, and help from the team and other users. |
You do not need to contact us to use a feature that your plan includes. For example, `xlarge` needs only the \$100 plan or higher. See [Pricing & Limits](/pricing).
## What to send
* The email address of your Boat account.
* The sandbox ID, for example `bx_23456789`, if one sandbox is affected.
* The command or API call you ran, and the full error text.
* The time it happened, with your time zone.
Do not send API keys, passwords or secret files. We never ask for them.
# Webhooks
Source: https://docs.boat.dev/webhooks
Receive signed notifications when a sandbox becomes ready, finishes restoring, errors, or archives.
<video />
A webhook sends sandbox lifecycle events to your HTTPS endpoint. One webhook gets the events of all the sandboxes in your account.
Use webhooks to:
* Start work when a sandbox is usable.
* Respond when a sandbox fails to start.
* Continue an automation after a sandbox stops.
| | CLI | API | SDKs | Dashboard |
| - | - | - | - | - |
| Register | `boat webhook create` | `POST /webhooks` | `createWebhook` | [Webhooks](https://boat.dev/dashboard?tab=webhooks) |
| List / read | `boat webhook list` | `GET /webhooks`, `GET /webhooks/{id}` | `listWebhooks`, `getWebhook` | [Webhooks](https://boat.dev/dashboard?tab=webhooks) |
| Edit in place | not available | `PATCH /webhooks/{id}` | `updateWebhook` | not available |
| Rotate secret | `boat webhook rotate` | `POST /webhooks/{id}/rotate` | `rotateWebhookSigningSecret` | [Webhooks](https://boat.dev/dashboard?tab=webhooks) |
| Remove | `boat webhook remove` | `DELETE /webhooks/{id}` | `deleteWebhook` | [Webhooks](https://boat.dev/dashboard?tab=webhooks) |
| Delivery history | not available | not available | not available | [Webhooks](https://boat.dev/dashboard?tab=webhooks) → Deliveries |
## Register an endpoint
<CodeGroup>
```bash CLI theme={null}
boat webhook create https://example.com/hooks/sandbox \
--name production \
--event ready \
--event error \
--event archived
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/webhooks" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "production",
"url": "https://example.com/hooks/sandbox",
"events": ["sandbox.ready", "sandbox.error", "sandbox.archived"]
}'
```
```ts TypeScript theme={null}
const created = await sandbox.createWebhook({
name: "production",
url: "https://example.com/hooks/sandbox",
events: new Set(["sandbox.ready", "sandbox.error", "sandbox.archived"]),
});
console.log(created.webhook.id, created.secret); // secret is shown once
```
```python Python theme={null}
from boat_sdk.models.webhook_create_request import WebhookCreateRequest
created = sandbox.create_webhook(WebhookCreateRequest(
name="production",
url="https://example.com/hooks/sandbox",
events=["sandbox.ready", "sandbox.error", "sandbox.archived"],
))
print(created.webhook.id, created.secret) # secret is shown once
```
</CodeGroup>
How to name events:
| Surface | Event names | If you give no event |
| - | - | - |
| CLI `--event` | `ready`, `error`, `archived` or `hydrated`. The `sandbox.` prefix is optional. | You get all four events. |
| API and SDKs | The full name, for example `sandbox.ready`. | The call fails. You must give at least one event. |
The call returns a signing secret that starts with `whsec_`. **You see this secret only once.** Store it in your secret manager.
<Note>
The endpoint must use HTTPS on port 443. Its address must resolve only to public IP addresses. Boat does not follow redirects. An account can register up to 10 endpoint URLs.
</Note>
## Manage endpoints
<CodeGroup>
```bash CLI theme={null}
boat webhook list
boat webhook rotate <id> # replaces the signing secret
boat webhook remove <id>
```
```bash curl theme={null}
curl -sS "$BOAT_API_BASE/webhooks" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X PATCH "$BOAT_API_BASE/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":["sandbox.error"]}'
curl -sS -X POST "$BOAT_API_BASE/webhooks/$WEBHOOK_ID/rotate" \
-H "Authorization: Bearer $BOAT_API_KEY"
curl -sS -X DELETE "$BOAT_API_BASE/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $BOAT_API_KEY"
```
```ts TypeScript theme={null}
await sandbox.listWebhooks();
await sandbox.getWebhook({ webhookId: "wh_0123456789abcdef01234567" });
await sandbox.updateWebhook({
webhookId: "wh_0123456789abcdef01234567",
events: new Set(["sandbox.error"]),
});
const rotated = await sandbox.rotateWebhookSigningSecret({ webhookId: "wh_0123456789abcdef01234567" });
console.log(rotated.secret);
await sandbox.deleteWebhook({ webhookId: "wh_0123456789abcdef01234567" });
```
```python Python theme={null}
from boat_sdk.models.webhook_update_request import WebhookUpdateRequest
sandbox.list_webhooks()
sandbox.get_webhook("wh_0123456789abcdef01234567")
sandbox.update_webhook(
"wh_0123456789abcdef01234567",
WebhookUpdateRequest(events=["sandbox.error"]),
)
rotated = sandbox.rotate_webhook_signing_secret("wh_0123456789abcdef01234567")
print(rotated.secret)
sandbox.delete_webhook("wh_0123456789abcdef01234567")
```
</CodeGroup>
The [Webhooks](https://boat.dev/dashboard?tab=webhooks) tab of the dashboard does the same tasks. Only the dashboard shows the delivery history.
<Note>
Only the API and SDKs can change the name, URL or events of an endpoint in place (`PATCH /webhooks/{webhookId}`). The CLI and the dashboard cannot edit an endpoint. Delete it and create it again. This gives you a new signing secret.
</Note>
When you rotate the secret, accept the old secret and the new secret for a short time. A delivery attempt that already started can still carry the old signature.
When you delete an endpoint, Boat removes its queued deliveries. A delivery attempt that already started can still arrive.
## Events
| Event | Boat sends it when |
| - | - |
| `sandbox.ready` | A sandbox becomes usable (`ready`, `idle` or `running`) after it was not usable. This includes recovery from an error. |
| `sandbox.hydrated` | A restored sandbox finishes materializing. See [After a restore](#after-a-restore). |
| `sandbox.error` | A sandbox enters `error`. |
| `sandbox.archived` | A sandbox finishes stopping and enters `archived`. |
| `sandbox.degraded` | The machine is alive, but Boat cannot fully reach it. Boat sends this about a minute after the machine stops answering. The sandbox keeps running. Boat does not stop it. `data.reason` gives the cause. |
| `sandbox.recovered` | A degraded sandbox is fully reachable again. This happens on the same machine, or on a new machine after a resume or an automatic recovery. |
Boat creates `sandbox.ready`, `sandbox.error` and `sandbox.archived` in the same database transaction as the state change.
### After a restore
`sandbox.hydrated` arrives after `sandbox.ready`. It can arrive at the same moment, or minutes later.
1. The sandbox becomes `ready`. Boat sends `sandbox.ready`.
2. The Docker containers of the sandbox start as soon as their images load.
3. The background disk copy finishes. The Docker volumes move onto the real disk.
4. Each running container's volume mounts move onto the real disk in place. The containers pause for about 0.1 s. They do not restart.
5. Boat sends `sandbox.hydrated`.
To poll instead, read `hydrated` and `hydratedAt` on `GET /sandboxes/{id}`.
### Degraded sandboxes
A degraded sandbox shows `"health": "degraded"` and a `healthReason` on `GET /sandboxes/{id}`. The most common cause is a firewall rule inside the sandbox that blocks the Boat tunnel. See [Firewall rules](/hosting/firewall).
## Payload
```json theme={null}
{
"id": "evt_2af97cd17a8248bb8fe37653a235bc91",
"type": "sandbox.ready",
"createdAt": "2026-08-11T12:00:00.000Z",
"data": {
"sandbox": {
"id": "bx_23456789",
"name": "Production worker"
},
"previousState": "cloning",
"state": "ready"
}
}
```
* `data.sandbox.id` is the public sandbox ID.
* Use the top-level event `id` as an idempotency key.
The fields in `data` change with the event:
| Event | `previousState` | `state` | `reason` |
| - | - | - | - |
| `sandbox.ready`, `sandbox.error`, `sandbox.archived` | yes | yes | no |
| `sandbox.hydrated` | no | no | no |
| `sandbox.degraded`, `sandbox.recovered` | no | yes | yes |
## Verify signatures
Each request has these headers:
| Header | Value |
| - | - |
| `X-Ascii-Event` | Event type |
| `X-Ascii-Delivery` | Stable event ID |
| `X-Ascii-Timestamp` | Unix timestamp for this attempt |
| `X-Ascii-Signature` | `v1=` followed by a hex HMAC-SHA256 signature |
| `X-Ascii-Attempt` | Attempt number, starting at 1 |
To verify a request:
1. Compute the expected signature over the exact raw request body:
```text theme={null}
HMAC_SHA256(secret, delivery_id + "." + timestamp + "." + raw_body)
```
2. Compare the signatures in constant time.
3. Reject old timestamps.
4. Deduplicate on the delivery ID.
<CodeGroup>
```ts TypeScript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";
function verifyWebhook(rawBody: Buffer, headers: Headers, secret: string) {
const id = headers.get("x-ascii-delivery") ?? "";
const timestamp = headers.get("x-ascii-timestamp") ?? "";
const supplied = (headers.get("x-ascii-signature") ?? "").replace(/^v1=/, "");
const expected = createHmac("sha256", secret)
.update(`${id}.${timestamp}.`)
.update(rawBody)
.digest("hex");
const issuedAt = Number(timestamp);
if (!Number.isFinite(issuedAt) || Math.abs(Date.now() / 1000 - issuedAt) > 300) return false;
if (!/^[a-f0-9]{64}$/i.test(supplied)) return false;
return timingSafeEqual(Buffer.from(supplied, "hex"), Buffer.from(expected, "hex"));
}
```
```python Python theme={null}
import hmac, re, time
from hashlib import sha256
def verify_webhook(raw_body: bytes, headers, secret: str) -> bool:
delivery = headers.get("x-ascii-delivery", "")
timestamp = headers.get("x-ascii-timestamp", "")
supplied = headers.get("x-ascii-signature", "").removeprefix("v1=")
try:
if abs(time.time() - float(timestamp)) > 300:
return False
except ValueError:
return False
if not re.fullmatch(r"[a-fA-F0-9]{64}", supplied):
return False
expected = hmac.new(
secret.encode(),
f"{delivery}.{timestamp}.".encode() + raw_body,
sha256,
).hexdigest()
return hmac.compare_digest(supplied.lower(), expected)
```
</CodeGroup>
<Warning>
Verify the raw bytes before you parse the JSON. If you serialize the body again, the signature changes.
</Warning>
## Delivery and retries
| Your endpoint | What Boat does |
| - | - |
| Returns a `2xx` | Marks the event as delivered. |
| Returns another status, fails to connect, or takes more than 5 seconds | Retries with exponential backoff, up to 8 attempts. |
* Delivery is **at least once**. The same event ID can arrive more than once.
* Events can arrive out of order. Use the ID, creation time and state of each event. Do not rely on the request order.
* Return a `2xx` quickly. Move slow work to your own queue.
* Boat keeps completed and exhausted delivery records for 30 days.
## Inspect deliveries
1. Open [Webhooks](https://boat.dev/dashboard?tab=webhooks) in the Boat dashboard.
2. Expand **Deliveries** next to an endpoint.
The log of recent deliveries shows:
* The event that Boat sent.
* The exact payload.
* The Boat ID and the event ID.
* The number of attempts.
* The HTTP result, or a connection diagnostic.
* The time of the next retry, if there is one.
# Windows Apps
Source: https://docs.boat.dev/windows-apps
Run Windows-only desktop software in a sandbox with Wine, let an agent drive it, and fork the set-up sandbox.
<video />
A sandbox runs Windows programs on its Linux desktop through [Wine](https://www.winehq.org).
* The programs open as normal windows on the [desktop stream](/desktop-streaming). You can watch them.
* The agents of the sandbox can click, type and read them with the built-in [`computer` tools](/integrated-agents/computer-use).
* You install once. Then you [fork](/snapshots) the set-up sandbox as many times as you need.
## Main task
1. [Install Wine](/windows-apps/install-wine) in the sandbox. It takes about 5 minutes.
2. [Install and start the app](/windows-apps/run-apps). Every GUI command needs `DISPLAY=:0`.
3. [Give a prompt to an agent](/windows-apps/agents-and-forks#let-an-agent-drive-it) that uses the app.
4. [Fork the sandbox](/windows-apps/agents-and-forks#set-up-once-fork-many-times) for each task.
## Learn more
<Columns>
<Card title="Tested apps" icon="list-check" href="/windows-apps/tested-apps">
The apps that run, the extra steps they need, and the apps that do not run.
</Card>
<Card title="Install Wine" icon="download" href="/windows-apps/install-wine">
The install script, and what each part of it does.
</Card>
<Card title="Run an app" icon="play" href="/windows-apps/run-apps">
Install and start an app. Recipes for Steam, Paint.NET, Sysinternals and Direct3D games.
</Card>
<Card title="Agents and forks" icon="code-fork" href="/windows-apps/agents-and-forks">
Let an agent drive the app. Set up once, then fork many times.
</Card>
<Card title="Troubleshooting" icon="wrench" href="/windows-apps/troubleshooting">
Common errors and their fixes. Licence rules.
</Card>
</Columns>
## Related
* [Desktop Streaming](/desktop-streaming)
* [Computer use](/integrated-agents/computer-use)
* [Snapshots & Copies](/snapshots)
* [Long-Running Tasks](/long-running-tasks)
# Agents and forks
Source: https://docs.boat.dev/windows-apps/agents-and-forks
Let an agent drive a Windows app in a sandbox. Set up the sandbox once, then fork it for each task.
## Let an agent drive it
The Windows apps open as ordinary windows on the sandbox desktop. A prompt is enough:
<CodeGroup>
```bash CLI theme={null}
boat prompt bx_f7k2q9hd --provider claude "Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV"
```
```bash curl theme={null}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/prompt" \
-H "Authorization: Bearer $BOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"claude","prompt":"Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV"}'
```
```ts TypeScript theme={null}
await sandbox.prompt({
sandboxId: "bx_f7k2q9hd",
provider: "claude",
prompt: "Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV",
});
```
```python Python theme={null}
sandbox.prompt("bx_f7k2q9hd", PromptRequest(
provider="claude",
prompt="Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV",
))
```
</CodeGroup>
For scripted steps, `xdotool` and `wmctrl` are installed. Examples:
* `wmctrl -l` lists the open windows.
* `wmctrl -a HeidiSQL` brings one window to the front.
To record the run, use [`ascii-record-desktop`](/desktop-streaming/drive-and-record#record-the-screen).
## Set up once, fork many times
The Wine set-up is in `~/.wine` and in the system packages. Stop, resume and fork keep both.
In our test, a sandbox with Wine and 40 Windows apps (16 GB) gave these results:
| Action | Time | Result |
| - | - | - |
| Fork | About 2 minutes until the desktop accepts windows | Every app starts. Notepad++ keeps its unsaved text. |
| Stop | 4 seconds | |
| Resume | 20 to 32 seconds, on a different machine | Every app starts. |
To use this:
1. Make one sandbox with the apps that your agents need.
2. Fork it for each task. Read [Snapshots & Copies](/snapshots).
<Note>
Running Windows programs do not survive a stop or a fork. Start them again after a resume.
</Note>
# Install Wine
Source: https://docs.boat.dev/windows-apps/install-wine
Install Wine and the Windows runtimes in a sandbox with one script.
Run this script one time inside the sandbox. It takes about 5 minutes.
## Run the script
1. Save the script below as `install-wine.sh` on your computer.
2. Send it to the sandbox in one of these ways:
| Surface | How |
| - | - |
| CLI | `boat ssh bx_f7k2q9hd 'bash -s' < install-wine.sh` |
| API | Pass the script as the `command` of [`POST /sandboxes/{sandboxId}/commands`](/api/reference/agent/execute-sandbox-command), with `detached: true`. |
| SDK | Pass the script to the `command` call, with `detached: true`. |
3. For the API and the SDK, poll the command status until the command finishes.
<Warning>
Without `detached`, the command stops after its 30-second default timeout. Wine is then only half installed.
</Warning>
```bash install-wine.sh theme={null}
set -e
sudo dpkg --add-architecture i386
sudo mkdir -pm755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/winehq-archive.key https://dl.winehq.org/wine-builds/winehq.key
sudo wget -qNP /etc/apt/sources.list.d/ https://dl.winehq.org/wine-builds/ubuntu/dists/noble/winehq-noble.sources
printf 'Package: libgd3\nPin: release o=Ubuntu\nPin-Priority: 1001\n' | sudo tee /etc/apt/preferences.d/wine-libgd3
sudo apt-get update -qq
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --allow-downgrades --no-install-recommends \
winehq-staging mesa-vulkan-drivers mesa-vulkan-drivers:i386 cabextract p7zip-full
sudo wget -qO /usr/local/bin/winetricks https://raw.githubusercontent.com/Winetricks/winetricks/master/src/winetricks
sudo chmod +x /usr/local/bin/winetricks
export DISPLAY=:0
WINEDLLOVERRIDES="mscoree,mshtml=" wineboot -i
winetricks -q corefonts vcrun2022 dxvk d3dcompiler_47
wine --version
```
## What each part does
| Part | Why it is there |
| - | - |
| **WineHQ staging** | Ubuntu's own Wine is version 9. Steam, Paint.NET 5.2 and Direct3D games need Wine 11 or newer. |
| **The `libgd3` pin** | The sandbox has a PHP repository. Its `libgd3` exists only for 64-bit. 32-bit Wine needs the same version for both. The pin selects Ubuntu's version. As a side effect, PHP's `gd` extension is removed. |
| **`mesa-vulkan-drivers`** | A sandbox has no GPU. This software Vulkan driver lets DXVK run Direct3D 8 to 11 on the CPU. |
| **`WINEDLLOVERRIDES="mscoree,mshtml="`** | A new Wine set-up opens a "Wine Mono Installer" window and waits for a click. This setting skips that window. Apps that need .NET get Microsoft's runtime from winetricks instead. |
| **winetricks** | Installs Microsoft's free redistributables: core fonts, the Visual C++ 2015 to 2022 runtime, DXVK and the Direct3D shader compiler. |
## Next step
[Run an app](/windows-apps/run-apps).
# Run an app
Source: https://docs.boat.dev/windows-apps/run-apps
Install and start a Windows app in a sandbox. Recipes for Steam, Paint.NET, Sysinternals and Direct3D games.
Before you start, [install Wine](/windows-apps/install-wine).
## Install and start an app
1. Download the official installer or portable archive in the sandbox.
2. Install it.
3. Start it on the desktop. Every GUI command needs `DISPLAY=:0`.
This example installs the MicroDicom medical image viewer and opens a CT scan:
```bash theme={null}
export DISPLAY=:0
curl -fsSL -o /tmp/microdicom.exe https://www.microdicom.com/downloads/Software/MicroDicom-2026.4-Setup.exe
wine /tmp/microdicom.exe /S
curl -fsSL -o ~/CT_small.dcm https://github.com/pydicom/pydicom/raw/main/src/pydicom/data/test_files/CT_small.dcm
cd "$HOME/.wine/drive_c/Program Files/MicroDicom"
wine mDicom.exe 'Z:\home\user\CT_small.dcm' &
```
On the first start, MicroDicom asks to become the default viewer. It does not open the file. To open the scan:
1. Press Escape.
2. Close MicroDicom.
3. Run the last command again.
After this, the scan opens immediately.
## Tips
* Use `wine start /unix <path>` to start a program. `start` gives the program normal Windows console handles. Without it, programs written in Python (Blender, FreeCAD) and many others crash.
* Most installers have a silent switch:
| Installer type | Silent switch |
| - | - |
| NSIS | `/S` |
| Inno Setup | `/VERYSILENT` |
| MSI | `msiexec /i app.msi /qn` |
* To find an official download link, open the app's manifest in [winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests). The `InstallerUrl` field is the vendor's own link.
* Windows paths map to Linux paths:
| Windows path | Linux path |
| - | - |
| `C:\` | `~/.wine/drive_c` |
| `Z:\` | The Linux root `/` |
## Steam
Steam has these needs:
* It needs the Arial font.
* It must not use Wine's DirectWrite.
* Its web view must not use a GPU.
```bash theme={null}
export DISPLAY=:0
winetricks -q arial
wine reg add 'HKCU\Software\Wine\AppDefaults\steam.exe\DllOverrides' /v dwrite /t REG_SZ /d '' /f
curl -fsSL -o /tmp/SteamSetup.exe https://cdn.cloudflare.steamstatic.com/client/installer/SteamSetup.exe
wine /tmp/SteamSetup.exe /S
wine start 'C:\Program Files (x86)\Steam\steam.exe' -no-dwrite -cef-disable-gpu -cef-disable-sandbox
```
The first start updates Steam and takes about 2 minutes. Then the sign-in window opens.
## Paint.NET
Paint.NET 5.2 has a separate [build for Wine](https://github.com/paintdotnet/Paint.NET-on-Wine).
* It needs Wine 11.15 or newer. The [Wine set-up](/windows-apps/install-wine) installs this version.
* Its installer makes its own Wine set-up and needs Wine Mono. So it opens the "Wine Mono Installer" window.
* The `xdotool` loop below presses **Install** for you.
```bash theme={null}
export DISPLAY=:0
mkdir -p ~/apps/paintnet && cd ~/apps/paintnet
curl -fsSL -o pdn.zip "$(curl -s https://api.github.com/repos/paintdotnet/Paint.NET-on-Wine/releases \
| grep -o '"browser_download_url": *"[^"]*x64[^"]*\.zip"' | cut -d'"' -f4 | head -1)"
unzip -q pdn.zip
( for i in $(seq 1 120); do
w=$(wmctrl -l | grep 'Wine Mono Installer' | awk '{print $1}')
[ -n "$w" ] && { wmctrl -i -a $w; sleep 0.5; xdotool key Return; break; }
sleep 2
done ) &
./install.sh
./paintdotnet.sh &
```
* Use the `x64` file. The release also has an `arm64` file. That file does not run on a sandbox.
* The Wine build is experimental. It expires 12 weeks after its build date. When it expires, download a new one.
* Paint.NET 5.1 and older do not run.
## Sysinternals
Process Explorer and Autoruns show a licence window on the first start. Accept the licence before the start, so that an agent does not have to. Autoruns rejects the `/accepteula` flag. So set the registry value for both apps:
```bash theme={null}
export DISPLAY=:0
curl -fsSL -o /tmp/procexp.zip https://download.sysinternals.com/files/ProcessExplorer.zip
curl -fsSL -o /tmp/autoruns.zip https://download.sysinternals.com/files/Autoruns.zip
mkdir -p ~/apps/sysinternals && cd ~/apps/sysinternals
unzip -qo /tmp/procexp.zip && unzip -qo /tmp/autoruns.zip
wine reg add 'HKCU\Software\Sysinternals\Process Explorer' /v EulaAccepted /t REG_DWORD /d 1 /f
wine reg add 'HKCU\Software\Sysinternals\Autoruns' /v EulaAccepted /t REG_DWORD /d 1 /f
wine start /unix ~/apps/sysinternals/procexp64.exe
```
## Direct3D games
DXVK from the Wine set-up runs Direct3D 8, 9, 10 and 11 games on the software Vulkan driver.
| Game type | Speed |
| - | - |
| Simple 2D games and older 3D games | Playable |
| Modern 3D games | Too slow without a GPU |
Old games that change the screen resolution can leave a full-screen window over the desktop. To stop Wine from changing the resolution, run:
```bash theme={null}
wine reg add 'HKCU\Software\Wine\X11 Driver' /v UseXRandR /t REG_SZ /d N /f
wine reg add 'HKCU\Software\Wine\X11 Driver' /v UseXVidMode /t REG_SZ /d N /f
```
# Tested apps
Source: https://docs.boat.dev/windows-apps/tested-apps
Windows apps that run in a Boat sandbox with Wine, the extra steps they need, and the apps that do not run.
Every app below ran on a Boat sandbox with the set-up from [Install Wine](/windows-apps/install-wine). The "Extra step" column gives what the app needs in addition to that set-up.
## Apps that run
| App | What it is | Extra step |
| - | - | - |
| Notepad++, HxD, WinMerge, Everything | Editors, hex, diff, file search | None |
| WinRAR, 7-Zip, WinDirStat | Archives, disk usage | None |
| HeidiSQL | Database client | None |
| Winamp, foobar2000, MPC-HC, IrfanView, FastStone, XnView | Media and image viewers | None |
| LTspice | Circuit simulator | None |
| FORScan | Car diagnostics | None |
| x64dbg | Debugger | None |
| Process Explorer, Autoruns | Microsoft Sysinternals | [Accept the licence first](/windows-apps/run-apps#sysinternals) |
| MicroDicom, RadiAnt | Medical image (DICOM) viewers | RadiAnt asks you to start its free trial |
| Steam | Game store client | [Steam](/windows-apps/run-apps#steam) |
| Paint.NET 5.2 | Image editor | [Paint.NET](/windows-apps/run-apps#paintnet) |
| Spelunky, Cave Story | Games | None. Direct3D runs through DXVK. |
| ImgBurn | Disc image tool | None |
## Apps that do not run
No set-up makes these apps work.
| App | Why |
| - | - |
| CPU-Z | Opens with a driver error. It loads a Windows kernel driver, and Wine cannot load kernel drivers. |
| Paint.NET 5.1 and older | Needs a Windows system file that Wine does not have. Use 5.2. |
| CCleaner | Starts, then opens no window. |
| SkiFree and other 16-bit Windows 3.1 programs | They run, but their emulator slows every other Wine window. Run them alone. |
| SketchUp Make 2017 | Discontinued. Trimble removed the download. |
# Troubleshooting
Source: https://docs.boat.dev/windows-apps/troubleshooting
Fix common errors when you run Windows apps with Wine in a sandbox. Licence rules.
## Common errors
| Symptom | Cause | Fix |
| - | - | - |
| `apt-get` says `libgd3:i386` "is not going to be installed" | The `libgd3` from the PHP repository | Add the `libgd3` pin from [Install Wine](/windows-apps/install-wine#what-each-part-does) |
| `wineboot` never finishes | The "Wine Mono Installer" window waits for a click | `WINEDLLOVERRIDES="mscoree,mshtml=" wineboot -i` |
| `Cannot open display` | The command does not know the desktop | `export DISPLAY=:0` |
| A Python-based app exits immediately with `init_sys_streams` | No Windows console handles | Start it with `wine start /unix` |
| `unimplemented function msvcp140.dll...` | Old Visual C++ runtime | `winetricks -q vcrun2022` |
| Windows go blank and show "Not Responding" | A window was closed from Linux with `wmctrl -c` or the title bar while it held a modal dialog | Answer dialogs with keys (`xdotool key Return`). Do not close them from outside. |
| Every Wine window is slow | A 16-bit Windows 3.1 program is running. Its emulator keeps Wine busy. | Close it. Run 16-bit programs on their own. |
| A game covers the whole desktop | It changed the screen resolution | Set `UseXRandR` and `UseXVidMode` to `N`. Read [Direct3D games](/windows-apps/run-apps#direct3d-games). |
## Licences
* Install only software that you have the right to use.
* Download it from the vendor, as on these pages.
* Do not copy Windows system files into Wine. Microsoft's licence does not allow it.
* Wine does not need Windows system files for the apps on these pages.
* The winetricks components on these pages are Microsoft's free redistributables.