Installation

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.

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

npm install @bonya-ai/bonya

Configure

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

export BONYA_API_KEY=byk_...

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().

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.

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

Quickstart

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

TypeScript

Python

Go

Installation

Requirements

Install

Configure

Quickstart

​Requirements

​Install

​Configure

​Quickstart

Requirements

Install

Configure

Quickstart