Run commands in a sandbox

Run any shell command inside a sandbox using sandbox.commands.run().

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  fromTemplate: "superserve/python-3.11",
})
const result = await sandbox.commands.run("python analyze.py")
console.log(result.stdout)

from superserve import Sandbox

sandbox = Sandbox.create(name="data-analyzer", from_template="superserve/python-3.11")
result = sandbox.commands.run("python analyze.py")
print(result.stdout)

sandbox.kill()

This page covers run(). If you need to send input to a process while it runs, like a REPL, spawn() keeps the session open instead.

Using AsyncSandbox? The same methods are there, awaitable. See the Sandbox reference.

Handling exit codes

run() doesn’t throw on a non-zero exit code. Check exitCode on the result yourself.

const result = await sandbox.commands.run("exit 42")
if (result.exitCode !== 0) {
  console.error(`Command failed: ${result.stderr}`)
}

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

Working directory and environment

Pass cwd and env to control the execution context.

const result = await sandbox.commands.run("python script.py", {
  cwd: "/app",
  env: { PORT: "3000", DEBUG: "1" },
  timeoutMs: 60_000,
})

result = sandbox.commands.run(
    "python script.py",
    cwd="/app",
    env={"PORT": "3000", "DEBUG": "1"},
    timeout_seconds=60,
)

Watch the units: TypeScript takes timeoutMs (milliseconds), Python takes timeout_seconds (seconds).

Commands run as the template’s user (the image’s USER, or the template’s user step). Pass user to run as someone else, like docker exec -u: a name or uid, optionally :group, e.g. user: "root" to install a package.

Timeouts

The timeout is a hard limit on how long a command runs. When it’s reached, the sandbox stops the command and run() returns with exit code 124. It doesn’t throw, so check the exit code. Output doesn’t extend the limit: a command that keeps printing still stops on time.

const result = await sandbox.commands.run("sleep 100", {
  timeoutMs: 5_000,
})
if (result.exitCode === 124) {
  console.error("Timed out after 5 seconds")
}

result = sandbox.commands.run("sleep 100", timeout_seconds=5)
if result.exit_code == 124:
    print("Timed out after 5 seconds")

What happens depends on the method and whether you set a timeout:

	Timeout left off	Timeout set
`run()`	The sandbox stops the command after 30 seconds. Without callbacks, the SDK also stops waiting at 30 seconds and throws `TimeoutError` / `SandboxTimeoutError`. With callbacks, the result has exit code `124`.	The sandbox stops the command at the limit, and the result has exit code `124`.
`spawn()`	No limit. The process runs until it exits or you kill it.	The sandbox stops the process at the limit, and `wait()` resolves with exit code `124`.

Set a timeout on any run() that can take longer than 30 seconds. For a process with no fixed end, like a server, use spawn() without one.

TypeScript rounds timeoutMs up to whole seconds. run() treats timeoutMs: 0 the same as leaving it out, and throws ValidationError for a value that is negative, not finite, or out of range.

Large output

Without callbacks, run() returns stdout and stderr in one JSON response, capped at 8 MiB of JSON-encoded output for both streams together. Characters that JSON escapes count for more than one byte (a < counts as six), so output with many of them is cut below 8 MiB of raw text. When the cap is reached, the sandbox drops the rest, sets truncated to true on the result, and appends a notice to stderr. The command itself still runs to the end.

const result = await sandbox.commands.run("cat big.log")
if (result.truncated) {
  console.warn("Output was truncated")
}

result = sandbox.commands.run("cat big.log")
if result.truncated:
    print("Output was truncated")

For the full output, stream it with callbacks, or redirect it to a file in the sandbox and read the file. Streamed runs return everything, and truncated is always false. For longer commands, stream the output as it runs. To send input to a process while it runs, open a session.

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

Run commands in a sandbox

Handling exit codes

Working directory and environment

Timeouts

Large output

​Handling exit codes

​Working directory and environment

​Timeouts

​Large output

Handling exit codes

Working directory and environment

Timeouts

Large output