# TypeScript SDK

The official SDK for TypeScript and JavaScript: sandboxes, commands, files, background jobs, batches, live metrics and desktop control – with typed errors, timeouts, cancellation and safe retries. No dependencies; it runs on Node.js 20+, Deno, Bun and edge runtimes.

## Install and configure

```
npm install wbxsandbox
```

Create an API key in the portal (*API keys*) and set it in the environment – the same variables as for the Python SDK – or pass `apiKey` and `baseURL` to `new WBX()`:

```
export WBXSANDBOX_API_KEY=YOUR_API_KEY
export WBXSANDBOX_URL=https://sandbox.wbx.cz        # optional
```

## Quickstart

```
import { WBX } from "wbxsandbox";

const wbx = new WBX({ apiKey: process.env.WBXSANDBOX_API_KEY! });

const sandbox = await wbx.sandboxes.create({ template: "base", name: "my-project" });
const r = await sandbox.commands.run("python3 --version");
console.log(r.stdout);

await sandbox.files.write("/home/user/data.txt", "hello");
console.log(await sandbox.files.readText("/home/user/data.txt"));

await sandbox.sleep();   // files kept, no compute billed – the next request wakes it up
```

## Jobs and batches

```
const job = await wbx.jobs.create({ command: "python3 analyze.py", saveArtifacts: true, maxCost: "0.10" });
await job.wait();                                  // server-side waiting, no polling
console.log((await job.summary()).status);
const bytes = await job.download("output/report.csv");  // SHA-256 checked

const batch = await wbx.batches.create({
  jobs: [
    { command: "python3 prepare.py", saveArtifacts: true },
    { command: "python3 train.py", dependsOn: [0], inputs: [{ fromIndex: 0, name: "output/data.csv" }] },
  ],
  maxConcurrency: 10,
  maxTotalCost: "2.00",
});
console.log((await batch.wait()).status);       // completed / partial / failed
```

## What it covers

| Area | Calls |
| --- | --- |
| **Sandboxes** | `wbx.sandboxes.create / get / list / kill`, `sandbox.sleep / pause / resume / setTimeout / keep / getUrl / refresh / kill` – see [Create and manage](https://sandbox.wbx.cz/docs/sandboxes.md) and [Sleep and wake](https://sandbox.wbx.cz/docs/sandboxes/sleep.md). |
| **Commands** | `sandbox.commands.run` (with live output callbacks), `sandbox.commands.stream` (async iterator), `sandbox.runCode` (python, node, bash). |
| **Files** | `sandbox.files.read / readText / readStream / write / list / stat / exists / mkdir / move / remove / watch`. |
| **Processes** | `sandbox.processes.start / list / stream / sendStdin / signal / resize / kill`. |
| **Jobs** | `wbx.jobs.create / get / list / wait`, `job.wait / summary / logs / digest / follow / receipt / signedReceipt / artifacts / download / cancel / retry`. |
| **Batches** | `wbx.batches.create / get / list`, `batch.wait / summary / report / reportCsv / listJobs / cancel`. |
| **Metrics** | `sandbox.metrics.get`; `history` and the live `stream` (optionally reconnecting after the server's 15-minute limit) need the metrics history feature on your account – see [Metrics and observability](https://sandbox.wbx.cz/docs/sandboxes/metrics.md). |
| **Desktop** | `sandbox.computer.status / screenshot / actions / move / click / doubleClick / drag / scroll / type / key / wait / control` for the `desktop` template (beta); needs the desktop feature on your account – see [Desktop & Computer Use](https://sandbox.wbx.cz/docs/sandboxes/desktop.md). Note `scroll(x, y, dx, dy)`: horizontal first, unlike the Python SDK. |
| **Account** | `wbx.templates.list`, `wbx.features`, `wbx.budget`, `wbx.compute`, `wbx.webhooks`, `verifyWebhook`, `wbx.request` for any other endpoint. |

Records returned by the API keep their REST field names (`exit_code`, `created_at`), so the [REST API reference](https://sandbox.wbx.cz/docs/api.md) applies unchanged; options you pass are camelCase.

## Errors, timeouts and retries

Every error extends `WBXError`; HTTP errors are `APIError` subclasses with `status`, `code` and `retryAfter` – for example `AuthenticationError`, `NotFoundError`, `RateLimitError`, `FeatureDisabledError` or `HumanInControlError` (each also has `body`). A failed desktop action throws `ComputerActionError` with `failedIndex` and `results`, unless you pass `throwOnFailure: false`. Default timeouts: 60 s per request, 150 s to create a sandbox, 5 minutes for file transfers and desktop actions, 10 minutes for result files; a command waits for its own `timeoutMs` plus 30 s. A command that exits with an error is a normal result; `result.check()` turns it into an exception.

Every call accepts `{ signal, timeoutMs }`. Only requests that cannot take effect twice are retried automatically (reads, deletes, job and batch submissions with an idempotency key the SDK adds, a sandbox create with a `name`), after connection errors, 502–504 and 429 with `Retry-After`. Commands and other actions are never repeated behind your back.

## More

The full reference is the package README, on [npmjs.com/package/wbxsandbox](https://www.npmjs.com/package/wbxsandbox) and at [github.com/WBX-Sandbox/wbxsandbox-js](https://github.com/WBX-Sandbox/wbxsandbox-js). It comes with examples: a sandbox, a job with waiting and logs, a batch with dependencies, a metrics stream, desktop control and a tool function an AI model can call. Versions follow semantic versioning; while the SDK is 0.x, breaking changes are possible in minor releases and are listed in its changelog.

Source: https://sandbox.wbx.cz/docs/sdk/typescript
