Skip to main content
The runStreamingCommand() method is designed for executing long-running or interactive commands inside a sandbox while receiving real-time output streams. Unlike runCommand(), which waits for a command to complete before returning output, this method streams data continuously through callbacks as soon as it’s produced. It’s the recommended way to handle installations, builds, and background processes such as servers that may run indefinitely. Each chunk of data from stdout or stderr is sent to the provided callbacks immediately, giving you full control over how logs and errors are displayed. Once execution completes, the method returns an object containing the aggregated stdout, stderr, and exitCode.

​
runStreamingCommand(options)

Description: Executes a long-running command with real-time output streaming. Use this for installations, builds, servers, or any operation that takes more than 5 seconds. Callbacks are invoked as data arrives. Parameters:
ParameterTypeRequiredDescription
cmdstringYesCommand to execute
argsstring[]YesArray of command arguments
stdinstringNoStandard input to send to the command
onStdout(data: string) => voidNoCallback for stdout data chunks
onStderr(data: string) => voidNoCallback for stderr data chunks
Returns: 
Promise<{
  stdout: string   // Complete accumulated output
  stderr: string   // Complete accumulated errors
  exitCode: number // Process exit code (0 = success)
}>
Example: 
// Basic streaming
const result = await sandbox.runStreamingCommand({
  cmd: 'npm',
  args: ['install', 'express'],
  onStdout: (data) => console.log(data.trim()),
  onStderr: (data) => console.error(data.trim())
})
console.log('Exit code:', result.exitCode)

// Build process with progress
await sandbox.runStreamingCommand({
  cmd: 'npm',
  args: ['run', 'build'],
  onStdout: (chunk) => {
    process.stdout.write(chunk) // Stream to terminal
  }
})

// Server (runs indefinitely)
sandbox.runStreamingCommand({
  cmd: 'node',
  args: ['server.js'],
  onStdout: (data) => console.log('[Server]', data.trim())
})
// Don't await if you want it to run in background

// With stdin
const result = await sandbox.runStreamingCommand({
  cmd: 'node',
  args: ['-e', 'process.stdin.on("data", d => console.log(d.toString()))'],
  stdin: 'Hello from stdin\n'
})
Throws:
  • Error: "Not connected" - Must call create() or fromSnippet() first
  • Error: "Unexpected response event type" - Internal protocol error
Exit Codes:
  • 0 - Success
  • Non-zero - Error (e.g., 1 for general errors, 127 for command not found)
Streaming Behavior:
  • Callbacks invoked immediately as data arrives
  • Data comes in chunks (may be partial lines)
  • Use .trim() to clean up newlines
  • Both callbacks and return value contain all output
Long-Running Processes: 
// Background server - don't await
sandbox.runStreamingCommand({
  cmd: 'python',
  args: ['-m', 'http.server', '3000']
})

// Do other work while server runs
const url = await sandbox.exposePort(3000)
console.log('Server running at:', url)
Best Practices:
  • Always provide onStdout and onStderr for visibility
  • Check exitCode to verify success
  • For servers, don’t await the promise
  • Use stdin for interactive programs