@ekairos/sandbox
Sandbox domain library.
Provider-agnostic execution environments for commands, files, process streams, ports, checkpoints, and coding agents.
Schema
sandbox_sandboxes
Durable sandbox records with provider, runtime, purpose, external id, and status.
sandbox_processes
Command/process runs linked to a sandbox and optional stream output.
Actions
createSandbox
Creates a provider-backed sandbox and persists the durable sandbox id.
runCommand
Runs a command in an existing sandbox and returns the immediate result.
runCommandProcess
Runs a command as a durable process with linked stream output.
writeFiles / readFile
Moves file payloads through the sandbox boundary.
createCheckpoint / getPortUrl
Captures sandbox state and exposes running app ports.
Create once. Reconnect by sandbox id.
Workbench, agents, and templates should treat sandbox ids as durable domain ids, not provider handles.
import { sandboxDomain } from "@ekairos/sandbox";
const sandbox = await runtime.use(sandboxDomain);
const created = await sandbox.actions.createSandbox({
provider: "vercel",
runtime: "node22",
purpose: "registry-preview",
});
const run = await sandbox.actions.runCommandProcess({
sandboxId: created.data.sandboxId,
command: "sh",
args: ["-lc", "pnpm test"],
kind: "command",
mode: "foreground",
});
const stream = await sandbox.actions.readProcessStream({
processId: run.data.processId,
});