Python SDK

python -m pip install ascii-box-sdk

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)

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)

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

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))

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")

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)

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)

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="")