Skip to main content
See Commands for usage examples.

Sandbox

sandbox.exec()

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

Collected stdout, stderr, and exit status.

sandbox.execWith()

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.

sandbox.shell()

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.

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

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.

sandbox.execStreamWith()

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.
Builder callback for per-call overrides.

Returns

Streaming handle.

sandbox.shellStream()

Run a shell command with streaming output.

Parameters

scriptstring
Shell command string.

Returns

Streaming handle.

sandbox.attach()

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

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.

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

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

Returns

string

output.stderr()

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

Returns

string

output.stdoutBytes()

Raw stdout bytes

Returns

Uint8Array

output.stderrBytes()

Raw stderr bytes

Returns

Uint8Array

ExecHandle

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

A handle to a running streaming execution and its events. A configured streaming timeout is enforced by the SDK even when the caller is not reading output. At expiry, the SDK waits for process startup before sending SIGKILL. Waiting or collecting reports ExecTimeoutError after the guest confirms exit; cancelling a pending wait does not cancel the deadline. Raw event readers receive the actual exit event. If termination cannot be delivered, the SDK reports a separate error without claiming the process exited. The SDK connection must remain open for this client-owned deadline to run.

handle.recv()

Receive the next event, or null once the stream ends

Returns

Promise<ExecEvent \| null>

handle.takeStdin()

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

Returns

Promise<ExecSink \| null>

handle.wait()

Wait for the process to exit

Returns

Promise<ExitStatus>

handle.collect()

Drain stdout/stderr and wait for exit

Returns

Promise<ExecOutput>

handle.signal()

Send a POSIX signal (numeric) to the process

Returns

Promise<void>

handle.kill()

Force-terminate the process

Returns

Promise<void>

handle.resize()

Resize the PTY to the given unsigned 16-bit dimensions

Returns

Promise<void>

handle.Symbol.asyncIterator

Iterate events with for await...of

Returns

AsyncIterator<ExecEvent>

handle.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 bytes to the process’s stdin. Strings are UTF-8 encoded. The write completes once the guest accepts the data, so it waits while the command is slow to read. For a command that also produces output, read output concurrently to avoid blocking each other. Writing empty data does nothing. Call close() when done writing; in pipe mode it sends EOF.

Returns

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

sink.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

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

Append a single argument

Returns

(arg: string) => this

execOptions.args()

Append many arguments

Returns

(args: string[]) => this

execOptions.cwd()

Working directory

Returns

(cwd: string) => this

execOptions.user()

Guest user

Returns

(user: string) => this

execOptions.env()

Add a single env var

Returns

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

execOptions.envs()

Add many env vars

Returns

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

execOptions.timeout()

Kill the process after this many milliseconds

Returns

(ms: number) => this

execOptions.stdinNull()

Connect stdin to /dev/null (default)

Returns

() => this

execOptions.stdinPipe()

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

Returns

() => this

execOptions.stdinBytes()

Pre-supply stdin bytes and close it

Returns

(data: Buffer) => this

execOptions.tty()

Allocate a pseudo-terminal

Returns

(enabled: boolean) => this

execOptions.rlimit()

Set both soft and hard rlimit. Numeric limits must be non-negative safe integers (at most Number.MAX_SAFE_INTEGER). Values above 32 bits are preserved; negative, fractional, non-finite, and unsafe integers are rejected

Returns

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

execOptions.rlimitRange()

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

Append a single argument

Returns

(arg: string) => this

attachOptions.args()

Append many arguments

Returns

(args: string[]) => this

attachOptions.cwd()

Working directory

Returns

(cwd: string) => this

attachOptions.user()

Guest user

Returns

(user: string) => this

attachOptions.env()

Add a single env var

Returns

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

attachOptions.envs()

Add many env vars

Returns

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

attachOptions.detachKeys()

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

Returns

(spec: string) => this

attachOptions.rlimit()

Set both soft and hard rlimit. Numeric limits must be non-negative safe integers (at most Number.MAX_SAFE_INTEGER). Values above 32 bits are preserved; negative, fractional, non-finite, and unsafe integers are rejected

Returns

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

attachOptions.rlimitRange()

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

Connect stdin to /dev/null

Returns

() => StdinMode

Stdin.pipe()

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

Returns

() => StdinMode

Stdin.bytes()

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.

ExitStatus

Returned by ExecHandle.wait() · ExecOutput.status

The exit result of a process.

StdinMode

Produced by Stdin

Discriminated union describing stdin behavior for an execution.

Rlimit

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

A POSIX resource limit applied to the process.

RlimitResource

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

String union naming a limitable POSIX resource.

Managed jobs

sandbox.execDetached()

Start a runtime-owned command and return after guest startup. Defaults to pipes with stdin retained. Requires a supporting local runtime. Dropping the handle does not stop the job; stopping the sandbox does. See background jobs for lifecycle and limits.

sandbox.execDetachedWith()

Configure detached execution with the existing execution builder. stdinNull() closes stdin; stdinBytes() provides at most 64 KiB followed by EOF. Use attachment writes for larger input.

sandbox.getJob()

Look up a sandbox-scoped job. Available on Sandbox and SandboxHandle.

sandbox.listJobs()

List active jobs. Available on Sandbox and SandboxHandle.

sandbox.listJobsWith()

Configure pagination or include retained completed jobs. Available on Sandbox and SandboxHandle.

Job

job.id

Opaque sandbox-scoped job identity.

job.inspect()

Read current status and capture failures.

job.wait()

Wait for process exit independently of output consumption.

job.signal()

Request delivery of a numeric signal.

job.kill()

Request termination. Use wait() to confirm exit.

job.eof()

Permanently close pipe stdin. PTYs reject EOF; use terminal control characters.

job.logs()

Read bounded retained output. Cursors are opaque and job-scoped; retention gaps are explicit.

job.logStream()

Open an output stream. Close or dispose it to release the observer.

job.followLogs()

Open a stream with following enabled.

job.attach()

Attach as the single input owner. Detaching preserves the job and its stdin.

job.attachWith()

Configure read-only observation or replay. Multiple read-only observers may coexist.

JobAttachment

attachment.recv()

Receive output, a retention gap, or completion; null ends the stream. May run concurrently with input and detach.

attachment.writeStdin()

Admit at most 16 KiB per call. An empty buffer does not send EOF.

attachment.resize()

Resize the attached PTY.

attachment.detach()

Release the attachment without closing stdin or killing the job. Async disposal and ending async iteration also detach.

JobLogStream

stream.next()

Read the next entry, or null at end. Also supports async iteration.

stream.close()

Release the observer without killing the job. Async disposal and ending async iteration also close the stream.

JobListBuilder

list.all()

Include completed jobs. Calling without an argument enables it.

list.limit()

Set page size (default 50).

list.cursor()

Continue from JobPage.nextCursor.

JobAttachOptionsBuilder

options.readOnly()

Observe without owning input. Calling without an argument enables it.

options.replayRecent()

Replay up to this many recent bytes; replaces a replay cursor.

options.replayAfter()

Replay after a job-scoped cursor; replaces the recent-byte limit.

JobState

JobInfo

JobPage

JobExit

JobLogEntry

JobLogOptions

Timestamps use Unix milliseconds. fromCursor resumes after an opaque job-scoped cursor; follow keeps reading new output. tail, since, until, and sources filter logs.

JobEvent

JobError

Stable failure code and, for uncertain launch errors, a recoverable job ID. Inspect that ID before retrying.