Execution

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. See Commands for usage examples.

Typical flow

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()

exec(cmd: string, args?: Iterable<string>): Promise<ExecOutput>

Example

const result = await sandbox.exec("python3", ["-c", "print(1 + 1)"]);
console.log(result.stdout()); // "2\n"
console.log(result.code);     // 0

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() 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.

sandbox.execWith()

execWith(
  cmd: string,
  configure: (b: ExecOptionsBuilder) => ExecOptionsBuilder,
): Promise<ExecOutput>

Example

const out = await sandbox.execWith("python3", (e) =>
  e.args(["script.py"])
    .cwd("/app")
    .env("PYTHONPATH", "/app/lib")
    .timeout(30_000),
);

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.

configure(b: ExecOptionsBuilder) => ExecOptionsBuilder

Builder callback for per-call overrides.

Returns

Promise<ExecOutput>

Collected stdout, stderr, and exit status.

sandbox.shell()

shell(script: string): Promise<ExecOutput>

Example

const out = await sandbox.shell("ls -la /app && echo done");
console.log(out.stdout());

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

Promise<ExecOutput>

Collected stdout, stderr, and exit status.

sandbox.attachShell()

attachShell(): Promise<number>

Example

const code = await sandbox.attachShell();

Bridge your terminal to the sandbox’s default shell in a fully interactive PTY session.

Returns

Promise<number>

Exit code of the shell process.

Stream and attach

sandbox.execStream()

execStream(cmd: string, args?: Iterable<string>): Promise<ExecHandle>

Example

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;
}

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

Promise<ExecHandle>

Streaming handle for receiving events and controlling the process.

sandbox.execStreamWith()

execStreamWith(
  cmd: string,
  configure: (b: ExecOptionsBuilder) => ExecOptionsBuilder,
): Promise<ExecHandle>

Example

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");

Streaming variant of execWith(): same configuration via ExecOptionsBuilder, but returns an ExecHandle instead of buffering output. For sessions configured with .tty(true), call resize(rows, cols) when the terminal dimensions change.

Parameters

cmdstring

Command to execute.

configure(b: ExecOptionsBuilder) => ExecOptionsBuilder

Builder callback for per-call overrides.

Returns

Promise<ExecHandle>

Streaming handle.

sandbox.shellStream()

shellStream(script: string): Promise<ExecHandle>

Example

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);
}

Run a shell command with streaming output.

Parameters

scriptstring

Shell command string.

Returns

Promise<ExecHandle>

Streaming handle.

sandbox.attach()

attach(cmd: string, args?: Iterable<string>): Promise<number>

Example

const code = await sandbox.attach("python3");

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.

sandbox.attachWith()

attachWith(
  cmd: string,
  configure: (b: AttachOptionsBuilder) => AttachOptionsBuilder,
): Promise<number>

Example

const code = await sandbox.attachWith("bash", (a) =>
  a.cwd("/app")
    .env("EDITOR", "vim")
    .detachKeys("ctrl-]"),
);

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.

configure(b: AttachOptionsBuilder) => AttachOptionsBuilder

Builder callback for the attach session.

Returns

Promise<number>

Exit code of the process.

Types

ExecOutput

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

The result of a completed command execution: collected output plus exit status. In TTY mode, stdoutBytes() contains the combined terminal output and stderrBytes() is empty because a PTY doesn’t preserve separate stdout and stderr streams.

Property / Method	Type	Description
`code`	`number` (getter)	Process exit code
`success`	`boolean` (getter)	`true` when `code === 0`
`status`	`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

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

A handle to a running streaming execution. Implements AsyncIterable<ExecEvent> and AsyncDisposable, so it works with for await...of and await using. signal(), kill(), and resize() may run while another task is waiting in recv(); concurrent receive, wait, and collect operations are not supported.

Property / Method	Type	Description
`recv()`	`Promise<ExecEvent` `\| null>`	Receive the next event, or `null` once the stream ends
`takeStdin()`	`Promise<ExecSink` `\| null>`	Take ownership of the stdin sink. Returns `null` after the first call
`wait()`	`Promise<ExitStatus>`	Wait for the process to exit
`collect()`	`Promise<ExecOutput>`	Drain stdout/stderr and wait for exit
`signal(signal)`	`Promise<void>`	Send a POSIX signal (numeric) to the process
`kill()`	`Promise<void>`	Force-terminate the process
`resize(rows, cols)`	`Promise<void>`	Resize the PTY to the given unsigned 16-bit dimensions
`[Symbol.asyncIterator]()`	`AsyncIterator<ExecEvent>`	Iterate events with `for await...of`
`[Symbol.asyncDispose]()`	`Promise<void>`	Best-effort kill on `await using` scope exit

ExecSink

Returned by ExecHandle.takeStdin()

Writer for sending data to a running process’s stdin. Implements AsyncDisposable. Obtained from ExecHandle.takeStdin() when the execution was configured with .stdinPipe().

Method	Type	Description
`write(data)`	`(data: Uint8Array \| string) => Promise<void>`	Write bytes to the process’s stdin. Strings are UTF-8 encoded
`close()`	`() => Promise<void>`	Close the sink. Sends EOF in non-TTY pipe mode; the guest PTY remains open in TTY mode
`[Symbol.asyncDispose]()`	`() => Promise<void>`	Calls `close()` on `await using` scope exit

ExecEvent

Emitted by ExecHandle

Discriminated union emitted while iterating an ExecHandle. The discriminator is kind.

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

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

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<string, string>) => 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()`
`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, limit: number) => this`	Set both soft and hard rlimit
`rlimitRange(resource, soft, hard)`	`(resource:` `RlimitResource, soft: number, hard: number) => this`	Set distinct soft and hard rlimits

AttachOptionsBuilder

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<string, string>) => 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, limit: number) => this`	Set both soft and hard rlimit
`rlimitRange(resource, soft, hard)`	`(resource:` `RlimitResource, soft: number, hard: number) => this`	Set distinct soft and hard rlimits

Stdin

Produces StdinMode

Helper factory for constructing a StdinMode. Equivalent to the stdinNull / stdinPipe / stdinBytes setters on ExecOptionsBuilder.

Method	Type	Description
`Stdin.null()`	`() =>` `StdinMode`	Connect stdin to `/dev/null`
`Stdin.pipe()`	`() =>` `StdinMode`	Open a writable pipe; caller writes via `ExecHandle.takeStdin()`
`Stdin.bytes(data)`	`(data: Uint8Array \| string) =>` `StdinMode`	Send the given bytes (or UTF-8-encoded string) and close stdin

StdinMode

Produced by Stdin

Discriminated union describing stdin behavior for an execution.

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

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

A POSIX resource limit applied to the process.

Field	Type	Description
resource	`RlimitResource`	Which resource is limited
soft	`number`	Soft limit
hard	`number`	Hard limit

RlimitResource

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

String union naming a limitable POSIX resource.

type RlimitResource =
  | "cpu" | "fsize" | "data" | "stack" | "core" | "rss"
  | "nproc" | "nofile" | "memlock" | "as" | "locks"
  | "sigpending" | "msgqueue" | "nice" | "rtprio" | "rttime";

Getting Started

SDKs

CLI

Run and collect

sandbox.exec()

sandbox.execWith()

sandbox.shell()

sandbox.attachShell()

Stream and attach

sandbox.execStream()

sandbox.execStreamWith()

sandbox.shellStream()

sandbox.attach()

sandbox.attachWith()

Types

ExecOutput

ExecHandle

ExecSink

ExecEvent

ExitStatus

ExecOptionsBuilder

AttachOptionsBuilder

Stdin

StdinMode

Rlimit

RlimitResource

​Run and collect

​sandbox.exec()

​sandbox.execWith()

​sandbox.shell()

​sandbox.attachShell()

​Stream and attach

​sandbox.execStream()

​sandbox.execStreamWith()

​sandbox.shellStream()

​sandbox.attach()

​sandbox.attachWith()

​Types

​ExecOutput

​ExecHandle

​ExecSink

​ExecEvent

​ExitStatus

​ExecOptionsBuilder

​AttachOptionsBuilder

​Stdin

​StdinMode

​Rlimit

​RlimitResource

Run and collect

sandbox.exec()

sandbox.execWith()

sandbox.shell()

sandbox.attachShell()

Stream and attach

sandbox.execStream()

sandbox.execStreamWith()

sandbox.shellStream()

sandbox.attach()

sandbox.attachWith()

Types

ExecOutput

ExecHandle

ExecSink

ExecEvent

ExitStatus

ExecOptionsBuilder

AttachOptionsBuilder

Stdin

StdinMode

Rlimit

RlimitResource