Skip to main content

​
Run a Command

sandbox.exec(...) to run a command in the sandbox. 
const result = await sandbox.exec("node -v");

console.log("Exit code:", result.exitCode);
console.log("Stdout:", result.stdout.trim());
console.log("Stderr:", result.stderr.trim());
You can also pass request-scoped options on the same call: 
const result = await sandbox.exec("pwd && echo $FOO && whoami", {
  cwd: "/tmp",
  env: {
    FOO: "bar",
  },
  timeoutMs: 5_000,
  runAs: "root",
});

​
Start a Background Process

Use sandbox.processes.start(...) when you need to keep a process running: 
const process = await sandbox.processes.start(
  "read line; echo stdout:$line; echo stderr:$line 1>&2",
  {
    runAs: "root",
  }
);

await process.writeStdin({
  data: "hello\n",
  eof: true,
});

const result = await process.wait();
console.log(result.stdout);
console.log(result.stderr);

​
Get, List, and Signal Processes

Inspect running processes or control them later by ID: 
const process = await sandbox.processes.start("sleep 30", {
  runAs: "root",
});

const fetched = await sandbox.getProcess(process.id);
const listing = await sandbox.processes.list({
  status: "running",
  limit: 20,
});

await fetched.signal("TERM");
const result = await fetched.wait();

console.log(listing.data.map((entry) => entry.id));
console.log(result.status);
result() is a convenience alias for wait() on a process handle.

​
Stream Process Output

Stream stdout and stderr as server-sent events: 
const process = await sandbox.processes.start("echo stream-out; echo stream-err 1>&2");

for await (const event of process.stream()) {
  if (event.type === "exit") {
    console.log("Exited with:", event.result.exitCode);
    break;
  }

  console.log(event.type, event.data);
}

​
Common Parameters

​
command
string
required
Command to run inside the sandbox.
​
cwd
string
Working directory for the process.
​
env
object
Environment variables to inject into the process.
​
timeoutMs
number
Maximum runtime in milliseconds.
​
runAs
string
Run the command as a specific sandbox user, for example root.

​
Process Status Values

  • queued
  • running
  • exited
  • failed
  • killed
  • timed_out