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).

Timeouts

Pass a timeout to kill a command that runs longer than you expect.

const result = await sandbox.commands.run("sleep 100", {
  timeoutMs: 5_000,
})

result = sandbox.commands.run("sleep 100", timeout_seconds=5)

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

​Handling exit codes

​Working directory and environment

​Timeouts

Handling exit codes

Working directory and environment

Timeouts