Skip to main content
Use the process API for one-shot commands, long-running processes, stdin, signals, and output streaming.

​
Run a One-shot Command

sandbox.exec(...) is the simplest way to run a command in a 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 structured command parameters: 
const result = await sandbox.exec({
  command: "bash",
  args: ["-lc", "pwd && echo $FOO"],
  cwd: "/tmp",
  env: {
    FOO: "bar",
  },
  timeoutMs: 5_000,
});

​
Start a Background Process

Use sandbox.processes.start(...) when you need to keep a process running: 
const process = await sandbox.processes.start({
  command: "bash",
  args: ["-lc", "read line; echo stdout:$line; echo stderr:$line 1>&2"],
});

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({
  command: "bash",
  args: ["-lc", "sleep 30"],
});

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({
  command: "bash",
  args: ["-lc", "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.
​
args
string[]
Optional command arguments.
​
cwd
string
Working directory for the process.
​
env
object
Environment variables to inject into the process.
​
timeoutMs
number
Maximum runtime in milliseconds.
​
useShell
boolean
Run the command through a shell.

​
Process Status Values

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