Skip to main content
Run shell commands inside a sandbox via sandbox.commands. Running a command on a paused sandbox transparently resumes it and executes.

​
run (synchronous)

Execute a command and wait for it to finish. Returns a CommandResult. 
const result = await sandbox.commands.run("echo hello")
console.log(result.stdout)    // "hello\n"
console.log(result.stderr)    // ""
console.log(result.exitCode)  // 0

​
run (streaming)

Pass onStdout / on_stdout and/or onStderr / on_stderr callbacks. Output is delivered over Server-Sent Events and flushed to your callback as it arrives. The final result still contains the full concatenated output. 
const result = await sandbox.commands.run("npm run build", {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  timeoutMs: 300_000,
})
Streaming uses an idle timeout: the timer resets on every chunk. A command that keeps producing output never trips it, however long it runs. A command that goes silent still has to finish before the timeout.

​
spawn (interactive session)

spawn() hands back a CommandSession while the process is still running. Stream its output with callbacks, write to stdin, signal it, and call wait() for the result. Output comes over a WebSocket. The sessions guide walks through it. 
const session = await sandbox.commands.spawn("python -i", {
  onStdout: (data) => process.stdout.write(data),
})
session.stdin.write("print(2 + 2)\n")
session.stdin.close()
const result = await session.wait()
In Python, spawn() is on AsyncSandbox only; the synchronous version raises. It takes the same cwd, env, timeoutMs / timeout_seconds, onStdout, and onStderr options as run. Leave the timeout off for a long-lived process.

​
CommandSession

MemberDescription
stdin.write(data)Write to stdin: a string (UTF-8) or raw bytes.
stdin.close()Close stdin, signalling EOF.
kill(signal?)Send a signal (default "SIGTERM").
wait()Resolve with the CommandResult on exit; rejects if the connection drops first.
close()Kill the process and close the connection.
In Python the methods are awaitable (await session.stdin.write(...), await session.kill(), await session.wait()) and the session is an async with context manager. In TypeScript the session supports await using for automatic cleanup.

​
Options

OptionTypeDescription
cwdstringWorking directory. Server-side default when unset.
envRecord<string, string>Env vars for this command only (merged with sandbox-wide env vars).
timeoutMs / timeout_secondsnumberCommand timeout. Only sent when specified.
onStdout / on_stdout(data: string) => voidStream stdout chunks.
onStderr / on_stderr(data: string) => voidStream stderr chunks.
signalAbortSignalTypeScript only. Aborts mid-execution.

​
CommandResult

interface CommandResult {
  stdout: string
  stderr: string
  exitCode: number
}

​
Non-zero exit codes

run() does not raise for non-zero exits. Inspect the exit code yourself. 
const result = await sandbox.commands.run("exit 42")
if (result.exitCode !== 0) {
  console.error(`Failed: ${result.stderr}`)
}

​
Errors

Commonly raised:
  • TimeoutError / SandboxTimeoutError: the timeout elapsed before the command finished
  • NotFoundError: the sandbox was deleted
  • ConflictError: the sandbox is in an invalid state
  • SandboxError: the connection dropped mid-stream without a terminal finished event (streaming only)
See Errors for the full hierarchy.