Interactive stdio

This cookbook demonstrates the full stdio API surface through six self-contained demos. Each one starts a process with an open stdin pipe, sends data, and reads the response.

What you’ll learn

Sending stdin and receiving stdout via sandbox.stdio.start(cmd)
Separate on_stdout and on_stderr callbacks
Multi-round interactive conversations (read-echo loop)
Iterator / stream protocol for consuming output
Closing stdin to signal EOF (proc.close_stdin())
Custom environment variables and working directory
Killing a long-running process (proc.kill())

Prerequisites

export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="your-declaw-instance.example.com:8080"

Install the SDK:

Python
TypeScript
Go

pip install declaw

npm install @declaw/sdk

go get github.com/declaw-ai/declaw-go

1. Basic echo (cat)

Start cat, send a line, close stdin, and read the echoed output.

Python
TypeScript
Go

from declaw import Sandbox

sbx = Sandbox.create(timeout=300)
chunks = []
proc = sbx.stdio.start("cat", on_stdout=lambda d: chunks.append(d))
proc.send_stdin("hello from stdio!\n")
proc.close_stdin()
result = proc.wait(timeout=10)
print(b"".join(chunks).decode().strip())  # "hello from stdio!"
print(result.exit_code)                    # 0

import { Sandbox } from "@declaw/sdk";

const sbx = await Sandbox.create({ timeout: 300 });
const chunks: Uint8Array[] = [];
const proc = await sbx.stdio.start("cat", {
  onStdout: (d) => chunks.push(d),
});
await proc.sendStdin("hello from stdio!\n");
await proc.closeStdin();
const result = await proc.wait();

sbx, _ := declaw.Create(ctx, declaw.WithTimeout(300))
handle, _ := sbx.Stdio.Start(ctx, "cat", nil)
handle.SendStdin(ctx, []byte("hello from stdio!\n"))
handle.CloseStdin(ctx)
var output []byte
result, _ := handle.Stream(ctx, &declaw.StdioStreamOpts{
    OnStdout: func(data []byte) { output = append(output, data...) },
})

2. Stdout and stderr callbacks

Receive stdout and stderr on separate callbacks.

Python
TypeScript
Go

out, err = [], []
proc = sbx.stdio.start(
    "sh -c 'echo this-is-stdout; echo this-is-stderr >&2'",
    on_stdout=lambda d: out.append(d),
    on_stderr=lambda d: err.append(d),
)
result = proc.wait(timeout=10)
print(b"".join(out).decode().strip())  # "this-is-stdout"
print(b"".join(err).decode().strip())  # "this-is-stderr"

const out: Uint8Array[] = [];
const err: Uint8Array[] = [];
const proc = await sbx.stdio.start(
  "sh -c 'echo this-is-stdout; echo this-is-stderr >&2'",
  {
    onStdout: (d) => out.push(d),
    onStderr: (d) => err.push(d),
  },
);
await proc.wait();

handle, _ := sbx.Stdio.Start(ctx,
    "sh -c 'echo this-is-stdout; echo this-is-stderr >&2'", nil)
var stdout, stderr []byte
handle.Stream(ctx, &declaw.StdioStreamOpts{
    OnStdout: func(d []byte) { stdout = append(stdout, d...) },
    OnStderr: func(d []byte) { stderr = append(stderr, d...) },
})

3. Multi-round interactive conversation

Send multiple lines to a process that reads in a loop.

Python
TypeScript
Go

replies = []
proc = sbx.stdio.start(
    "sh -c 'while read line; do echo \"reply: $line\"; done'",
    on_stdout=lambda d: replies.append(d),
)
for i in range(5):
    proc.send_stdin(f"message {i}\n")
proc.close_stdin()
proc.wait(timeout=10)
# reply: message 0 ... reply: message 4

const replies: Uint8Array[] = [];
const proc = await sbx.stdio.start(
  "sh -c 'while read line; do echo \"reply: $line\"; done'",
  { onStdout: (d) => replies.push(d) },
);
for (let i = 0; i < 5; i++) {
  await proc.sendStdin(`message ${i}\n`);
}
await proc.closeStdin();
await proc.wait();

handle, _ := sbx.Stdio.Start(ctx,
    `sh -c 'while read line; do echo "reply: $line"; done'`, nil)
for i := 0; i < 5; i++ {
    handle.SendStdin(ctx, []byte(fmt.Sprintf("message %d\n", i)))
}
handle.CloseStdin(ctx)
handle.Wait(ctx)

4. Line counting with EOF

Send lines to wc -l and close stdin so it sees EOF and reports.

Python
TypeScript
Go

out = []
proc = sbx.stdio.start("wc -l", on_stdout=lambda d: out.append(d))
proc.send_stdin("line one\nline two\nline three\n")
proc.close_stdin()
result = proc.wait(timeout=10)
print(b"".join(out).decode().strip())  # "3"

const out: Uint8Array[] = [];
const proc = await sbx.stdio.start("wc -l", {
  onStdout: (d) => out.push(d),
});
await proc.sendStdin("line one\nline two\nline three\n");
await proc.closeStdin();
await proc.wait();

handle, _ := sbx.Stdio.Start(ctx, "wc -l", nil)
handle.SendStdin(ctx, []byte("line one\nline two\nline three\n"))
handle.CloseStdin(ctx)
var count []byte
handle.Stream(ctx, &declaw.StdioStreamOpts{
    OnStdout: func(d []byte) { count = append(count, d...) },
})

5. Environment variables and working directory

Pass env vars and set the working directory.

Python
TypeScript
Go

out = []
proc = sbx.stdio.start(
    "sh -c 'echo $GREETING from $(pwd)'",
    envs={"GREETING": "hello-env"},
    cwd="/tmp",
    on_stdout=lambda d: out.append(d),
)
proc.wait(timeout=10)
print(b"".join(out).decode().strip())  # "hello-env from /tmp"

const out: Uint8Array[] = [];
const proc = await sbx.stdio.start(
  "sh -c 'echo $GREETING from $(pwd)'",
  {
    envs: { GREETING: "hello-env" },
    cwd: "/tmp",
    onStdout: (d) => out.push(d),
  },
);
await proc.wait();

handle, _ := sbx.Stdio.Start(ctx,
    "sh -c 'echo $GREETING from $(pwd)'",
    &declaw.StdioStartOpts{
        Envs: map[string]string{"GREETING": "hello-env"},
        Cwd:  "/tmp",
    })
handle.Wait(ctx)

6. Kill a long-running process

Start a process, wait briefly, kill it, and read the exit code.

Python
TypeScript
Go

import time

proc = sbx.stdio.start("sleep 300")
time.sleep(1)
killed = proc.kill()          # True
result = proc.wait(timeout=10)
print(result.exit_code)       # -1

const proc = await sbx.stdio.start("sleep 300");
await new Promise((r) => setTimeout(r, 1000));
const killed = await proc.kill();   // true
const result = await proc.wait();
console.log(result.exitCode);       // -1

handle, _ := sbx.Stdio.Start(ctx, "sleep 300", nil)
time.Sleep(time.Second)
handle.Kill(ctx)
result, _ := handle.Wait(ctx)
fmt.Println(result.ExitCode)  // -1

Full runnable examples

Complete self-contained scripts with all six demos and cleanup are available in the SDK repositories. Install the SDK (pip install declaw or npm install @declaw/sdk) and run the example directly.

Getting Started

Built-in Templates

Commands

PTY

OpenAI Agents

Filesystem

Volumes

Network Policies

PII Protection

Security Features

LLM Providers

Framework Integrations

Agent-in-Sandbox

Real-World Patterns

Security Demos

Interactive stdio

What you’ll learn

Prerequisites

1. Basic echo (cat)

2. Stdout and stderr callbacks

3. Multi-round interactive conversation

4. Line counting with EOF

5. Environment variables and working directory

6. Kill a long-running process

Full runnable examples

​What you’ll learn

​Prerequisites

​1. Basic echo (cat)

​2. Stdout and stderr callbacks

​3. Multi-round interactive conversation

​4. Line counting with EOF

​5. Environment variables and working directory

​6. Kill a long-running process

​Full runnable examples

What you’ll learn

Prerequisites

1. Basic echo (cat)

2. Stdout and stderr callbacks

3. Multi-round interactive conversation

4. Line counting with EOF

5. Environment variables and working directory

6. Kill a long-running process

Full runnable examples