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() starts a command and gives you the result once it finishes. spawn() is for when you need to stay connected while it runs: send it input, signal it, and read its output as it arrives. You get back a session and keep it until the process exits. 
const session = await sandbox.commands.spawn("python -i", {
  onStdout: (data) => process.stdout.write(data),
})

session.stdin.write("print(2 + 2)\n")
session.stdin.close() // EOF, so the REPL exits

const result = await session.wait()
console.log(`exited ${result.exitCode}`)
In Python, spawn() is on AsyncSandbox only; the synchronous Sandbox.commands.spawn() raises and points you there. In TypeScript it works in the browser and in Node 22+. Older Node needs a WebSocket polyfill such as ws.

​
When to use which

Most of the time you want run(): scripts, builds, anything that takes its input up front and hands back output. Switch to spawn() when the process reads from stdin, when you need to signal it, or when you’re streaming an agent’s output and feeding it more as it goes.
run()spawn()
Gives youthe result, once it finishesa session, while it runs
Stdinnonestdin.write(), stdin.close()
Signalsnonekill()

​
The session

spawn() resolves once the process is running and hands back a session:
  • stdin.write(data) takes a string or raw bytes. stdin.close() sends EOF, which programs like cat or a REPL wait for before they finish.
  • kill(signal) sends a signal, SIGTERM by default.
  • wait() resolves with the result when the process exits.
  • Wrap the session in await using (TypeScript) or async with (Python) and it kills the process and closes the connection when the block ends.
The SDK reference lists the full surface.

​
If the connection drops

wait() fails if the socket closes before the command finishes. The process keeps running inside the sandbox, so save the ID and pick it back up with Sandbox.connect(id). A paused sandbox wakes on its own before the session opens.