JS SDK reference

npm install orkestr
# or
pnpm add orkestr
# or
yarn add orkestr

import { Sandbox, OrkestrClient } from "orkestr";

// 1) Implicit: SDK reads ORKESTR_API_KEY from process.env
const sbx = await Sandbox.create({ template: "python-3.12" });

// 2) Explicit: per-call apiKey
const sbx2 = await Sandbox.create({
  template: "python-3.12",
  apiKey: "ork_...",
});

// 3) Reusable client (good for long-running agents)
import { setDefaultClient } from "orkestr";
setDefaultClient(new OrkestrClient({
  apiKey: "ork_...",
  baseUrl: "https://api.orkestr.eu",
}));

import { Sandbox } from "orkestr";

const sbx = await Sandbox.create({
  template: "python-3.12",
  size: "small",
  network: "off",
  timeoutSeconds: 600,
  env: { OPENAI_API_KEY: "sk-..." },
  metadata: { agentRun: "r_42" },
  region: "fsn1",
});
console.log(sbx.id, sbx.status);

// Reattach from another process
const sbx = await Sandbox.get("sbx_01HXYZ...");

// List your sandboxes
const running = await Sandbox.list({ status: "running" });
for (const sbx of running) {
  console.log(sbx.id, sbx.template, sbx.createdAt);
}

const limits = await Sandbox.limits();
limits.plan;                            // "free"
limits.allowedSizes;                    // ["small"]
limits.allowedSizes.includes("medium"); // false
limits.maxConcurrent;                   // 1
limits.usageGbHoursUsed;                // 2.5  (memory used of the trial)
limits.usageGbHoursIncluded;            // 10.0 (one-time trial allowance)
limits.usageCpuHoursUsed;               // 0.42 (CPU used of the trial)
limits.usageCpuHoursIncluded;           // 2.0  (one-time trial allowance)
limits.usageResetsAt;                   // null - the trial does not reset
for (const s of limits.sizes) {         // full menu, each with .allowed
  console.log(s.size, s.cpu, s.memoryMb, s.allowed);
}

const result = await sbx.exec("python /workspace/main.py", {
  timeoutSeconds: 60,
});
result.stdout;      // string
result.stderr;      // string
result.exitCode;    // number
result.durationMs;  // number

for await (const chunk of sbx.execStream("python long_task.py")) {
  if (chunk.stream === "stdout") {
    process.stdout.write(chunk.data);
  } else {
    process.stderr.write(chunk.data);
  }
  if (chunk.exitCode !== undefined) {
    console.log(`exit=${chunk.exitCode} duration=${chunk.durationMs}ms`);
  }
}

// Text I/O
await sbx.files.write("/workspace/script.py", "console.log('hi')");
const content = await sbx.files.read("/workspace/output.txt");

// Binary I/O
await sbx.files.writeBytes(
  "/workspace/blob.bin",
  new Uint8Array([0, 1, 2]),
);
const raw = await sbx.files.readBytes("/workspace/blob.bin");

// Directory listing
for (const entry of await sbx.files.list("/workspace")) {
  console.log(entry.name, entry.isDir, entry.size, entry.mode);
}

// Remove
await sbx.files.delete("/workspace/output.txt");

import { Sandbox, Volume } from "orkestr";

// Attach a volume by name - created on first use (default 10 GB).
// Anything under /persist survives terminate.
let sbx = await Sandbox.create({ template: "python-3.12", volume: "my-cache" });
await sbx.exec("echo trained-weights-v1 > /persist/model.txt");
await sbx.terminate();

// A brand-new sandbox re-attaches the same volume and sees the data:
sbx = await Sandbox.create({ template: "python-3.12", volume: "my-cache" });
console.log((await sbx.exec("cat /persist/model.txt")).stdout); // trained-weights-v1

// Manage volumes explicitly (custom size, a region pin, listing, cleanup):
const vol = await Volume.create("datasets", { sizeGb: 50, region: "rbx" });
for (const v of await Volume.list()) console.log(v.name, v.sizeMb, v.status, v.region);
await Volume.move(vol.id, "hel1"); // re-home a detached volume to another region
await Volume.delete(vol.id); // rejected while attached to a running sandbox

const m = await sbx.metrics();
m.sandboxStatus;        // "running" (usage is null when paused / terminated)
m.cpu.cores;            // 1.0
m.cpu.usagePercent;     // 94.0  (% of allocated cores; 1-core pegged = 100)
m.cpu.usageCores;       // 0.94  (cores in use)
m.memory.usageBytes;    // 188743680  (working set, excludes reclaimable cache)
m.memory.usagePercent;  // 35.2  (% of m.memory.limitBytes)
m.lifetime.cpuSeconds;  // 12.84 (on-CPU seconds since the sandbox started)
for (const s of m.samples) {  // rolling ~60s window, oldest first
  console.log(s.t, s.cpuPercent, s.memBytes);
}

const sbx = await Sandbox.create({ template: "node-22", network: "open" });

// Start a server inside the sandbox (here, in the background):
await sbx.exec("nohup python3 -m http.server 3000 >/tmp/srv.log 2>&1 &");

const host = await sbx.getHost(3000);   // "3000-01hxyz....sbx.orkestr.run"
const url = `https://${host}`;          // open in a browser or embed it in your app

// Pause: returns the sandbox id, stops compute meter
const sandboxId = await sbx.pause();

// ... later ...
const resumed = await Sandbox.resume(sandboxId);

import { Sandbox } from "orkestr";

await Sandbox.withTemp({ template: "python-3.12" }, async (sbx) => {
  const result = await sbx.exec("python -c 'print(2+2)'");
  console.log(result.stdout);
});
// terminate() is awaited automatically on return, including on thrown errors

import {
  Sandbox,
  OrkestrError,
  AuthError,
  ExecTimeout,
  SandboxNotFound,
  SnapshotCapReached,
} from "orkestr";

try {
  const sbx = await Sandbox.create({ template: "python-3.12" });
  await sbx.exec("sleep 9999", { timeoutSeconds: 5 });
} catch (err) {
  if (err instanceof ExecTimeout) {
    console.log("Command timed out; sandbox is still running.");
  } else if (err instanceof AuthError) {
    console.error(`Auth failed (${err.statusCode}): ${err.detail}`);
  } else if (err instanceof OrkestrError) {
    console.error(`Other failure: ${err.message} requestId=${err.requestId}`);
  } else {
    throw err;
  }
}