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 and Sleep and wake. |
| 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. |
| 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. 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 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 and at 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.