Find an SDK or CLI Call

Python and TypeScript share method names unless a row says otherwise. The CLI has top-level commands for the common calls; everything else is boxrouter api GROUP OPERATION. For a full program, see the quickstart.

Sandboxes

Task	Python	TypeScript	CLI
Create	`client.sandboxes.create(...)`	`client.sandboxes.create({...})`	`boxrouter create`
Check routing	`client.sandboxes.match(...)`	`client.sandboxes.match({...})`	`boxrouter match`
Read state	`client.sandboxes.get(id)`, then `box.state`	`client.sandboxes.get(id)`, then `box.state`	`boxrouter get ID`
Read again	`box.refresh()`	`await box.refresh()`	`boxrouter get ID`
List	`client.sandboxes.list(label=[...])`	`client.sandboxes.list({ label: [...] })`	`boxrouter api sandboxes list`
Destroy	`box.destroy()`	`box.destroy()`	`boxrouter destroy ID`
Pause	`box.pause()`	`box.pause()`	`boxrouter api sandboxes pause ID`
Resume	`box.resume()`	`box.resume()`	`boxrouter api sandboxes resume ID`
Extend	`box.extend(lifetime_seconds=1800)`	`box.extend({ lifetime_seconds: 1800 })`	`boxrouter api sandboxes extend ID`
Open a preview	`box.previews.open(3000)`	`box.previews.open(3000)`	`boxrouter preview ID 3000`

pause and resume work only on a sandbox created with the pause_resume requirement, extend only with resources.extendable_lifetime, and previews.open only for a port the previews requirement named. On any other sandbox, the call fails with not_named. get reads state and nothing else: a paused sandbox stays paused and its lifetime is not extended. Call resume to wake it.

Commands

Task	Python	TypeScript	CLI
Run Bash	`box.exec(command)`	`box.exec(command)`	`boxrouter exec ID COMMAND`
Start a background process	`box.processes.start(command)`	`box.processes.start(command)`	`boxrouter process start ID COMMAND`
Open a terminal	`sandbox.open_terminal()`	`sandbox.openTerminal()`	`boxrouter terminal ID`

Files

Task	Python	TypeScript	CLI
Read bytes	`box.files.read(path)`	`box.files.read(path)`	`boxrouter read ID --path PATH`
Write bytes	`box.files.write(path, data)`	`box.files.write(path, data)`	`boxrouter write ID --path PATH --body FILE`
Upload a file to a Volume	`client.volumes.upload(volume_id, local, path)`	`client.volumes.upload(volumeId, local, path)`	`boxrouter volumes put VOLUME_ID LOCAL PATH`
Download a file from a Volume	`client.volumes.download(volume_id, path, local)`	`client.volumes.download(volumeId, path, local)`	`boxrouter volumes get VOLUME_ID PATH LOCAL`
List a directory	`box.files.list(path)`	`box.files.list(path)`	`boxrouter api files list ID --path PATH`
Make a directory	`box.files.mkdir(path, parents=True)`	`box.files.mkdir(path, { parents: true })`	`boxrouter api files mkdir ID --body '{"path": "PATH", "parents": true}'`
Test a path	`box.files.exists(path)`	`box.files.exists(path)`	`boxrouter api files exists ID --path PATH`
Remove a path	`box.files.remove(path, recursive=True)`	`box.files.remove(path, { recursive: true })`	`boxrouter api files remove ID --body '{"path": "PATH", "recursive": true}'`

read returns and write accepts bytes in Python and Uint8Array in TypeScript. The CLI prints read results to stdout. For writes, it reads the content from the local file named by --body.

Names That Follow a Rule

Topic	Python	TypeScript	CLI
Requirements that need no settings	`requirements=["pause_resume"]`	`requirements: ['pause_resume']`	`--require pause_resume`
Operations not listed	`client.api.GROUP.OPERATION(...)`	`client.api.GROUP.OPERATION(...)`	`boxrouter api GROUP OPERATION`
SDK method and option casing	`snake_case`, as in `save_volume`	`camelCase`, as in `saveVolume`	Not applicable
Command options `env`, `cwd`, `timeout_seconds`	Keyword arguments	A second argument	`--env`, `--cwd`, `--timeout-seconds`
Idempotency key	`idempotency_key=`	`idempotencyKey` in the options argument	`--idempotency-key`
Resends of a `retry: safe` error	`max_retries=` on the client (default 2)	`maxRetries` in the client options (default 2)	Always 2

The API reference lists the operation groups. Request fields keep the API’s snake_case in both SDKs, for example timeout_seconds. Recover from Errors says when to set an idempotency key. In TypeScript, await promise-returning methods and use for await for async generators; get returns the sandbox handle. In Python’s AsyncBoxRouter, await open_terminal() and use async for with terminal.output(); launch also supports async with.

Next Steps

Use the Python SDK

Install and configure the Python SDK.

Use the TypeScript SDK

Install and configure the TypeScript SDK.

Use the CLI

Install and use the CLI.

Get Started

Sandboxes

Routing and Providers

Errors and Limits

Cost and Billing

Security and Privacy

Clients

Find an SDK or CLI Call

Sandboxes

Commands

Files

Names That Follow a Rule

Next Steps

Use the Python SDK

Use the TypeScript SDK

Use the CLI