--- title: Execution description: TypeScript SDK - Command execution API reference --- Run commands inside a running sandbox: collect output in one shot, stream it as it arrives, attach an interactive PTY, or pipe data to stdin. These methods live on a running [`Sandbox`](/sdk/typescript/sandbox). See [Commands](/sandboxes/commands) for usage examples.

Run & collect4

sandbox.exec()run, buffer output sandbox.execWith()run with per-call overrides sandbox.shell()run through the shell sandbox.attachShell()attach the default shell

Stream & attach5

sandbox.execStream()stream events live sandbox.execStreamWith()stream with overrides sandbox.shellStream()stream through the shell sandbox.attach()interactive PTY bridge sandbox.attachWith()attach with overrides

Builder · ExecOptionsBuilder13

.arg() .args() .cwd() .user() .env() .envs() .timeout() .stdinPipe() .stdinBytes() .tty() + 3 more in the Types section

Builder · AttachOptionsBuilder9

.arg() .args() .cwd() .user() .env() .envs() .detachKeys() .rlimit() .rlimitRange()

Types

ExecOutput ExecHandle ExecSink ExecEvent ExitStatus ExecOptionsBuilder AttachOptionsBuilder Stdin StdinMode Rlimit RlimitResource

Typical flow

```typescript import { Sandbox } from "microsandbox"; const sandbox = await Sandbox.create("api", { image: "python" }); // 1. one-shot const out = await sandbox.exec("python3", ["-c", "print(1 + 1)"]); console.log(out.stdout()); // "2\n" // 2. stream const handle = await sandbox.execStream("tail", ["-f", "/var/log/app.log"]); for await (const event of handle) { if (event.kind === "stdout") process.stdout.write(event.data); if (event.kind === "exited") break; } await sandbox.stop(); ``` ## Run and collect --- #### sandbox.exec()
instanceasync
```typescript exec(cmd: string, args?: Iterable): Promise ``` Run a command inside the sandbox and wait for it to complete. Collects all stdout and stderr into memory and returns them along with the exit code. For long-running processes or large output, use [`execStream()`](#sandbox-execstream) instead.

Parameters

cmdstring
Command to execute (e.g. "python3", "/usr/bin/node").
args?Iterable<string>
Command arguments (e.g. ["-c", "print('hello')"]).

Returns

Promise<ExecOutput>
Collected stdout, stderr, and exit status.
```typescript const result = await sandbox.exec("python3", ["-c", "print(1 + 1)"]); console.log(result.stdout()); // "2\n" console.log(result.code); // 0 ``` --- #### sandbox.execWith()
instanceasync
```typescript execWith( cmd: string, configure: (b: ExecOptionsBuilder) => ExecOptionsBuilder, ): Promise ``` Run a command with per-execution overrides. Configure working directory, environment variables, timeout, stdin, TTY allocation, and rlimits via the builder callback. These overrides apply only to this execution and don't change the sandbox's defaults.

Parameters

cmdstring
Command to execute.
Builder callback for per-call overrides.

Returns

Collected stdout, stderr, and exit status.
```typescript const out = await sandbox.execWith("python3", (e) => e.args(["script.py"]) .cwd("/app") .env("PYTHONPATH", "/app/lib") .timeout(30_000), ); ``` --- #### sandbox.shell()
instanceasync
```typescript shell(script: string): Promise ``` Run a command through the sandbox's configured shell (defaults to `/bin/sh`). Shell syntax like pipes, redirects, and `&&` chains works.

Parameters

scriptstring
Shell command string (e.g. "ls -la /app && echo done").

Returns

Collected stdout, stderr, and exit status.
```typescript const out = await sandbox.shell("ls -la /app && echo done"); console.log(out.stdout()); ``` --- #### sandbox.attachShell()
instanceasync
```typescript attachShell(): Promise ``` Bridge your terminal to the sandbox's default shell in a fully interactive PTY session.

Returns

Promise<number>
Exit code of the shell process.
```typescript const code = await sandbox.attachShell(); ``` --- ## Stream and attach --- #### sandbox.execStream()
instanceasync
```typescript execStream(cmd: string, args?: Iterable): Promise ``` Run a command with streaming output. Returns a handle that emits stdout, stderr, and exit events as they happen, rather than buffering everything.

Parameters

cmdstring
Command to execute.
args?Iterable<string>
Command arguments.

Returns

Streaming handle for receiving events and controlling the process.
```typescript const handle = await sandbox.execStream("tail", ["-f", "/var/log/app.log"]); for await (const event of handle) { if (event.kind === "stdout") process.stdout.write(event.data); if (event.kind === "exited") break; } ``` --- #### sandbox.execStreamWith()
instanceasync
```typescript execStreamWith( cmd: string, configure: (b: ExecOptionsBuilder) => ExecOptionsBuilder, ): Promise ``` Streaming variant of [`execWith()`](#sandbox-execwith): same configuration via [`ExecOptionsBuilder`](#execoptionsbuilder), but returns an [`ExecHandle`](#exechandle) instead of buffering output.

Parameters

cmdstring
Command to execute.
Builder callback for per-call overrides.

Returns

Streaming handle.
```typescript const handle = await sandbox.execStreamWith("python3", (e) => e.args(["-u", "worker.py"]).env("LEVEL", "debug").stdinPipe(), ); const stdin = await handle.takeStdin(); await stdin?.write("task-1\n"); ``` --- #### sandbox.shellStream()
instanceasync
```typescript shellStream(script: string): Promise ``` Run a shell command with streaming output.

Parameters

scriptstring
Shell command string.

Returns

Streaming handle.
```typescript const handle = await sandbox.shellStream("for i in 1 2 3; do echo $i; sleep 1; done"); for await (const event of handle) { if (event.kind === "stdout") process.stdout.write(event.data); } ``` --- #### sandbox.attach()
instanceasync
```typescript attach(cmd: string, args?: Iterable): Promise ``` Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Press `Ctrl+]` (or configured detach keys) to disconnect without stopping the process.

Parameters

cmdstring
Command to run.
args?Iterable<string>
Command arguments.

Returns

Promise<number>
Exit code of the process.
```typescript const code = await sandbox.attach("python3"); ``` --- #### sandbox.attachWith()
instanceasync
```typescript attachWith( cmd: string, configure: (b: AttachOptionsBuilder) => AttachOptionsBuilder, ): Promise ``` Interactive PTY attach with options for arguments, environment variables, working directory, user, custom detach keys, and rlimits. Configure via the builder callback.

Parameters

cmdstring
Command to run.
Builder callback for the attach session.

Returns

Promise<number>
Exit code of the process.
```typescript const code = await sandbox.attachWith("bash", (a) => a.cwd("/app") .env("EDITOR", "vim") .detachKeys("ctrl-]"), ); ``` --- ## Types ### ExecOutput
class

Returned by exec() · execWith() · shell() · ExecHandle.collect()

The result of a completed command execution: collected output plus exit status. | Property / Method | Type | Description | |-------------------|------|-------------| | `code` | `number` (getter) | Process exit code | | `success` | `boolean` (getter) | `true` when `code === 0` | | `status` | [`ExitStatus`](#exitstatus) (getter) | Exit status object | | `stdout()` | `string` | Collected stdout decoded as UTF-8 (lossy on invalid sequences) | | `stderr()` | `string` | Collected stderr decoded as UTF-8 (lossy on invalid sequences) | | `stdoutBytes()` | `Uint8Array` | Raw stdout bytes | | `stderrBytes()` | `Uint8Array` | Raw stderr bytes | ### ExecHandle
class

Returned by execStream() · execStreamWith() · shellStream()

A handle to a running streaming execution. Implements `AsyncIterable` and `AsyncDisposable`, so it works with `for await...of` and `await using`. | Property / Method | Type | Description | |-------------------|------|-------------| | `recv()` | `Promise<`[`ExecEvent`](#execevent)` \| null>` | Receive the next event, or `null` once the stream ends | | `takeStdin()` | `Promise<`[`ExecSink`](#execsink)` \| null>` | Take ownership of the stdin sink. Returns `null` after the first call | | `wait()` | `Promise<`[`ExitStatus`](#exitstatus)`>` | Wait for the process to exit | | `collect()` | `Promise<`[`ExecOutput`](#execoutput)`>` | Drain stdout/stderr and wait for exit | | `signal(signal)` | `Promise` | Send a POSIX signal (numeric) to the process | | `kill()` | `Promise` | Force-terminate the process | | `[Symbol.asyncIterator]()` | `AsyncIterator<`[`ExecEvent`](#execevent)`>` | Iterate events with `for await...of` | | `[Symbol.asyncDispose]()` | `Promise` | Best-effort kill on `await using` scope exit | ### ExecSink
class

Returned by ExecHandle.takeStdin()

Writer for sending data to a running process's stdin. Implements `AsyncDisposable`. Obtained from [`ExecHandle.takeStdin()`](#exechandle) when the execution was configured with [`.stdinPipe()`](#execoptionsbuilder). | Method | Type | Description | |--------|------|-------------| | `write(data)` | `(data: Uint8Array \| string) => Promise` | Write bytes to the process's stdin. Strings are UTF-8 encoded | | `close()` | `() => Promise` | Send EOF. Idempotent | | `[Symbol.asyncDispose]()` | `() => Promise` | Calls `close()` on `await using` scope exit | ### ExecEvent
union

Emitted by ExecHandle

Discriminated union emitted while iterating an [`ExecHandle`](#exechandle). The discriminator is `kind`. ```typescript type ExecEvent = | { kind: "started"; pid: number } | { kind: "stdout"; data: Uint8Array } | { kind: "stderr"; data: Uint8Array } | { kind: "exited"; code: number }; ``` | `kind` | Payload | Description | |--------|---------|-------------| | `"started"` | `pid: number` | The process has started | | `"stdout"` | `data: Uint8Array` | A chunk of stdout data | | `"stderr"` | `data: Uint8Array` | A chunk of stderr data | | `"exited"` | `code: number` | The process has exited | ### ExitStatus
interface

Returned by ExecHandle.wait() · ExecOutput.status

The exit result of a process. | Field | Type | Description | |-------|------|-------------| | code | `number` | Process exit code | | success | `boolean` | `true` when `code === 0` | ### ExecOptionsBuilder
class

Used by execWith() · execStreamWith()

Fluent builder passed to the callback in `execWith(cmd, b => ...)` and `execStreamWith(cmd, b => ...)`. Every setter mutates the builder and returns it, so calls chain. | Method | Type | Description | |--------|------|-------------| | `arg(arg)` | `(arg: string) => this` | Append a single argument | | `args(args)` | `(args: string[]) => this` | Append many arguments | | `cwd(cwd)` | `(cwd: string) => this` | Working directory | | `user(user)` | `(user: string) => this` | Guest user | | `env(key, value)` | `(key: string, value: string) => this` | Add a single env var | | `envs(vars)` | `(vars: Record) => this` | Add many env vars | | `timeout(ms)` | `(ms: number) => this` | Kill the process after this many milliseconds | | `stdinNull()` | `() => this` | Connect stdin to `/dev/null` (default) | | `stdinPipe()` | `() => this` | Open a writable stdin pipe; read it back with [`ExecHandle.takeStdin()`](#exechandle) | | `stdinBytes(data)` | `(data: Buffer) => this` | Pre-supply stdin bytes and close it | | `tty(enabled)` | `(enabled: boolean) => this` | Allocate a pseudo-terminal | | `rlimit(resource, limit)` | `(resource: `[`RlimitResource`](#rlimitresource)`, limit: number) => this` | Set both soft and hard rlimit | | `rlimitRange(resource, soft, hard)` | `(resource: `[`RlimitResource`](#rlimitresource)`, soft: number, hard: number) => this` | Set distinct soft and hard rlimits | ### AttachOptionsBuilder
class

Used by attachWith()

Fluent builder passed to the callback in `attachWith(cmd, b => ...)`. Every setter mutates the builder and returns it, so calls chain. | Method | Type | Description | |--------|------|-------------| | `arg(arg)` | `(arg: string) => this` | Append a single argument | | `args(args)` | `(args: string[]) => this` | Append many arguments | | `cwd(cwd)` | `(cwd: string) => this` | Working directory | | `user(user)` | `(user: string) => this` | Guest user | | `env(key, value)` | `(key: string, value: string) => this` | Add a single env var | | `envs(vars)` | `(vars: Record) => this` | Add many env vars | | `detachKeys(spec)` | `(spec: string) => this` | Detach key sequence (e.g. `"ctrl-]"` or `"ctrl-p,ctrl-q"`) | | `rlimit(resource, limit)` | `(resource: `[`RlimitResource`](#rlimitresource)`, limit: number) => this` | Set both soft and hard rlimit | | `rlimitRange(resource, soft, hard)` | `(resource: `[`RlimitResource`](#rlimitresource)`, soft: number, hard: number) => this` | Set distinct soft and hard rlimits | ### Stdin
const

Produces StdinMode

Helper factory for constructing a [`StdinMode`](#stdinmode). Equivalent to the `stdinNull` / `stdinPipe` / `stdinBytes` setters on [`ExecOptionsBuilder`](#execoptionsbuilder). | Method | Type | Description | |--------|------|-------------| | `Stdin.null()` | `() => `[`StdinMode`](#stdinmode) | Connect stdin to `/dev/null` | | `Stdin.pipe()` | `() => `[`StdinMode`](#stdinmode) | Open a writable pipe; caller writes via [`ExecHandle.takeStdin()`](#exechandle) | | `Stdin.bytes(data)` | `(data: Uint8Array \| string) => `[`StdinMode`](#stdinmode) | Send the given bytes (or UTF-8-encoded string) and close stdin | ### StdinMode
union

Produced by Stdin

Discriminated union describing stdin behavior for an execution. ```typescript type StdinMode = | { kind: "null" } | { kind: "pipe" } | { kind: "bytes"; data: Uint8Array }; ``` | `kind` | Payload | Description | |--------|---------|-------------| | `"null"` | - | Stdin connected to `/dev/null` | | `"pipe"` | - | Writable pipe opened for the caller | | `"bytes"` | `data: Uint8Array` | Pre-supplied stdin bytes, then EOF | ### Rlimit
interface

Set via ExecOptionsBuilder.rlimit() · AttachOptionsBuilder.rlimit()

A POSIX resource limit applied to the process. | Field | Type | Description | |-------|------|-------------| | resource | [`RlimitResource`](#rlimitresource) | Which resource is limited | | soft | `number` | Soft limit | | hard | `number` | Hard limit | ### RlimitResource
union

Used by Rlimit.resource · rlimit() · rlimit()

String union naming a limitable POSIX resource. ```typescript type RlimitResource = | "cpu" | "fsize" | "data" | "stack" | "core" | "rss" | "nproc" | "nofile" | "memlock" | "as" | "locks" | "sigpending" | "msgqueue" | "nice" | "rtprio" | "rttime"; ```