Bonya Python SDK

Run code in a fast, isolated sandbox — from Python.

python -m pip install bonya

from bonya import Bonya

with Bonya() as client:                       # reads BONYA_API_KEY
    with client.create_sandbox() as sandbox:  # deleted on the way out
        result = sandbox.exec(["echo", "hello"], check=True)
        print(result.stdout)                  # hello

That is a real VM: it boots in about a second, runs anything Linux runs, and is gone when the with block ends.

The SDK is synchronous. It talks to the Bonya REST API over HTTPS (httpx), and to the edge over a WebSocket (websockets) for streaming exec and terminal sessions. Python 3.10 or newer; fully typed (py.typed).

Configuration

Every setting has an environment-variable fallback:

An empty organization_id is an error rather than a silent fallback to your personal organization.

What you can do

Everything is a flat method on Bonya or Sandbox.

Streaming exec

from bonya import Exit, Stderr, Stdout

with sandbox.exec_stream(["bash", "-lc", "echo out; echo err >&2"]) as session:
    for event in session:
        if isinstance(event, Stdout):
            print("out:", event.data.decode(), end="")
        elif isinstance(event, Stderr):
            print("err:", event.data.decode(), end="")
        elif isinstance(event, Exit):
            print("exit:", event.exit_code)

Persistent sessions

sandbox.create_session("server", ["bash"])
with sandbox.attach_session("server") as stream:
    stream.write("npm run dev\n")
    for event in stream:
        ...  # Stdout, Exit, SessionEnded, SessionOutputDropped
# leaving the block detaches; the process keeps running

Jobs

from bonya import JobSandboxSpec, JobSpec

run = client.run_job(JobSpec(new_sandbox=JobSandboxSpec(), cmd=["./run-tests.sh"]))
print(run.status, run.result.exit_code)

Snapshots and forks

snapshot = sandbox.snapshot(name="baseline")
restored = client.create_sandbox(snapshot=snapshot.id)
forks = sandbox.fork(2).sandboxes

Errors

Every error extends BonyaError (with sandbox_id, idempotency_key, code). Catch the class you care about: AuthenticationError, SandboxNotFoundError, SandboxCreationTimeoutError (carries the idempotency_key so create can be retried), ExecFailedError, TimeoutError, NoCapacityError, RateLimitedError, OutcomeUnknownError, RemoteFileNotFoundError, and so on. API keys and capability tokens are redacted from error messages.

Create, exec, snapshot and other mutations accept an idempotency_key; the SDK generates one and reuses it across its own retries, so a retried call joins the original attempt instead of repeating it.

Examples

Runnable programs live in examples/: quickstart.py, exec_streaming.py, files.py, sessions.py, previews.py, snapshots.py.

Development

python -m pip install -e '.[dev]'
make check      # mypy + pytest

MIT licensed.