Installation

The Python SDK is published on PyPI as bonya, and the importable package is also bonya, typed with py.typed. It is synchronous. It talks to the Bonya REST API over HTTPS (httpx), and to the sandbox edge over a WebSocket (websockets) for streaming exec and terminal sessions.

Requirements

Python 3.10+
httpx>=0.27,<1 and websockets>=13 (installed automatically)
A Bonya API key (byk_...)

Install

python -m pip install bonya

Configure

Every setting has an environment-variable fallback, so the common case needs no arguments at all:

export BONYA_API_KEY=byk_...

from bonya import Bonya

client = Bonya(
    api_key="byk_...",
    organization_id="org_123",
)

api_key can also be passed positionally: Bonya("byk_...").

Argument	Environment variable	Default
`api_key`	`BONYA_API_KEY`	required
`endpoint`	`BONYA_ENDPOINT`	`https://api.bonya.ai`
`edge_endpoint`	`BONYA_EDGE_ENDPOINT`	the API endpoint
`organization_id`	`BONYA_ORGANIZATION_ID`	your personal organization
`ca_bundle`	`BONYA_CA_BUNDLE`	system trust store
`timeout`	—	`30` seconds
`max_retries`	—	`2`
`filesystem_read_limit`	—	64 MiB

ca_bundle points to a PEM bundle for private development CAs; if it can’t be read, the SDK raises InvalidRequestError. timeout is the default per-operation deadline in seconds; exec calls can override it with timeout=. max_retries controls retries of transient failures. Mutations carry an Idempotency-Key that the SDK reuses across its own retries. filesystem_read_limit caps bytes buffered by sandbox.read_file().

An empty organization_id (or BONYA_ORGANIZATION_ID="") raises InvalidRequestError rather than silently falling back to your personal organization. See Organizations.

Close the client when done, or use with, which does it for you. Calling SDK methods after client.close() raises InvalidRequestError.

Quickstart

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 exits. See Usage for the full surface.

TypeScript

Python

Go

Installation

Requirements

Install

Configure

Quickstart

​Requirements

​Install

​Configure

​Quickstart

Requirements

Install

Configure

Quickstart