WBX Sandbox
Reference

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

AreaCalls
Sandboxeswbx.sandboxes.create / get / list / kill, sandbox.sleep / pause / resume / setTimeout / keep / getUrl / refresh / kill – see Create and manage and Sleep and wake.
Commandssandbox.commands.run (with live output callbacks), sandbox.commands.stream (async iterator), sandbox.runCode (python, node, bash).
Filessandbox.files.read / readText / readStream / write / list / stat / exists / mkdir / move / remove / watch.
Processessandbox.processes.start / list / stream / sendStdin / signal / resize / kill.
Jobswbx.jobs.create / get / list / wait, job.wait / summary / logs / digest / follow / receipt / signedReceipt / artifacts / download / cancel / retry.
Batcheswbx.batches.create / get / list, batch.wait / summary / report / reportCsv / listJobs / cancel.
Metricssandbox.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.
Desktopsandbox.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.
Accountwbx.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.