> ## Documentation Index > Fetch the complete documentation index at: https://docs.ascii.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 to be configured for the authenticated account. If Codex or Claude Code credentials are missing, `box.prompt(...)` raises `ApiException` with code `provider_not_configured`. ## 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,git_checkpoint") print(events.events) finally: if box_id: box.stop(box_id) ``` ## 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. 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 `ttl_seconds`, `no_env` | `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). | | `get(box_id)` | Box id | `BoxInfoResponse` | Fetch the latest Box state and connection fields. | | `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)` | Box id | `BoxActionResponse` | Stop/archive a Box. | | `resume(box_id, ResumeRequest)` | Box id, optional `no_env` | `BoxActionResponse` | Resume an archived Box. Pass `ResumeRequest(no_env=True)` to convert it to no-env while scrubbing inherited owner secrets. Poll `get()` until it is ready. | | `fork(box_id, ForkRequest)` | Box id, optional `env`, optional `no_env` | `BoxActionResponse` | Create a new Box from the source Box snapshot. Pass `ForkRequest(no_env=True)` to create a no-env fork. | | `prompt(box_id, PromptRequest)` | Box id plus `provider`, `prompt`, optional `model`, optional `reasoning_effort` | `PromptResponse` | Queue work inside a Box. Returns `prompt_run.status` and `prompt_id`. | | `prompt_run_status(box_id, prompt_id)` | Box id and prompt id | `PromptRunResponse` | Read first-class prompt run status. | | `events(box_id, limit=None, cursor=None, sort=None, type=None)` | Box id plus optional pagination/filtering | `EventsResponse` | Read typed event history for a Box. | | `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)` | Box id | `BoxActionResponse` | Interrupt current work in a running Box. | | `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) ``` 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` | Metadata only; not the raw secret. | | `ApiKeysResponse` | `ok`, `type`, `api_keys` | API key metadata response. Raw secrets are not returned. | | `Box` | `id`, `name`, `state`, `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()`. | | `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` | `ttl_seconds` | Seconds before auto-stop; `None` disables auto-stop. | | `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()`. | | `GitCheckpointEvent` | `id`, `type`, `timestamp`, `task_id`, `data` | Git checkpoint event. `data` includes `commit_sha`, `commit_message`, `commit_url`, `branch`, `files_changed`, `additions`, `deletions`, and `pushed`. | | `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`, `has_payment_history`, `package`, `subscription_quota_seconds`, `subscription_remaining_seconds`, `pack_balance_seconds`, `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` | Shared limit and billing-access fields. Use `can_start` and `start_blocked_reason` before creating Boxes. | | `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`, `data` | Prompt lifecycle event. `data` includes `prompt`, `status`, and optionally `is_reverted`. | | `PromptRequest` | `provider`, `model`, `reasoning_effort`, `prompt` | `provider` is `codex` or `claude-code`. Omit `model` to use the saved default. | | `PromptResponse` | `ok`, `type`, `id`, `prompt_id`, `prompt_run`, `status`, `provider`, `model`, `reasoning_effort` | Returned after work is queued. | | `PromptRun` | `id`, `prompt_id`, `box_id`, `status`, `done`, `created_at`, `model`, `reasoning_effort` | First-class prompt run state. `status` is `sending`, `queued`, `running`, `finished`, or `failed`. | | `PromptRunResponse` | `ok`, `type`, `id`, `prompt_run` | Returned by `prompt_run_status()`. | | `ResponseEvent` | `id`, `type`, `timestamp`, `task_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`, `pre_commit_hooks` | Repository selected for future Boxes. | | `SelectedRepositoryAllOfPreCommitHooks` | `id`, `script`, `blocking` | Pre-commit hook configured for a selected repository. | | `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,git_checkpoint")`.