> ## 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 ascii-box-sdk Python package. Install the Python package: ```bash theme={null} python -m pip install ascii-box-sdk ``` Import `BoxApi`, configure auth, and call snake\_case methods like `box.create`, `box.prompt`, and `box.events`. ## Configure ```python theme={null} import os from ascii_box_sdk import ApiClient, Configuration from ascii_box_sdk.api.box_api import BoxApi config = Configuration( host=os.getenv("BOX_BASE_URL", "https://ascii.dev/api/box/v1"), access_token=os.environ["BOX_API_KEY"], ) with ApiClient(config) as client: box = BoxApi(client) ``` Request models live under `ascii_box_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, `box.prompt(...)` raises `ApiException` with code `provider_not_configured`. A Box runs [many conversations in parallel](/box/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 ascii_box_sdk import ApiClient, Configuration from ascii_box_sdk.api.box_api import BoxApi from ascii_box_sdk.models.create_box_request import CreateBoxRequest from ascii_box_sdk.models.prompt_request import PromptRequest from ascii_box_sdk.models.update_box_request import UpdateBoxRequest from ascii_box_sdk import wait_until_ready, wait_for_prompt config = Configuration( host=os.getenv("BOX_BASE_URL", "https://ascii.dev/api/box/v1"), access_token=os.environ["BOX_API_KEY"], ) box_id = None with ApiClient(config) as client: box = BoxApi(client) try: created = box.create(CreateBoxRequest(ttl_seconds=1800)) box_id = created.box.id box.update(box_id, UpdateBoxRequest(name="sdk-demo")) wait_until_ready(box, box_id) queued = box.prompt( box_id, PromptRequest( provider="codex", prompt="Inspect the repository and summarize the test command.", ), ) run = wait_for_prompt(box, box_id, queued.prompt_id) print(run.status) events = box.events(box_id, limit=50, type="prompt,response") print(events.events) finally: if box_id: box.stop(box_id) ``` ## Machine size Pass `type` to create a bigger Box. `large` consumes machine time at 2x, `small` at half rate. A fork inherits the source Box's type, and passing `type` to `resume` or `fork` moves a Box between sizes. ```python theme={null} created = box.create(CreateBoxRequest(type="large", ttl_seconds=3600)) info = box.get(created.box.id) print(info.box.type, info.box.vcpu, info.box.memory_gb) ``` See [Machine Capabilities](/box/machines) and [Billing & Limits](/box/billing). ## Per-box environment variables Pass `env` to inject variables into a single Box, on top of your account-level secrets (per-box values win on name conflicts). At most 100 variables, 64KB total. ```python theme={null} created = box.create(CreateBoxRequest( ttl_seconds=3600, env={"DATABASE_URL": "postgres://user:pass@host:5432/app", "FEATURE_FLAG": "1"}, )) ``` Forked Boxes inherit the source Box's `env` unless the fork supplies its own. ## No-env boxes When you hand a Box 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 Box is always no-env and cannot be downgraded. ```python theme={null} created = box.create(CreateBoxRequest(ttl_seconds=1800, no_env=True)) box.resume(box_id, ResumeRequest(no_env=True)) forked = box.fork(box_id, ForkRequest(no_env=True)) ``` ## Methods All methods are called on `BoxApi`. Request bodies use model classes from `ascii_box_sdk.models`. | Method | Arguments | Returns | Use | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `me()` | none | `MeResponse` | Get the authenticated Box account user. | | `limits()` | none | `LimitsResponse` | Check whether the account can create or operate Boxes 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 Boxes. 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 Boxes. | | `update_secrets(SecretsUpdateRequest)` | `env_contents`, `secret_files` | `SecretsResponse` | Replace the complete secret setup. Send every env var and file that should remain. | | `boxes(limit=None, cursor=None, sort=None, state=None)` | optional pagination and state filter | `BoxListResponse` | List Boxes for the account. | | `create(CreateBoxRequest)` | optional `type`, `ttl_seconds`, `env`, `environment`, `no_env`, `setup_script`, `var_from`, `org` | `CreateBoxResponse` | Create a Box. Use `ttl_seconds=None` to disable auto-stop. Set `no_env=True` to withhold all account secrets (for Boxes you give to your users). `var_from` starts the Box from a named snapshot; `org` bills it to an organization wallet. | | `get(box_id)` | Box id | `BoxInfoResponse` | Fetch the latest Box state and connection fields. | | `usage(box_id, since=None, until=None)` | Box id, optional window as ISO 8601 or Unix seconds | `BoxUsageResponse` | Billable machine time one Box consumed, and its cost at list price, for per-box billing of your own users. Omit the window for the Box's whole life. See [Per-box usage](/box/billing#per-box-usage). | | `update(box_id, UpdateBoxRequest)` | Box id plus `name`, `ttl_seconds`, and/or `subdomain` | `BoxInfoResponse` | Rename a Box, change its auto-stop TTL, or rename its subdomain (re-points every live URL with no downtime). | | `stop(box_id, StopRequest=None)` | Box id, optional `force` | `BoxActionResponse` | Stop/archive a Box. A stop snapshots the disk first; if that is failing the stop is refused and the Box 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(box_id, ResumeRequest)` | Box id, optional `type`, `env`, `environment`, `ttl_seconds`, `no_env` | `BoxActionResponse` | Resume an archived Box. 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 Box's current auto-stop. Poll `get()` until it is ready. | | `fork(box_id, ForkRequest)` | Box id, optional `env`, `environment`, `type`, `ttl_seconds`, `no_env` | `BoxActionResponse` | Create a new Box from the source Box 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 Box is never modified. | | `delete_box(box_id)` | Box id | `BoxActionResponse` | **Permanently delete a Box and its snapshots.** Force-stops it, then deletes every snapshot chain only this Box 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](/box/snapshots#deleting-a-boxs-snapshots). | | `prompt(box_id, PromptRequest)` | Box id plus `provider`, `prompt`, optional `model`, optional `reasoning_effort`, optional `new`, optional `conversation_id` | `PromptResponse` | Queue work inside a Box. Returns `prompt_id`, `prompt_run.status`, and the `conversation_id` it ran in. Set `new=True` for a new [conversation](/box/integrated-agents) or `conversation_id` to continue one. | | `prompt_run_status(box_id, prompt_id)` | Box id and prompt id | `PromptRunResponse` | Read first-class prompt run status, including its `conversation_id`. | | `events(box_id, limit=None, cursor=None, sort=None, type=None, conversation=None)` | Box id plus optional pagination/filtering | `EventsResponse` | Read typed event history for a Box. Streams all [conversations](/box/integrated-agents) by default; pass `conversation=` to filter. Each event carries `conversation_id`. | | `read_file(box_id, path, encoding="utf8")` | Box id and relative path | `FileReadResponse` | Deterministically read a text/base64 file from the Box work directory. | | `write_file(box_id, FileWriteRequest)` | Box id plus relative path/content | `FileWriteResponse` | Deterministically write a text/base64 file. | | `command(box_id, CommandRequest)` | Box id plus command/cwd/timeout | `CommandResponse` | Execute a bounded command in the Box work directory. | | `artifact(box_id, path)` | Box id and relative path | bytes response | Download an artifact as bytes. | | `interrupt(box_id, conversation=None)` | Box id, optional conversation id | `BoxActionResponse` | Interrupt current work in a running Box. Stops every [conversation](/box/integrated-agents) by default; pass `conversation=` to stop just one and leave the others running. | | `desktop(box_id, vnc=None, theme=None, request_body=None)` | Box 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(box_id, SshKeyRequest)` | Box id plus public SSH key | `SshKeyResponse` | Add a public SSH key for Box SSH access. | | `list_snapshots(limit=None, cursor=None, sort=None)` | optional pagination | `SnapshotListResponse` | List completed snapshots across all Boxes; each item carries its `box_id`. | | `list_box_snapshots(box_id, limit=None, cursor=None, sort=None)` | Box id plus optional pagination | `SnapshotListResponse` | List completed snapshots for one Box. | | `get_latest_box_snapshot(box_id)` | Box id | `SnapshotLatestResponse` | Most recent completed snapshot for a Box, or `None`. | | `get_snapshot_tree(snapshot_id)` | Snapshot id | `SnapshotTreeResponse` | Flat file/folder listing with sizes for a snapshot. Works with the Box 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 Box 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 Box's filesystem Snapshot reads never touch the machine, so they work while the Box is archived: ```python theme={null} latest = box.get_latest_box_snapshot(box_id) tree = box.get_snapshot_tree(latest.snapshot.id) data = box.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 ascii_box_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(box, box_id) queued = box.prompt(box_id, PromptRequest(provider="codex", prompt="Run tests")) wait_for_prompt(box, box_id, queued.prompt_id) public_vnc = wait_for_desktop(box, box_id, public_access=True) write_text(box, box_id, "notes/result.txt", "done\n") result = exec_command(box, box_id, "cat notes/result.txt") stop_and_remove(box, box_id) # stop, keep the snapshots stop_and_remove(box, box_id, delete=True) # delete the Box and its snapshots ``` Use `wait_for_prompt`/`wait_for_prompt_done` instead of inferring completion from `box.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. | | `Box` | `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. | | `BoxActionResponse` | `ok`, `type`, `id`, `status`, `box` | Returned by lifecycle actions such as stop, resume, fork, and interrupt. | | `BoxInfoResponse` | `ok`, `type`, `box` | Returned by `get()` and `update()`. | | `BoxUsageResponse` | `ok`, `type`, `box_id`, `box_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. | | `BoxListResponse` | `ok`, `type`, `boxes`, `page_info` | Returned by `boxes()`. Use `page_info.next_cursor` when `page_info.has_more` is true. | | `BoxEvent` | `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. | | `CreateBoxRequest` | `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 Box to an organization wallet. | | `CreateBoxResponse` | `ok`, `type`, `status`, `ttl_seconds`, `box` | 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 Box 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 Box 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_boxes`, `active_states`, `max_active_boxes`, `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 Boxes. `starts.*.remaining` is remaining machine starts in each rolling window. | | `LimitsFieldsCurrentLimits` | `active_boxes`, `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](/box/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`, `box_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 `box 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 Boxes. | | `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. | | `UpdateBoxRequest` | `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, Box secrets, SSH keys, and desktop URLs. ```python theme={null} from ascii_box_sdk.exceptions import ApiException try: box.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 Box 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 ascii_box_sdk import stream_prompt from ascii_box_sdk.models.prompt_request import PromptRequest for event in stream_prompt( box, box_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(box, box_id, type="prompt,response")`.