SDKs

npm install @brimble/sandbox

import { Sandbox } from "@brimble/sandbox";

// reads BRIMBLE_SANDBOX_KEY
const client = new Sandbox();

// or pass explicitly
const client = new Sandbox({ apiKey: process.env.MY_KEY });

import { Sandbox } from "@brimble/sandbox";

const client = new Sandbox();

// Node 22, 20 GB persistent disk, waits for ready
const handle = await client.sandboxes.quickstartNode({ region: "auto" });

const result = await handle.exec({ cmd: "node -e 'console.log(2 + 2)'" });
console.log(result.stdout);

await handle.destroy();

const handle = await client.sandboxes.createReady({
  region: "auto",
  template: "python-3.12",
  persistent: true,
  persistentDiskGB: 20,
});
// handle is ready to use immediately

const handle = await client.sandboxes.create({
  region: "auto",
  template: "node-22",
});

await handle.waitUntilReady({
  timeoutMs: 120_000,
  pollIntervalMs: 1_000,
  signal: abortController.signal,  // optional
});

const handle = await client.sandboxes.withVolume({
  sandbox: {
    region: "auto",
    template: "node-22",
  },
  volume: {
    name: "alice-workspace",
    sizeGB: 20,
    region: "auto",
  },
});

const handle = await client.sandboxes.get(sandboxId);

// or a thinner scope (no cached state, no auto-wait)
const scope = client.sandboxes.use(sandboxId);

const handle = await client.sandboxes.create({ region: "auto", template: "node-22" });

// auto-waits until ready, then runs the command
const result = await handle.exec(
  { cmd: "echo hello" },
  { waitUntilReady: true },
);

// or with custom wait config
const result2 = await handle.exec(
  { cmd: "echo hello" },
  { waitUntilReady: { timeoutMs: 120_000, pollIntervalMs: 1_000 } },
);

const handle = await client.sandboxes.create({
  region: "auto",                          // or a region ID
  template: "python-3.12",
  name: "scratch",
  teamId: "<team-id>",                     // omit for personal
  specs: { cpu: 500, memory: 512, disk: 2 },
  autoDestroy: true,
  destroyTimeout: "1h",                    // 30m, 1h, 3h, 6h, 12h, 18h
  oneShot: false,
  blockOutbound: false,
  persistent: true,
  persistentDiskGB: 20,
  // volumeId: "<existing-volume-id>",
  // fromSnapshot: "<snapshot-id>",
  snapshotMode: "automatic",
  snapshotFrequency: "0 */2 * * *",
});

const page = await client.sandboxes.list({ page: 1, limit: 15, teamId: "<team>" });
const handle = await client.sandboxes.get(sandboxId);
await client.sandboxes.destroy(sandboxId);

for await (const handle of client.sandboxes.iterate({ limit: 50 })) {
  console.log(handle.id, handle.status);
}

await handle.pause();
await handle.resume();

const result = await handle.exec({
  cmd: "echo hello && uname -a",
  timeout_seconds: 30,
  cwd: "/work",
});
console.log(result.stdout, result.stderr, result.exit_code, result.duration_ms);

const result = await handle.runCode({
  language: "python",       // or "node"
  code: "import sys; print(sys.version)",
});

const result = await handle.exec({
  cmd: "node script.js",
  env: {
    NODE_ENV: "production",
    OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
    REQUEST_ID: requestId,
  },
});

// Same shape on runCode
await handle.runCode({
  language: "python",
  code: "import os; print(os.environ['MY_KEY'])",
  env: { MY_KEY: "value" },
});

// Pass `stream: true` and the return type narrows to ReadableStream<Uint8Array>
const stream = await handle.exec({
  cmd: "pip install -r requirements.txt",
  stream: true,
});

const reader = stream.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buffer.indexOf("\n")) >= 0) {
    const frame = JSON.parse(buffer.slice(0, nl));
    buffer = buffer.slice(nl + 1);
    if (frame.type === "stdout" || frame.type === "stderr") process.stdout.write(frame.data);
    if (frame.type === "done") console.log("\nexit:", frame.exit_code);
  }
}

await handle.putFile("/app/index.js", "console.log('hello')");

const stream = await handle.getFile("/app/index.js");
// stream is a ReadableStream<Uint8Array>

const summary = await handle.putFiles([
  { path: "/work/package.json", body: JSON.stringify({ name: "demo" }) },
  { path: "/work/index.js", body: "console.log('hello')" },
  { path: "/work/README.md", body: "# demo\n" },
]);

console.log(summary.uploaded, "uploaded,", summary.failed, "failed");
for (const r of summary.results) {
  if (!r.success) console.warn("failed:", r.path, r.error);
}

const stats = await handle.stats({ hoursAgo: 1 });

// per-sandbox
const snap = await handle.snapshots.create({ name: "before-migration" });
const list = await handle.snapshots.list({ page: 1, limit: 15 });

// account-wide
const all = await client.snapshots.listAll({ limit: 50 });
await client.snapshots.delete(snapshotId);

// iterate every snapshot you own
for await (const snap of client.snapshots.iterateAll({ limit: 100 })) {
  console.log(snap.id, snap.status);
}

const handle = await client.sandboxes.createReady({
  region: "auto",
  fromSnapshot: "<snapshot-id>",
});

const volume = await client.volumes.create({
  name: "node-cache",
  sizeGB: 20,                // min 10, max 50
  region: "auto",
  teamId: "<team-id>",       // optional
});

const list = await client.volumes.list({ page: 1, limit: 15 });
const fetched = await client.volumes.get(volume.id);
await client.volumes.delete(volume.id);

const templates = await client.sandboxes.listTemplates();
const node = await client.sandboxes.getTemplate("node-22");

const regions = await client.sandboxes.listRegions();

import { RateLimitError, NotFoundError, SandboxApiError } from "@brimble/sandbox";

try {
  await client.sandboxes.get("missing");
} catch (err) {
  if (err instanceof RateLimitError) {
    await new Promise((r) => setTimeout(r, (err.retryAfterSeconds ?? 1) * 1000));
    // retry
  } else if (err instanceof NotFoundError) {
    console.warn("sandbox is gone");
  } else if (err instanceof SandboxApiError) {
    console.error(err.status, err.message, err.requestId);
  } else {
    throw err;
  }
}

const client = new Sandbox({
  retry: {
    maxAttempts: 3,
    baseDelayMs: 300,
    maxDelayMs: 3_000,
    retryStatuses: [408, 429, 500, 502, 503, 504],
  },
});

// per-call override
await client.sandboxes.create(input, {
  retry: { maxAttempts: 5 },
  idempotencyKey: crypto.randomUUID(),
});

// or disable retries on a single call
await client.sandboxes.destroy(id, { retry: false });

const handle = await client.sandboxes.createReady({ region: "auto", template: "node-22" });
try {
  // ... do work
} finally {
  await handle.destroy().catch(() => {});
}

npm install @brimble/sandbox@^0.1.2