Use the Python SDK

The boxrouter package gives Python a synchronous and an asynchronous client for the BoxRouter API. It needs Python 3.11 or later. python -m pip show boxrouter prints the version you have.

Install

python -m pip install boxrouter

Your first sandbox is in the quickstart.

Configure the Client

For each setting, the client uses the argument first, then the environment variable, then the default.

Argument	Environment Variable	Default
`api_key`	`BOXROUTER_API_KEY`	None. The client raises `ValueError` without one.
`base_url`	`BOXROUTER_BASE_URL`	`https://api.boxrouter.ai/api/v1`
`timeout`	None	360 s for reads and writes; 10 s for connect and pool waits
`transport`	None	HTTPX’s default
`max_retries`	None	2. The client resends a call whose error says `retry: safe`; `0` turns it off.

timeout takes an httpx.Timeout. Its limits apply to individual network waits, not the whole request; see HTTPX timeouts. Creating a sandbox that sets up an image can wait minutes, so leave the default read timeout or raise it. Command options set a command’s own limit. The client resends an API call only when the error says retry: safe, up to max_retries times, with the same idempotency key. Recover from Errors has the rules.

Choose Sync or Async

BoxRouter blocks. AsyncBoxRouter has the same methods, with three calling patterns:

Await coroutine methods such as create, exec and destroy.
Enter the async context managers returned by terminal and launch with async with.
Use async for for an async iterator such as volumes.list_files.

import asyncio
from boxrouter import AsyncBoxRouter

async def main() -> None:
    async with AsyncBoxRouter() as client:
        async with await client.sandboxes.create() as box:
            print((await box.exec("echo hello")).stdout, end="")

asyncio.run(main())

Leaving async with box requests the sandbox’s destruction, even when your code raised. Leaving async with client closes HTTP connections and leaves every sandbox as it was.

Handle Errors

Failure	Raised As	What It Carries
BoxRouter refused or could not finish the call	`APIError`	`status`, `code`, `outcome`, `retry`, `retry_after_seconds`, `fix`, `details`, `operation_id`, `sandbox_id`, `request_id`, `idempotency_key`, `response`
A volume file transfer fails	An `httpx.HTTPError`	Error details.
No API key	`ValueError`	The variable to set

Branch on error.retry, not on error.status: the status never decides a retry. A command that exits nonzero or reaches its timeout is a result: read exit_code and timed_out, because nothing is raised. Pass check=True to raise CommandFailed for either. Save this as errors.py. It runs a command in a sandbox that does not exist and prints the error’s code and outcome:

from boxrouter import APIError, BoxRouter

with BoxRouter() as client:
    try:
        client.sandboxes.exec("sb_missing", "echo hello")
    except APIError as error:
        print(error.code, error.outcome)
        print(error.fix)

python errors.py

A retry of check_outcome means BoxRouter cannot tell whether the call ran. Read the operation before resending (Recover from Errors has the steps). Quote request_id to support. When the workload and the sandbox’s cleanup both fail, the SDK raises a BaseExceptionGroup holding both; catch it with except*. If only the cleanup fails, you get its error alone. Either way it carries the sandbox ID as a note. A failed cleanup does not prove the sandbox stopped: keep its ID and look it up under Sandboxes before you retry.

Where Each Task Lives

Files: read and write sandbox files.
Volumes: upload and download files outside a sandbox.
Commands and background processes.
Pause and resume.
Find an SDK or CLI Call: each call in Python, TypeScript, and the CLI.

Next Steps

Find an SDK or CLI Call

The Python call for each sandbox task.

Recover from Errors

When resending a failed call is safe.

Use the TypeScript SDK

The same tasks in TypeScript.

Get Started

Sandboxes

Routing and Providers

Errors and Limits

Cost and Billing

Security and Privacy

Clients