> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and configure the Python SDK

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

```bash theme={null}
python -m pip install bonya
```

## Configure

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

```bash Environment variable theme={null}
export BONYA_API_KEY=byk_...
```

```python Explicit theme={null}
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()`.

> [!NOTE]
>
> An empty `organization_id` (or `BONYA_ORGANIZATION_ID=""`) raises
> `InvalidRequestError` rather than silently falling back to your personal
> organization. See [Organizations](https://docs.bonya.ai/sdks/python/usage.md#organizations).

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

## Quickstart

```python theme={null}
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](https://docs.bonya.ai/sdks/python/usage.md) for the full surface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.