Python SDK - boat

Install the Python package:

python -m pip install boat-sdk

Import BoatApi, configure auth, and call snake_case methods like sandbox.create, sandbox.prompt, and sandbox.events.

Configure

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)

Request models live under boat_sdk.models. Prompting requires the selected provider (harness) to be configured for the authenticated account. Providers are codex, claude-code (alias claude), pi, opencode, prime-agent (alias prime), kimi, and mistral; omit provider to use the account’s dashboard default. If the selected provider’s credentials are missing, sandbox.prompt(...) raises ApiException with code provider_not_configured. A Sandbox runs many conversations in parallel: pass new=True to start a fresh one or conversation_id to continue a specific one, and read conversation_id back off the response.

Create, prompt, and clean up

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

Pass type to create a bigger Boat. large consumes machine time at 2x, small at half rate. A fork inherits the source sandbox’s type, and passing type to resume or fork moves a sandbox between sizes.

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 and Pricing.

Per-sandbox environment variables

Pass env to inject variables into a single sandbox, on top of your account-level secrets (per-sandbox values win on name conflicts). At most 100 variables, 64KB total.

created = sandbox.create(CreateSandboxRequest(
    ttl_seconds=3600,
    env={"DATABASE_URL": "postgres://user:pass@host:5432/app", "FEATURE_FLAG": "1"},
))

Forked Sandboxes inherit the source sandbox’s env unless the fork supplies its own.

No-env sandboxes

When you hand a sandbox to your own end users, create it with no_env=True so none of your account secrets reach it. Model keys, GitHub token, dashboard environment variables, SSH identity, and secret files are all withheld. SSH, desktop, snapshots, public URLs, and forks still work. A fork of a no-env Boat is always no-env and cannot be downgraded.

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

All methods are called 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 Sandboxes for 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.
`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 snapshots the disk first; if that is failing the stop is refused and the sandbox keeps running (you are not billed for that time). Pass `StopRequest(force=True)` to stop anyway and permanently lose everything written since the last successful snapshot.
`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 source sandbox snapshot. 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.
`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 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 by default; pass `conversation=<id>` to filter. 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 every conversation by default; pass `conversation=<id>` to stop just one and leave the others 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 across all sandboxes; each item carries 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 never touch the machine, so they work while the sandbox is archived:

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 first-class waiters and deterministic file/command helper functions:

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

Use wait_for_prompt/wait_for_prompt_done instead of inferring completion from sandbox.state plus event polling. Use stream_prompt or stream_events when you need incremental response/tool-call events as work runs.

Types

Python models use snake_case attributes. JSON serialization uses the API’s camelCase field names.

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` has the type multiplier applied; `running` means it is still growing.
`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.
`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()`.
`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. Log the status, reason, and response body when debugging, but redact API keys, Boat secrets, SSH keys, and desktop URLs.

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 for response streaming. They long-poll the sandbox v1 events cursor API; no separate SSE or WebSocket endpoint is required. response events carry text in event.data.content; streaming partials set event.data.is_streaming; tool-call events are response events with event.data.tools.

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 dashboard-style feed not tied to one prompt, use stream_events(sandbox, sandbox_id, type="prompt,response").

​Configure

​Create, prompt, and clean up

​Machine size

​Per-sandbox environment variables

​No-env sandboxes

​Methods

​Browse a stopped sandbox’s filesystem

​Waiters and helpers

​Types

​Errors

​Streaming responses and tool calls