Skip to content

Guides

Commands

r = sbx.commands.run(
"echo $MODE && ls /work",
cwd="/work",
envs={"EXTRA": "1"},
timeout=30, # seconds; None or 0 = no limit
on_stdout=lambda s: print("live:", s, end=""),
)
print(r.exit_code, r.stdout)
# A list runs without a shell.
r = sbx.commands.run(["python3", "-c", "import sys; print(sys.version)"])
  • A string runs with bash -lc, so pipes, &&, globs and $VARS work. This matches E2B.
  • An argv list runs as-is, with no shell (Python and TypeScript pass a list; Go uses RunArgs, Rust run_args). This matches Vercel’s runCommand(cmd, args) and Modal’s exec(*args).
  • Where it runs: commands run as root in /work unless you give cwd.
  • The result has exit_code/exitCode/ExitCode, stdout and stderr as text (UTF-8, with invalid bytes replaced).
Option Python TypeScript Go Rust Default
Working directory cwd= cwd Cwd cwd /work (relative paths resolve against it)
Environment variables envs= envs Envs envs the sandbox’s envs
Time limit timeout= (s; None/0 = none) timeoutMs (0 = none) Timeout (negative = none) timeout: Some(Duration) (Duration::ZERO = none) 60 s
Standard input stdin= (str/bytes) stdin (string/Uint8Array) Stdin []byte stdin: Vec<u8> empty
Live output on_stdout=, on_stderr= onStdout, onStderr OnStdout, OnStderr on_stdout, on_stderr none
Detach background=True background: true Start / StartArgs start / start_with / start_args_with —
  • Timeouts: the service enforces them, and kills the command when time is up.
  • stdin: at most 16 MiB, sent up front and then closed. For more, write a file and redirect it.
  • Output callbacks: called with each chunk as it arrives, in real time. The full output is also in the result. A character whose bytes arrive in two chunks is delivered whole, with the later chunk.

A non-zero exit code is an error, as in E2B. The error carries the whole result:

try:
sbx.commands.run("exit 3")
except CommandExitError as e:
print("exit code", e.exit_code, "stderr", e.stderr)
try:
sbx.commands.run("sleep 10", timeout=1)
except TimeoutError as e:
print("timed out; partial output:", e.result.stdout if e.result else "")
Situation Python TypeScript Go Rust
Exit code ≠ 0 CommandExitError (.exit_code, .stdout, .stderr) CommandExitError (.exitCode, …) *CommandExitError Error::CommandExit(result)
Time limit passed TimeoutError (.result = output so far) TimeoutError *TimeoutError Error::Timeout { result, .. }
cwd doesn’t exist FileNotFoundError FileNotFoundError *NotFoundError (What: "directory") Error::NotFound (what: "directory")
An interactive shell is attached SandboxBusyError SandboxBusyError ErrBusy Error::Busy
Connection ended or failed before the exit status OutcomeUnknownError (.cause) OutcomeUnknownError (.cause) ErrOutcomeUnknown Error::OutcomeUnknown { cause, result }

If you’d rather not get an exception for a failing command, append || true to the command or catch the error. The error is also the result.

A background command starts and returns at once. It keeps running after the call, across pauses, and while you run other commands:

server = sbx.commands.run("python3 -m http.server 8000", background=True)
print("pid", server.pid)
print("running:", server.poll() is None)
print("killed:", server.kill())
job = sbx.commands.run("for i in 1 2 3; do echo $i; sleep 1; done", background=True)
result = job.wait(on_stdout=lambda s: print(s, end=""))
# Or iterate over output chunks as they arrive:
job = sbx.commands.run("for i in 1 2 3; do echo $i; sleep 1; done", background=True)
for stdout, stderr in job:
print(stdout or "", end="")
Handle member Python TypeScript Go Rust
Process ID pid pid PID pid
Wait for exit (raises on ≠ 0) wait(on_stdout=, on_stderr=) wait({onStdout, onStderr}) Wait(ctx, *WaitOptions) wait(), wait_with(WaitOptions)
Check without waiting poll() → code or None poll() → code or undefined Poll(ctx) → *int poll() → Option<i32>
Kill (SIGKILL to the whole process group) kill() kill() Kill(ctx) kill()
Output so far stdout, stderr stdout, stderr Stdout(), Stderr() stdout(), stderr()
Exit code once known exit_code exitCode ExitCode() exit_code()
Iterate (stdout, stderr) chunks for out, err in handle — — —

Commands-level helpers:

  • commands.list() returns every background command started in the sandbox, with its pid, command line, and whether it’s running or its exit code.
  • commands.connect(pid) gets a handle to a background command again, for example from another process.
  • commands.kill(pid) kills one by pid.

The service runs one command at a time per sandbox (see below), so a background command can’t stream its output over a held-open connection. Instead:

  • Output: it goes to files in the sandbox (/tmp/.chainguard-sandbox/cmd/<id>/).
  • Fetching: wait() fetches the output in short polls, about every 2 s, and hands it to your callbacks. Output that an earlier poll() fetched is delivered first.
  • Exit: a killed command’s exit code is 137 (128 + SIGKILL).

A sandbox runs one foreground command at a time. If you start two concurrently, the service queues the second until the first finishes. This was measured live: two concurrent sleep 3 calls took 4 s and 7 s.

To do things in parallel inside one sandbox, start background commands; the short status calls interleave between them. Also:

  • Exec vs. an interactive shell: commands are refused while an interactive shell (chainctl develop, or another Workspaces client) is attached to the same sandbox. You’ll get SandboxBusyError / ErrBusy / Error::Busy.
  • Retries: right after an attach or command ends, the service can briefly report the sandbox as held, and the library retries that for about 30 s.