Streaming

Real-time output streaming with executeStream()

The executeStream() method returns an AsyncIterable<StreamEvent> that yields stdout, stderr, exit, and error events in real time as code executes.

Basic Usage

for await (const event of isol8.executeStream({
  code: `
import time
for i in range(5):
    print(f"Step {i}")
    time.sleep(1)
  `,
  runtime: "python",
})) {
  switch (event.type) {
    case "stdout":
      process.stdout.write(event.data);
      break;
    case "stderr":
      process.stderr.write(event.data);
      break;
    case "exit":
      console.log("Exit code:", event.data);
      break;
    case "error":
      console.error("Error:", event.data);
      break;
  }
}

StreamEvent Type

interface StreamEvent {
  type: "stdout" | "stderr" | "exit" | "error";
  data: string;
}

Type	Description
stdout	A chunk of standard output text
stderr	A chunk of standard error text
exit	The exit code as a string (e.g. "0")
error	An error message (container failure, timeout, etc.)

Events arrive in the order they are produced. The exit event is always the last event in a successful execution.

Streaming via HTTP (SSE)

The HTTP server exposes streaming via Server-Sent Events at POST /execute/stream:

curl -N -X POST http://localhost:3000/execute/stream \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "code": "for i in range(5): print(i)",
      "runtime": "python"
    }
  }'

Each SSE message:

data: {"type":"stdout","data":"0\n"}

data: {"type":"stdout","data":"1\n"}

data: {"type":"exit","data":"0"}

RemoteIsol8 Streaming

RemoteIsol8 automatically handles SSE parsing, so executeStream() works the same way:

import { RemoteIsol8 } from "isol8";

const remote = new RemoteIsol8({
  host: "http://localhost:3000",
  apiKey: "my-key",
});

await remote.start();

for await (const event of remote.executeStream({
  code: "print('streaming!')",
  runtime: "python",
})) {
  if (event.type === "stdout") {
    process.stdout.write(event.data);
  }
}

Timeout Behavior

When a timeout occurs during streaming:

1. A stderr event is emitted with "EXECUTION TIMED OUT"
2. The process is killed inside the container
3. An exit event is emitted with code "1"
4. The stream ends