Sandbox0 JavaScript/TypeScript SDK

The official JavaScript/TypeScript SDK for Sandbox0, providing typed models and ergonomic high-level APIs for managing secure code execution sandboxes.

Installation

npm install sandbox0
# or
yarn add sandbox0
# or
pnpm add sandbox0

Requirements

• Node.js 18.0.0 or later

Streaming APIs prefer a runtime-native globalThis.WebSocket when a Node-compatible host exposes one, and fall back to the ws package on older Node runtimes. This keeps the main SDK entry compatible with SandFunc-style runtimes that expose a standard outbound WebSocket client without requiring raw socket access in user code.

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------------------------|----------------------| | SANDBOX0_TOKEN | Yes | - | API authentication token | | SANDBOX0_BASE_URL | No | https://api.sandbox0.ai | API base URL |

Quick Start

import { Client } from "sandbox0";

const client = new Client({
  token: process.env.SANDBOX0_TOKEN!,
});

async function main() {
  // Claim a sandbox
  const sandbox = await client.sandboxes.claim("default");

  try {
    // Execute Python code (REPL - stateful)
    const result = await sandbox.run("python", "print('Hello, Sandbox0!')");
    process.stdout.write(result.outputRaw);
  } finally {
    // Cleanup
    await client.sandboxes.delete(sandbox.id);
  }
}

main().catch(console.error);

CMD Streaming

const stream = await sandbox.cmdStream("sh -c 'echo hello && echo warn >&2'", {
  command: ["sh", "-c", "echo hello && echo warn >&2"],
});

for await (const output of stream.outputs()) {
  process.stdout.write(output.data);
}

const done = await stream.wait();
console.log(`exit=${done.exitCode} state=${done.state}`);

Documentation

• Sandbox0 docs
• Volume mounts

Bootstrap Mounts At Claim Time

const volume = await client.volumes.create({});

const sandbox = await client.sandboxes.claim("default", {
  mounts: [{ sandboxvolumeId: volume.id, mountPoint: "/workspace/data" }],
});

for (const mount of sandbox.bootstrapMounts) {
  console.log(mount.sandboxvolumeId, mount.state);
}

Wait For Lifecycle Changes

Pause is accepted before its rootfs checkpoint is fully committed. Use the waiting helpers when the next operation depends on committed lifecycle state:

const paused = await client.sandboxes.pauseAndWait(sandbox.id, {
  timeoutMs: 120_000,
  signal: abortController.signal,
});

const resumed = await client.sandboxes.resumeAndWait(paused.id);
console.log(resumed.status, resumed.runtimeGeneration);

waitForLifecycle() is available for other committed-state conditions. Aborting a wait stops polling locally; it does not undo a pause or resume already accepted by Sandbox0.

Runtime Metrics

getMetrics() returns bounded, chart-ready sandbox metrics. Each series is split into segments at runtime restarts and collector resets, so chart segments should not be connected across those boundaries.

import { SandboxRuntimeMetricName } from "sandbox0";

const metrics = await sandbox.getMetrics({
  startTime: new Date(Date.now() - 60 * 60 * 1000),
  metrics: [
    SandboxRuntimeMetricName.SandboxCpuUtilization,
    SandboxRuntimeMetricName.SandboxMemoryUtilization,
  ],
  maxPoints: 240,
});

for (const series of metrics.series) {
  for (const segment of series.segments) {
    console.log(series.metric, segment.points);
  }
}

Use sandbox.getMetricsCatalog() to discover metric kinds, units, and dimensions supported by the API.

Links

• Documentation
• API Reference
• GitHub Repository

License

Apache-2.0