Execution - microsandbox

Run commands inside a running sandbox. See Commands for usage examples.

Sandbox

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.

ExecOutput

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

Collected output and exit status.

output.code

number (getter) Process exit code

output.success

boolean (getter) true when code === 0

output.status

ExitStatus (getter) Exit status object

output.stdout()

stdout()

Collected stdout decoded as UTF-8 (lossy on invalid sequences)

Returns

string

output.stderr()

stderr()

Collected stderr decoded as UTF-8 (lossy on invalid sequences)

Returns

string

output.stdoutBytes()

stdoutBytes()

Raw stdout bytes

Returns

Uint8Array

output.stderrBytes()

stderrBytes()

Raw stderr bytes

Returns

Uint8Array

ExecHandle

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

A handle to a running streaming execution and its events.

handle.recv()

recv()

Receive the next event, or null once the stream ends

Returns

Promise<ExecEvent \| null>

handle.takeStdin()

takeStdin()

Take ownership of the stdin sink. Returns null after the first call

Returns

Promise<ExecSink \| null>

handle.wait()

wait()

Wait for the process to exit

Returns

Promise<ExitStatus>

handle.collect()

collect()

Drain stdout/stderr and wait for exit

Returns

Promise<ExecOutput>

handle.signal()

signal(signal)

Send a POSIX signal (numeric) to the process

Returns

Promise<void>

handle.kill()

kill()

Force-terminate the process

Returns

Promise<void>

handle.resize()

resize(rows, cols)

Resize the PTY to the given unsigned 16-bit dimensions

Returns

Promise<void>

handle.Symbol.asyncIterator

[Symbol.asyncIterator]()

Iterate events with for await...of

Returns

AsyncIterator<ExecEvent>

handle.Symbol.asyncDispose

[Symbol.asyncDispose]()

Best-effort kill on await using scope exit

Returns

Promise<void>

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

sink.write()

write(data)

Write bytes to the process’s stdin. Strings are UTF-8 encoded

Returns

(data: Uint8Array \| string) => Promise<void>

sink.close()

close()

Close the sink. Sends EOF in non-TTY pipe mode; the guest PTY remains open in TTY mode

Returns

() => Promise<void>

sink.Symbol.asyncDispose

[Symbol.asyncDispose]()

Calls close() on await using scope exit

Returns

Promise<void>

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.

execOptions.arg()

arg(arg)

Append a single argument

Returns

(arg: string) => this

execOptions.args()

args(args)

Append many arguments

Returns

(args: string[]) => this

execOptions.cwd()

cwd(cwd)

Working directory

Returns

(cwd: string) => this

execOptions.user()

user(user)

Guest user

Returns

(user: string) => this

execOptions.env()

env(key, value)

Add a single env var

Returns

(key: string, value: string) => this

execOptions.envs()

envs(vars)

Add many env vars

Returns

(vars: Record<string, string>) => this

execOptions.timeout()

timeout(ms)

Kill the process after this many milliseconds

Returns

(ms: number) => this

execOptions.stdinNull()

stdinNull()

Connect stdin to /dev/null (default)

Returns

() => this

execOptions.stdinPipe()

stdinPipe()

Open a writable stdin pipe; read it back with ExecHandle.takeStdin()

Returns

() => this

execOptions.stdinBytes()

stdinBytes(data)

Pre-supply stdin bytes and close it

Returns

(data: Buffer) => this

execOptions.tty()

tty(enabled)

Allocate a pseudo-terminal

Returns

(enabled: boolean) => this

execOptions.rlimit()

rlimit(resource, limit)

Set both soft and hard rlimit

Returns

(resource: RlimitResource, limit: number) => this

execOptions.rlimitRange()

rlimitRange(resource, soft, hard)

Set distinct soft and hard rlimits

Returns

(resource: RlimitResource, soft: number, hard: number) => this

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.

attachOptions.arg()

arg(arg)

Append a single argument

Returns

(arg: string) => this

attachOptions.args()

args(args)

Append many arguments

Returns

(args: string[]) => this

attachOptions.cwd()

cwd(cwd)

Working directory

Returns

(cwd: string) => this

attachOptions.user()

user(user)

Guest user

Returns

(user: string) => this

attachOptions.env()

env(key, value)

Add a single env var

Returns

(key: string, value: string) => this

attachOptions.envs()

envs(vars)

Add many env vars

Returns

(vars: Record<string, string>) => this

attachOptions.detachKeys()

detachKeys(spec)

Detach key sequence (e.g. "ctrl-]" or "ctrl-p,ctrl-q")

Returns

(spec: string) => this

attachOptions.rlimit()

rlimit(resource, limit)

Set both soft and hard rlimit

Returns

(resource: RlimitResource, limit: number) => this

attachOptions.rlimitRange()

rlimitRange(resource, soft, hard)

Set distinct soft and hard rlimits

Returns

(resource: RlimitResource, soft: number, hard: number) => this

Stdin

Produces StdinMode

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

Stdin.null()

Stdin.null()

Connect stdin to /dev/null

Returns

() => StdinMode

Stdin.pipe()

Stdin.pipe()

Open a writable pipe; caller writes via ExecHandle.takeStdin()

Returns

() => StdinMode

Stdin.bytes()

Stdin.bytes(data)

Send the given bytes (or UTF-8-encoded string) and close stdin

Returns

(data: Uint8Array \| string) => StdinMode

Types

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`

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

​Sandbox

​sandbox.exec()

​sandbox.execWith()

​sandbox.shell()

​sandbox.attachShell()

​sandbox.execStream()

​sandbox.execStreamWith()

​sandbox.shellStream()

​sandbox.attach()

​sandbox.attachWith()

​ExecOutput

​output.code

​output.success

​output.status

​output.stdout()

​output.stderr()

​output.stdoutBytes()

​output.stderrBytes()

​ExecHandle

​handle.recv()

​handle.takeStdin()

​handle.wait()

​handle.collect()

​handle.signal()

​handle.kill()

​handle.resize()

​handle.Symbol.asyncIterator

​handle.Symbol.asyncDispose

​ExecSink

​sink.write()

​sink.close()

​sink.Symbol.asyncDispose

​ExecOptionsBuilder

​execOptions.arg()

​execOptions.args()

​execOptions.cwd()

​execOptions.user()

​execOptions.env()

​execOptions.envs()

​execOptions.timeout()

​execOptions.stdinNull()

​execOptions.stdinPipe()

​execOptions.stdinBytes()

​execOptions.tty()

​execOptions.rlimit()

​execOptions.rlimitRange()

​AttachOptionsBuilder

​attachOptions.arg()

​attachOptions.args()

​attachOptions.cwd()

​attachOptions.user()

​attachOptions.env()

​attachOptions.envs()

​attachOptions.detachKeys()

​attachOptions.rlimit()

​attachOptions.rlimitRange()

​Stdin

​Stdin.null()

​Stdin.pipe()

​Stdin.bytes()

​Types

​ExecEvent

​ExitStatus

​StdinMode

​Rlimit

​RlimitResource

Sandbox

sandbox.exec()

sandbox.execWith()

sandbox.shell()

sandbox.attachShell()

sandbox.execStream()

sandbox.execStreamWith()

sandbox.shellStream()

sandbox.attach()

sandbox.attachWith()

ExecOutput

output.code

output.success

output.status

output.stdout()

output.stderr()

output.stdoutBytes()

output.stderrBytes()

ExecHandle

handle.recv()

handle.takeStdin()

handle.wait()

handle.collect()

handle.signal()

handle.kill()

handle.resize()

handle.Symbol.asyncIterator

handle.Symbol.asyncDispose

ExecSink

sink.write()

sink.close()

sink.Symbol.asyncDispose

ExecOptionsBuilder

execOptions.arg()

execOptions.args()

execOptions.cwd()

execOptions.user()

execOptions.env()

execOptions.envs()

execOptions.timeout()

execOptions.stdinNull()

execOptions.stdinPipe()

execOptions.stdinBytes()

execOptions.tty()

execOptions.rlimit()

execOptions.rlimitRange()

AttachOptionsBuilder

attachOptions.arg()

attachOptions.args()

attachOptions.cwd()

attachOptions.user()

attachOptions.env()

attachOptions.envs()

attachOptions.detachKeys()

attachOptions.rlimit()

attachOptions.rlimitRange()

Stdin

Stdin.null()

Stdin.pipe()

Stdin.bytes()

Types

ExecEvent

ExitStatus

StdinMode

Rlimit

RlimitResource