Commands - Superserve

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

result = sandbox.commands.run("echo hello")
print(result.stdout)     # "hello\n"
print(result.stderr)     # ""
print(result.exit_code)  # 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,
})

import sys

result = sandbox.commands.run(
    "npm run build",
    on_stdout=lambda data: sys.stdout.write(data),
    on_stderr=lambda data: sys.stderr.write(data),
    timeout_seconds=300,
)

The timeout is a wall-clock limit, also for streamed commands. Output does not reset it. At the limit, the command stops and run() returns exit code 124. See Timeouts for the defaults.

`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()

# async only, so use AsyncSandbox
session = await sandbox.commands.spawn(
    "python -i",
    on_stdout=lambda data: print(data, end=""),
)
await session.stdin.write("print(2 + 2)\n")
await session.stdin.close()
result = await session.wait()

In Python, spawn() is on AsyncSandbox only; the synchronous version raises. It takes the same cwd, user, env, timeoutMs / timeout_seconds, onStdout / on_stdout, and onStderr / on_stderr options as run. Unlike run, it has no default timeout, so leave the timeout off for a long-lived process.

`CommandSession`

Member	Description
`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. The sandbox stops the process when the connection drops, and a session can’t be reattached.
`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

Option	Type	Description
`cwd`	`string`	Working directory. Server-side default when unset.
`user`	`string`	User to run as: a name or uid, optionally `:group` (`"root"`, `"1000"`, `"app:app"`). Defaults to the template’s user (the image’s `USER`, or the template’s `user` step).
`env`	`Record<string, string>`	Env vars for this command only (merged with sandbox-wide env vars).
`timeoutMs` / `timeout_seconds`	`number`	Hard limit on how long the command runs. At the limit, the command stops and the result has exit code `124`. When unset, `run` stops the command after 30 seconds and `spawn` has no limit. TypeScript rounds up to whole seconds; `run` treats `0` as unset and throws `ValidationError` for a value that is negative, not finite, or out of range.
`onStdout` / `on_stdout`	`(data: string) => void`	Stream stdout chunks.
`onStderr` / `on_stderr`	`(data: string) => void`	Stream stderr chunks.
`signal`	`AbortSignal`	TypeScript only. On `run`, stops waiting and throws. Without callbacks, the command keeps running in the sandbox until it exits or reaches its timeout; with callbacks, the sandbox stops it. On `spawn`, cancels the start, or kills the process once it’s running.
`startupSignal`	`AbortSignal`	TypeScript only, `spawn` only. Cancels only the connect and start; a command already running is left alone. Defaults to `signal`.
`maxOutputBytes`	`number`	TypeScript only, `run` without callbacks. Largest response body the SDK buffers. Defaults to 10 MiB. A larger response throws `ValidationError`.

`CommandResult`

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

from pydantic import BaseModel

class CommandResult(BaseModel):
    stdout: str
    stderr: str
    exit_code: int
    truncated: bool = False

exitCode / exit_code is 124 when the command reached its timeout. truncated is true when the output of a run() without callbacks reached the 8 MiB cap on JSON-encoded stdout and stderr combined. Escaped characters count for more than one byte, so the cap can be reached below 8 MiB of raw output. The sandbox drops the rest of the output and appends a notice to stderr. Streamed runs return the full output, and truncated is always false for them.

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}`)
}

result = sandbox.commands.run("exit 42")
if result.exit_code != 0:
    print(f"Failed: {result.stderr}")

Errors

Commonly raised:

TimeoutError / SandboxTimeoutError: the SDK stopped waiting for a response. A sync run() without a timeout throws this after 30 seconds. A command that reaches its own timeout doesn’t throw: it returns exit code 124.
ValidationError: an invalid timeoutMs, or a response larger than maxOutputBytes (TypeScript)
NotFoundError: the sandbox was deleted
ConflictError: the sandbox is in an invalid state
SandboxError: the connection dropped before the command finished (streaming and spawn), or a TypeScript signal aborted a run(). The sandbox stops a streamed run() command or a spawn() process. A run() without callbacks keeps running until it exits or reaches its timeout. None can be reattached.

See Errors for the full hierarchy.

​run (synchronous)

​run (streaming)

​spawn (interactive session)

​CommandSession

​Options

​CommandResult

​Non-zero exit codes

​Errors

`run` (synchronous)

`run` (streaming)

`spawn` (interactive session)

`CommandSession`

Options

`CommandResult`

Non-zero exit codes

Errors