Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 produces output regularly will not trip the timeout no matter how long it runs overall. A completely silent command still has to finish before the timeout.

​
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 - abort 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 - timeout elapsed before the command finished
  • NotFoundError - sandbox was deleted
  • ConflictError - sandbox is in an invalid state
  • SandboxError - connection dropped mid-stream without a terminal finished event (streaming only)
See Errors for the full hierarchy.