Stream command output

Pass output callbacks to commands.run when the application should process data before the command finishes.

mjs

import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  await sandbox.commands.run("printf 'first\\n'; sleep 1; printf 'second\\n'", {
    onStdout: (data) => process.stdout.write(data),
    onStderr: (data) => process.stderr.write(data),
  });
} finally {
  await sandbox.kill();
}

import sys

from agentbox import Sandbox


sandbox = Sandbox.create()

try:
    sandbox.commands.run(
        "printf 'first\\n'; sleep 1; printf 'second\\n'",
        on_stdout=lambda data: sys.stdout.write(data),
        on_stderr=lambda data: sys.stderr.write(data),
    )
finally:
    sandbox.kill()

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func kill(sandbox *agentbox.Sandbox) {
	if _, err := sandbox.Kill(context.Background()); err != nil {
		log.Printf("cleanup sandbox: %v", err)
	}
}

func run() (err error) {
	ctx := context.Background()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		return err
	}
	defer kill(sandbox)
	_, err = sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{
		Streaming: &agentbox.CommandStreamingOptions{},
		Args:      []string{"-lc", "printf 'first\\n'; sleep 1; printf 'second\\n'"},
		OnStdout:  func(chunk []byte) { fmt.Print(string(chunk)) },
		OnStderr:  func(chunk []byte) { fmt.Print(string(chunk)) },
	})
	if err != nil {
		return err
	}
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

Each callback receives a chunk, not necessarily a complete line. Write chunks as they arrive or buffer them if you need line-oriented processing.

commands.run resolves only after the command exits. The Go example enables Streaming to deliver output through callbacks without retaining it in the result. Omit Streaming when you also need the complete output after completion. Use a background command when the caller must continue immediately.

Long-running commands in Go

For processes that stay alive across requests, the Go SDK supports output streaming without retaining the complete stdout and stderr. Set CommandOptions.Streaming when starting the process and CommandConnectOptions.Streaming when reattaching through ConnectWithOptions. The default collecting mode remains useful when the application needs the full result from Wait.

Select one delivery path for each output: a callback, an explicitly enabled channel, or discard. An output with neither a callback nor a selected channel is discarded. In streaming mode, callbacks do not also queue bytes for channels. Callback slices are read-only and valid until the callback returns. Copy bytes that the application needs to keep.

Read every enabled channel concurrently with Wait. Channels are unbuffered and transfer owned slices of at most 32 KiB. A stalled reader applies backpressure and can eventually stall the remote process. Transport messages are limited to 4 MiB. Wait returns exit metadata and errors, with no retained stdout or stderr.

Call Close on the command handle to detach locally without killing the process or closing stdin. Canceling the attachment context has the same effect. A running callback must return before Wait completes. Reattachment does not guarantee replay of output emitted while disconnected.

See the Go streaming options for the complete delivery contract. PTY processes support the same policy through PTYOptions.Streaming and PTY.ConnectWithOptions.

Stream command output ​

Long-running commands in Go ​

Stream command output

Long-running commands in Go