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 (newest first)
const running = await Sandbox.list({ status: "running" });
for (const sbx of running) {
  console.log(sbx.id, sbx.template, sbx.createdAt);
}

// Find the sandbox for a session by its metadata tags (AND across keys).
// list() auto-pages; pass maxResults to cap.
const forUser = await Sandbox.list({ metadata: { userId: "42", session: "abc" } });

const limits = await Sandbox.limits();
limits.plan;                            // "free"
limits.allowedSizes;                    // ["small"]
limits.allowedSizes.includes("medium"); // false
limits.maxConcurrent;                   // 2    (RAM budget as a count of small boxes)
limits.maxSnapshots;                    // 1    (paused sandboxes you may hold)
limits.trialCreditEur;                  // 10.0 (one-time trial credit, EUR)
limits.trialCreditUsedEur;              // 2.5  (spent so far; the trial never resets)
limits.defaultEgressDomains;            // the restricted-mode default allowlist
for (const r of limits.regions) {       // regions a create may pin right now
  console.log(r.id, r.label);
}
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`);
  }
}

// Start a dev server without nohup gymnastics:
const handle = await sbx.exec("python -m http.server 8000", { background: true });
handle.pid; handle.status;        // 41, "running"

// Reattach from another process:
for (const cmd of await sbx.commands()) {
  console.log(cmd.id, cmd.command, cmd.status);
}

(await handle.logs()).content;    // buffered output so far
for await (const chunk of handle.stream()) {  // ...or follow it live
  process.stdout.write(chunk.data);
}

await handle.wait({ timeoutSeconds: 120 });  // block until it stops
await handle.kill();              // SIGTERM the process group, then SIGKILL

const sbx = await Sandbox.create({ template: "code-interpreter" });

await sbx.runCode("import pandas as pd; df = pd.read_csv('sales.csv')");
const execution = await sbx.runCode("df.describe()"); // df persisted

execution.results[0]?.text;   // text rendering of the final expression
execution.results[0]?.html;   // ...and the HTML table
execution.error;              // structured CodeError on a raising cell, else null

// Isolated contexts: separate interpreters inside one sandbox
const ctx = await sbx.createCodeContext();
await ctx.runCode("x = 1");   // invisible to the default context

// 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);
}

// Directory + move + stat/exists (no shelling out)
await sbx.files.mkdir("/workspace/data");        // mkdir -p by default
await sbx.files.move("/workspace/a", "/workspace/data/a");
const st = await sbx.files.stat("/workspace/data/a");  // .exists is a normal check
if (st.exists && !st.isDir) console.log(st.size, st.mode);
await sbx.files.exists("/workspace/nope");       // false, not an error

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

// Many files in one call (scaffolding a project without N round-trips).
// Per-file results: a bad path fails its own row, the rest still land.
const results = await sbx.files.writeBatch({
  "/workspace/src/app.py": "print('hi')",
  "/workspace/README.md": "# my app",
});
for (const r of results) {
  console.log(r.path, r.bytesWritten, r.error); // error is null on success
}

// Large files: mint a pre-signed URL and move bytes directly - plain
// HTTP, no auth header, no base64, no 16 MiB cap. Reusable until expiry.
const up = await sbx.files.presignUpload("/workspace/dataset.csv", { expiresIn: 600 });
// await fetch(up.url, { method: "PUT", body: file });

const down = await sbx.files.presignDownload("/workspace/out/report.pdf");
console.log(down.url); // hand to a browser, curl, or another service

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

import { Webhook, verifyWebhookSignature } from "orkestr";

// Register once; store the secret - it is shown ONLY in this response.
const whk = await Webhook.create("https://example.com/hooks/orkestr", {
  eventTypes: ["sandbox.paused", "sandbox.expired"], // omit for all events
});
saveSomewhere(whk.secret); // whsec_...

// In your receiver (Express shown), verify the RAW body before parsing:
app.post("/hooks/orkestr", express.raw({ type: "*/*" }), async (req, res) => {
  const ok = await verifyWebhookSignature(
    secret, req.body, req.get("X-Orkestr-Signature"),
  );
  if (!ok) return res.status(401).end();
  const delivery = JSON.parse(req.body); // {event: "sandbox.paused", data: {...}}
  res.status(200).end();
});

await Webhook.list();        // your registrations; secret never included
await Webhook.enable(whk.id); // re-arm one disabled after repeated failures
await Webhook.delete(whk.id);

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;  // 17.6  (% 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

await sbx.setTimeout(3600);   // live for another hour from now
console.log(sbx.expiresAt);   // the new deadline

// 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;
  }
}