> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stdio

> TypeScript SDK reference for sandbox.stdio — start interactive subprocesses with bidirectional stdin/stdout/stderr.

The TypeScript SDK exposes stdio through `sandbox.stdio`. Use
`stdio.start()` to launch a process with an open stdin pipe, then
send data, receive output, and close stdin or kill the process.

For conceptual background see the
[Stdio feature overview](/features/stdio).

## `sandbox.stdio.start(cmd, opts?)` → `Promise<StdioProcess>`

Start a subprocess with an open stdin pipe.

```typescript theme={null}
const proc = await sandbox.stdio.start("cat", {
  envs: { FOO: "bar" },
  user: "user",
  cwd: "/workspace",
  onStdout: (data) => console.log(data),
  onStderr: (data) => console.error(data),
  requestTimeout: 5000,
});
```

### `StdioStartOpts`

| Field            | Type                         | Default     | Description                                                                               |
| ---------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `envs`           | `Record<string, string>`     | `undefined` | Environment variables merged into the process env.                                        |
| `user`           | `string`                     | `"user"`    | User the process runs as.                                                                 |
| `cwd`            | `string`                     | `undefined` | Working directory.                                                                        |
| `onStdout`       | `(data: Uint8Array) => void` | `undefined` | If provided, the handle auto-opens the SSE stream and invokes this for each stdout chunk. |
| `onStderr`       | `(data: Uint8Array) => void` | `undefined` | Same, for stderr.                                                                         |
| `requestTimeout` | `number`                     | `undefined` | Per-request timeout in milliseconds for the start POST.                                   |

## `StdioProcess`

Handle for an interactive subprocess with stdin pipe.

### Properties

* `proc.cmdId: string` — server-assigned command identifier.
* `proc.exitCode: number | null` — `null` while the process is running.

### Methods

#### `proc.sendStdin(data, requestTimeout?): Promise<void>`

Send data to the process's stdin. Accepts `string` or `Uint8Array`.

```typescript theme={null}
await proc.sendStdin("hello\n");
await proc.sendStdin(new Uint8Array([0x04]));  // Ctrl-D
```

#### `proc.closeStdin(requestTimeout?): Promise<void>`

Close the process's stdin pipe, sending EOF.

#### `proc.kill(requestTimeout?): Promise<boolean>`

Terminate the process. Returns `true` if the process existed at the
time of the call.

#### `proc.wait(): Promise<StdioResult>`

Resolves when the process exits. If callbacks were provided at start
time, this awaits the background stream. Otherwise it opens a new
stream and drains it (discarding output).

```typescript theme={null}
const result = await proc.wait();
console.log(result.exitCode);
```

#### `proc.stream(opts?): Promise<StdioResult>`

Opens the SSE output stream and delivers chunks via callbacks. Resolves
when the process exits.

```typescript theme={null}
const proc = await sandbox.stdio.start("sh -c 'echo hi; echo err >&2'");
const result = await proc.stream({
  onStdout: (d) => console.log("out:", new TextDecoder().decode(d)),
  onStderr: (d) => console.log("err:", new TextDecoder().decode(d)),
});
```

Use `stream()` when you didn't provide callbacks at start time.

## `StdioResult`

```typescript theme={null}
interface StdioResult {
  exitCode: number;  // -1 if the stream ended without a clean exit frame
}
```