> ## 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 TypeScript SDK

The TypeScript SDK is published to npm as `@bonya-ai/bonya`. It ships ESM with
bundled type declarations. It talks to the Bonya REST API over HTTPS, and to
the sandbox edge over a WebSocket for streaming exec and terminal sessions.

> [!NOTE]
>
> **Node only.** The SDK relies on Node's networking stack and filesystem. It does
> not run in a browser or on edge runtimes.

## Requirements

* Node.js 18.17 or newer
* A Bonya API key (`byk_...`)

## Install

```bash theme={null}
npm install @bonya-ai/bonya
```

## Configure

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

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

```ts Explicit theme={null}
import { Bonya } from "@bonya-ai/bonya";

const client = new Bonya({
  apiKey: "byk_...",
  organizationId: "org_123",
});
```

| Option | Environment variable | Default |
| - | - | - |
| `apiKey` | `BONYA_API_KEY` | *required* |
| `endpoint` | `BONYA_ENDPOINT` | `https://api.bonya.ai` |
| `edgeEndpoint` | `BONYA_EDGE_ENDPOINT` | the API endpoint |
| `organizationId` | `BONYA_ORGANIZATION_ID` | your personal organization |
| `caBundle` | `BONYA_CA_BUNDLE` | system trust store |
| `timeout` | — | `30` (seconds) |
| `maxRetries` | — | `2` |
| `filesystemReadLimit` | — | 64 MiB |

`apiKey` is required: pass it directly or set `BONYA_API_KEY`. The key is sent as
`Authorization: Bearer byk_...`.

`caBundle` points to a PEM bundle for private development CAs. If the file can't
be read, the constructor throws `InvalidRequestError`.

`timeout` is the default per-operation deadline in seconds; buffered and
streaming exec calls can override it per call. `maxRetries` controls retries of
transient failures. Mutations carry an `Idempotency-Key`, which the SDK reuses
across its own retries, so a retried call joins the original instead of
repeating it. `filesystemReadLimit` caps bytes buffered by `sandbox.readFile()`.

> [!NOTE]
>
> An empty `organizationId` (or `BONYA_ORGANIZATION_ID=""`) is an error, not a
> silent fallback to your personal organization. This stops CI jobs quietly
> running against the wrong tenant when a variable expansion is empty. See
> [Organizations](https://docs.bonya.ai/sdks/typescript/usage.md#organizations).

Call `client.close()` when you're done so open connections don't keep Node's
event loop alive.

## Quickstart

```ts theme={null}
import { Bonya } from "@bonya-ai/bonya";

const client = new Bonya(); // reads BONYA_API_KEY
try {
  const sandbox = await client.createSandbox();
  try {
    const result = await sandbox.exec(["echo", "hello"], { check: true });
    console.log(result.stdout); // hello
  } finally {
    await sandbox.delete();
  }
} finally {
  client.close();
}
```

That is a real VM: it boots in about a second, runs anything Linux runs, and is
gone when `delete()` resolves.

See [Usage](https://docs.bonya.ai/sdks/typescript/usage.md) for the full surface.


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