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

# TypeScript: @anona-labs/compute-sdk

> Sandbox, live view tokens and SSH certificates for Node.js.

```text
npm install @anona-labs/compute-sdk e2b
```

ESM only; Node.js 22.19 or newer.

## `configure`

```ts Signature
configure(opts?: { apiKey?: string; domain?: string; apiUrl?: string; debug?: boolean;
                   waitForCapacityMs?: number; onCapacityWait?: OnCapacityWait }): void
```

Sets the `E2B_*` variables of this process so the stock `e2b` package, and the extras, talk to Anona. `waitForCapacityMs` and `onCapacityWait` set the default [capacity wait](#waiting-for-capacity) of this package's `Sandbox` in this process.

```typescript configure.ts
import { configure } from "@anona-labs/compute-sdk";
import { Sandbox } from "e2b"; // the stock SDK picks up the configuration

configure({ apiKey: process.env.ANONA_API_KEY });
const sbx = await Sandbox.create();
console.log((await sbx.commands.run("echo configured")).stdout);
await sbx.kill();
```

## `Sandbox`

A subclass of e2b's `Sandbox`. Every e2b method works unchanged and defaults to the Anona domain. Added:

| Member | Type |
| - | - |
| `sandbox.live` | `Live` |
| `sandbox.idlePause` | `IdlePause`: `get()`, `set(minutes)`, `off()` ([Pause when idle](/docs/concepts/lifecycle.md#pause-when-idle)) |
| `sandbox.ssh` | `Ssh` |
| `Sandbox.connectionDefaults(opts?)` | the resolved connection options (diagnostics) |

`Sandbox.create`, `Sandbox.connect` and `sandbox.connect()` also take `waitForCapacityMs` and `onCapacityWait`.

## Waiting for capacity

From `@anona-labs/compute-sdk` 0.3.0.

When every host is full, the API answers a create with `503` `sandbox_capacity_unavailable`, `Should-Retry: true` and `Retry-After` while it starts another host, which takes a few minutes. `Sandbox.create` and `Sandbox.connect` (which resumes a paused sandbox) then wait and try again instead of throwing: after each `Retry-After`, held between 1 and 30 seconds with a little jitter, until the wait runs out. Then the last error is thrown unchanged.

| Option | Default | |
| - | - | - |
| `waitForCapacityMs` | `600_000` | Milliseconds to keep trying. `0` turns the wait off. The default comes from `configure({ waitForCapacityMs })`, else `ANONA_COMPUTE_CAPACITY_WAIT` (seconds, or a duration such as `10m`; the CLI reads it too), else 10 minutes |
| `onCapacityWait` | none | Called before each wait with `{ attempt, delayMs, elapsedMs, remainingMs, status, error }` |

Each wait is also logged through the `logger` option, at `info`. Your `signal` cancels a wait in progress, and each try keeps your `requestTimeoutMs`; e2b's own `retries` still apply inside each try.

Only a `503` marked `Should-Retry: true` is retried: no capacity yet (`sandbox_capacity_unavailable`), the platform starting (`sandbox_engine_starting`) or settling (`sandbox_engine_unavailable`), or a size being prepared (`sandbox_size_preparing`). Everything else is thrown at once: a plan limit (`403` or `429` `plan_limit_exceeded`), any `4xx`, and a `503` with `Should-Retry: false` or without the header, which comes from something in front of the API and may mean the sandbox already started.

```typescript capacity_wait.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", {
  waitForCapacityMs: 5 * 60_000,
  onCapacityWait: ({ delayMs }) => console.log(`no capacity yet; retrying in ${Math.round(delayMs / 1000)}s`),
});
console.log(sbx.sandboxId);
await sbx.kill();
```

The wait reads the response headers from Node's diagnostics channels, so it works on Node (and runtimes that provide `node:diagnostics_channel`); elsewhere it is off. The stock `e2b` package's `Sandbox` does not wait.

## `sandbox.live`

| Method | Returns | |
| - | - | - |
| `token({ scope?, channels?, ttl? })` | `Promise<ViewerToken>` | `scope`: `"view"` (default) or `"control"`. `channels`: `"dom"`, `"pty"`, `"desktop"`, `"thumb"` (default `["dom"]`). `ttl`: 30 to 600 s (default 600) |
| `url({ mode?, scope?, ttl? })` | `Promise<string>` | Embed URL for one channel |
| `desktopUrl({ control?, ttl? })` | `Promise<string>` | Embed URL for the desktop; control scope unless `control: false` |
| `revokeAll()` | `Promise<void>` | Closes every viewer and invalidates issued tokens |

`ViewerToken` has `token`, `expiresAt` (`Date`), `embedUrl` and `claims()`. `toString()` and `toJSON()` never include the token.

```typescript live_tokens.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.connect(process.env.SANDBOX_ID!);
const tok = await sbx.live.token({ scope: "control", channels: ["pty"], ttl: 120 });
console.log(String(tok), JSON.stringify(tok));
console.log(tok.claims().scp, tok.claims().sbx === sbx.sandboxId);
```

Errors map to e2b's classes: 400 `InvalidArgumentError`, 401/403 `AuthenticationError`, 404 `NotFoundError`, 429 `RateLimitError`, others `SandboxError`.

## `sandbox.ssh`

| Method | Returns | |
| - | - | - |
| `certificate(publicKey)` | `Promise<SshCertificate>` | The OpenSSH public key **text** (not a path) |
| `config({ identityFile?, certificateFile?, alias?, user?, proxyCommand? })` | `string` | An `ssh_config` block. No request |

`SshCertificate` is `{ cert, user, host, proxyCommand, expiresAt? }`. See [SSH](/docs/guides/ssh.md).

## `sandbox.idlePause`

Pauses the sandbox once nothing has used it for a while. Not the same as
`lifecycle: { onTimeout: "pause" }`, which acts when the **deadline** runs out;
idle pause has no deadline. See [Lifecycle](/docs/concepts/lifecycle.md) for what counts
as use.

| Method | Returns | |
| - | - | - |
| `get()` | `Promise<number>` | Minutes of idleness before this sandbox pauses; `0` when off |
| `set(minutes)` | `Promise<number>` | 1 to 10080 (one week); `0` turns it off. Returns what the gateway recorded |
| `off()` | `Promise<number>` | Same as `set(0)` |

```typescript idle_pause_sdk.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { timeoutMs: -1 });  // no deadline
await sbx.idlePause.set(15);                                  // pause after 15 idle minutes
console.log(await sbx.idlePause.get());                       // 15
```

Resume with `Sandbox.connect(sandboxId)`.

## Desktop

There is no desktop subclass in TypeScript: create with `@e2b/desktop`, then `Sandbox.connect(desk.sandboxId)` from `@anona-labs/compute-sdk` for `live.desktopUrl()`. See [Desktop](/docs/guides/desktop.md).

## Exports

`Sandbox`, `configure`, `applyEnv`, `anonaDefaults`, `Live`, `ViewerToken`, `Ssh`, `IdlePause`, `MAX_IDLE_PAUSE_MINUTES`, `CHANNELS`, `SCOPES`, `MIN_TTL`, `MAX_TTL`, `DEFAULT_DOMAIN`, `DEFAULT_API_URL`, `DOMAIN_ENV`, `ENV_MAP`, `DEFAULT_WAIT_FOR_CAPACITY_MS`, `CAPACITY_WAIT_ENV`, and the types `ConfigureOpts`, `AnonaSandboxOpts`, `AnonaSandboxConnectOpts`, `CapacityWaitOpts`, `CapacityWaitInfo`, `OnCapacityWait`, `ViewerScope`, `ViewerChannel`, `ViewerTokenOpts`, `ViewerTokenClaims`, `SshCertificate`, `SshConfigOpts`.


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