Python SDK

The Python SDK is instabox-sdk on PyPI. It runs on Python 3.9 to 3.13, has one dependency (httpx) and imports as instabox.

Install and authenticate

pip install instabox-sdk
export INSTABOX_API_KEY=ibk_...

Create the key on API keys in the dashboard: Full access, or a restricted key with machines:write and machines:delete, which is enough for the quickstart. The snapshot calls also need images:write (create), images:read (list and get) and images:delete (delete). See API keys. Client() reads INSTABOX_API_KEY and INSTABOX_API_URL (default https://api.instabox.sh), or takes Client(api_key=..., base_url=...).

Quickstart

from instabox import Client

client = Client()  # reads INSTABOX_API_KEY (and INSTABOX_API_URL, default https://api.instabox.sh)

box = client.machines.create(name="my-box")  # template agent-browser; waits until ready
try:
    r = client.machines.exec(box.id, "uname -a")
    print(r.stdout, end="")

    r = client.machines.exec(box.id, ["sh", "-c", "echo oops >&2; exit 3"])
    print(r.exit_code, r.stderr, end="")  # 3 oops
finally:
    client.machines.delete(box.id)

create waits until the machine is ready. exec takes a shell string, run with bash -lc, or an argv list, run with no shell. A non-zero exit code is a result, not an error: read it from r.exit_code.

Pick up a machine later

A machine pauses after 30 idle minutes by default. ensure_running starts or resumes it, whatever its state, and waits until it is ready. This block runs on its own: it makes my-box first, as an earlier run would have, and deletes it at the end:

from instabox import Client

client = Client()
client.machines.create(name="my-box")  # stands in for a machine made earlier
try:
    box = client.machines.ensure_running("my-box")  # starts or resumes it, waits until ready
    print(client.machines.exec(box.id, "ls /data/home").stdout, end="")
    client.machines.update(box.id, metadata={"stage": "review"})  # labels: any plan
    # Paid plans only; on the free plan another idle time is 403 spec_not_allowed:
    # client.machines.update(box.id, auto_suspend_after_seconds=600)
finally:
    client.machines.delete("my-box", confirm="my-box")  # refuses to delete anything but my-box

Calls

Every call that takes machine accepts a machine ID (m_...) or its name.

Call	Does
`client.machines.create(name=None, *, template=None, snapshot_id=None, metadata=None, ...)`	Create a machine; waits until it is ready
`client.machines.list()`, `get(machine)`	List your machines, get one
`client.machines.exec(machine, command, *, cwd=None, env=None, stdin=None, timeout=60)`	Run a command: `stdout`, `stderr`, `exit_code`, `timed_out`; from 0.4.0 `stdin` may be bytes
`client.machines.pause`, `resume`, `start`, `stop`, `ensure_running`	Lifecycle; each waits for its operation
`client.machines.update(machine, *, name=None, metadata=None, auto_suspend_after_seconds=None, ...)`	Rename, set labels or the idle pause
`client.machines.delete(machine, *, confirm=None)`	Delete
`client.files.write`, `read`, `read_bytes`, `list`, `exists`, `remove`	Files on the machine, at absolute paths (or, from 0.4.0, relative to HOME)
`client.files.read_stream`, `upload(machine, local_dir, remote_dir)`, `download(machine, remote_dir, local_dir)`	From 0.4.0: stream a file of any size, copy a whole directory each way
`client.snapshots.create(machine, name)`, `list()`, `get(id)`, `delete(id)`	Snapshots; `status` goes `pending` to `ready`
`client.templates.list()`	Templates

Every argument and model field is in the SDK README.

Errors

Every error is an instabox.InstaboxError. API errors are instabox.APIError subclasses with the API’s code, message, request_id, retryable and status:

Status	Class	Example `code`
400	`BadRequestError`	`bad_request`, `spec_not_allowed` (a size or disk the plan does not offer)
401	`AuthenticationError`	`missing_key`, `malformed_key`, `invalid_key`, `expired_key`, `revoked_key`; `missing_api_key` when no key is set
403	`PermissionDeniedError`	`missing_scope`, `template_not_allowed`, `spec_not_allowed` (another idle time on the free plan)
404	`NotFoundError`	`not_found`
409	`ConflictError`	`machine_not_running`, `operation_conflict`
429	`RateLimitError`	`quota_exceeded`, `rate_limited`
5xx	`ServerError`	`no_capacity`, `host_unavailable`

spec_not_allowed is a plan or size limit and takes the status of what was refused: 400 for a size or disk size the plan does not offer, 403 for another idle time (auto_suspend_after_seconds) on the free plan or starting a paid machine larger than its plan now allows, 409 for restoring a snapshot that does not fit the machine’s disk. A failed operation raises OperationFailedError, a wait that runs out WaitTimeoutError. Every code: Errors.

Get started

TypeScript

Python

Install and authenticate

Quickstart

Pick up a machine later

Calls

Errors

​Install and authenticate

​Quickstart

​Pick up a machine later

​Calls

​Errors

Install and authenticate

Quickstart

Pick up a machine later

Calls

Errors