Stream command output

For builds, training runs, servers, or anything else that takes a while, pass onStdout / on_stdout and onStderr / on_stderr callbacks. Output arrives as the command produces it, one line at a time, or in chunks when it comes fast.

const result = await sandbox.commands.run("npm run build", {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  timeoutMs: 300_000,
})

console.log(`Build exited ${result.exitCode}`)

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

print(f"Build exited {result.exit_code}")

Even while streaming, the returned result still holds the complete stdout and stderr.

AsyncSandbox takes the same callbacks with an awaitable run(). See the Sandbox reference.

Command timeout

timeoutMs / timeout_seconds is a wall-clock limit on the whole command. Output does not reset it. A command that keeps printing output still stops at the limit, and run() returns exit code 124. If you leave the timeout off, the limit is 30 seconds, so set a timeout that is longer than your longest expected run. See Timeouts for the defaults.

If the connection drops

If the stream ends before the finished event (a network hiccup, say), run() throws SandboxError, and the sandbox then stops the command. A run() without callbacks is different: if the client goes away, the command keeps running until it exits or reaches its timeout. Either way, nothing reattaches to command output. Sandbox.connect(id) gets you the sandbox back to run new commands, not the old stream. For a job that has to outlive the connection, start it in the background with its output in a file, then read the file later. run() returns as soon as the job starts, and the job isn’t bound by the command timeout:

nohup ./job.sh > /home/user/job.log 2>&1 &

A background job doesn’t count as activity, so a sandbox with an idle timeout can pause while the job runs.

Capture and stream together

Streaming and sync return aren’t mutually exclusive - capture chunks for logs while also collecting the full buffer for analysis.

const result = await sandbox.commands.run("./long-job.sh", {
  onStdout: (data) => process.stdout.write(data), // watch it live
  timeoutMs: 600_000,
})

await uploadLogs(result.stdout) // full buffer, already captured for you

result = sandbox.commands.run(
    "./long-job.sh",
    on_stdout=lambda data: print(data, end=""),  # watch it live
    timeout_seconds=600,
)

upload_logs(result.stdout)  # full buffer, already captured for you

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

Stream command output

Command timeout

If the connection drops

Capture and stream together

​Command timeout

​If the connection drops

​Capture and stream together

Command timeout

If the connection drops

Capture and stream together