> ## Documentation Index > Fetch the complete documentation index at: https://docs.boat.dev/llms.txt > Use this file to discover all available pages before exploring further. # Python SDK > Install, configure, and use the boat-sdk Python package. Install the Python package: ```bash theme={null} python -m pip install boat-sdk ``` Import `BoatApi`, configure auth, and 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) ``` 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`), and `kimi`; 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](/integrated-agents): 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 ```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 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. ```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 [Billing & Limits](/billing). ## 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. ```python theme={null} 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. ```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 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](/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 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](/snapshots#deleting-a-sandboxs-snapshots). | | `prompt(sandbox_id, PromptRequest)` | Sandbox id plus `provider`, `prompt`, optional `model`, optional `reasoning_effort`, 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. | | `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; pass `conversation=` 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](/integrated-agents) by default; pass `conversation=` 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: ```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 first-class waiters and deterministic file/command helper functions: ```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")) 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`, `new`, `conversation_id`, `prompt` | `provider` is `codex`, `claude-code` (alias `claude`), `pi`, `opencode`, `prime-agent` (alias `prime`), or `kimi`; omit it for the dashboard default. Omit `model`/`reasoning_effort` to use saved defaults (the live catalog is `GET /provider-models`). 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` | 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`, `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. ```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` 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`. ```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 dashboard-style feed not tied to one prompt, use `stream_events(sandbox, sandbox_id, type="prompt,response")`.