@sapiom/sandbox

Sandbox environment management for the Sapiom SDK. Create isolated execution environments, manage files, run commands, and stream output in real time.

Installation

npm install @sapiom/sandbox
# or
pnpm add @sapiom/sandbox

Quickstart

import { SapiomSandbox } from "@sapiom/sandbox";

// Create a sandbox (uses SAPIOM_API_KEY env var by default)
const sandbox = await SapiomSandbox.create({ name: "my-sandbox" });

// Write a file
await sandbox.writeFile("hello.py", 'print("Hello from the sandbox!")');

// Execute a command and wait for completion
const result = await sandbox.exec("python hello.py");
console.log(result.stdout); // "Hello from the sandbox!"

// Stream output from a long-running process
const proc = await sandbox.execStream("node runner.js");
for await (const line of proc.output) {
  console.log(`[${line.stream}] ${line.data}`);
}
console.log("exit code:", proc.exitCode);

// Clean up
await sandbox.destroy();

API

SapiomSandbox.create(opts)

Creates a new sandbox and returns a handle for interacting with it.

const sandbox = await SapiomSandbox.create({
  name: "my-sandbox",
  tier: "m",
  ttl: "1h",
  image: "python:3.12",
  envs: { NODE_ENV: "production" },
});

Options:

| Option | Type | Required | Description | |-----------|--------------------------|----------|-------------------------------------------------------| | name | string | Yes | Sandbox name (lowercase alphanumeric + hyphens, 2-63 chars) | | apiKey | string | No | Sapiom API key. Falls back to SAPIOM_API_KEY env var | | baseUrl | string | No | Override the sandbox service URL | | fetch | typeof fetch | No | Pre-configured fetch function (overrides apiKey) | | tier | SandboxTier | No | Memory tier: 'xs', 's', 'm', 'l', 'xl' (default 's') | | ttl | string | No | Time-to-live (e.g. '1h', '24h', '7d') | | envs | Record<string, string> | No | Environment variables | | port | number | No | Single port to expose (mutually exclusive with ports) | | ports | PortSpec[] | No | Array of port specs to expose (mutually exclusive with port) | | image | string | No | Pre-built Docker image for instant creation |

sandbox.writeFile(path, content)

Writes a file relative to the sandbox's workspace root.

await sandbox.writeFile("src/index.ts", 'console.log("hi")');

sandbox.readFile(path)

Reads a file relative to the sandbox's workspace root and returns its content as a string.

const content = await sandbox.readFile("src/index.ts");

sandbox.exec(command, opts?)

Executes a shell command inside the sandbox. By default waits for the process to finish.

// Wait for completion (default)
const result = await sandbox.exec("npm install");
console.log(result.exitCode); // 0
console.log(result.stdout);
console.log(result.stderr);

// Fire-and-forget
const bg = await sandbox.exec("npm start", { waitForCompletion: false });
console.log(bg.pid);

// Check on it later
const status = await sandbox.getProcess(bg.pid);
console.log(status.completed, status.exitCode);

// Or wait for it to finish
const final = await sandbox.waitForProcess(bg.pid);
console.log(final.exitCode);

Options:

| Option | Type | Default | Description | |----------------------|--------------------------|---------|--------------------------------------------------| | cwd | string | — | Working directory (resolved relative to workspaceRoot) | | env | Record<string, string> | — | Environment variables for the process | | waitForCompletion | boolean | true | Wait for the process to finish | | pollInterval | number | 1000 | Polling interval in ms | | timeout | number | 60000 | Timeout in ms when waiting | | signal | AbortSignal | — | Signal to cancel the operation |

sandbox.execStream(command, opts?)

Executes a command and streams output in real time via an async iterable. Ideal for long-running processes like AI agent runs.

const proc = await sandbox.execStream("node agent.js");
for await (const line of proc.output) {
  // line.stream is 'stdout' or 'stderr'
  process.stdout.write(line.data);
}
console.log("exit code:", proc.exitCode);

Supports cancellation via AbortSignal:

const controller = new AbortController();
const proc = await sandbox.execStream("long-task", {
  signal: controller.signal,
});

setTimeout(() => controller.abort(), 30_000);

for await (const line of proc.output) {
  console.log(line.data);
}

Options:

| Option | Type | Default | Description | |-----------|--------------------------|---------|--------------------------------------------------| | cwd | string | — | Working directory (resolved relative to workspaceRoot) | | env | Record<string, string> | — | Environment variables for the process | | signal | AbortSignal | — | Signal to cancel the operation |

sandbox.getProcess(pid)

Gets the current status of a process by PID.

const status = await sandbox.getProcess(pid);
console.log(status.completed, status.exitCode);

sandbox.waitForProcess(pid, opts?)

Waits for a process to complete by polling its status. Returns the same ExecResult as exec().

const result = await sandbox.waitForProcess(pid, { timeout: 120_000 });
console.log(result.exitCode, result.stdout);

sandbox.destroy()

Destroys the sandbox and releases all associated resources.

await sandbox.destroy();

Properties

| Property | Type | Description | |-------------------------|----------|----------------------------------------------| | sandbox.name | string | Sandbox identifier | | sandbox.workspaceRoot | string | Absolute workspace root path in the sandbox |

License

MIT