Execution

See Commands for usage examples.

attach()

async fn attach(&self, cmd: impl Into<String>, args: impl IntoIterator<Item = impl Into<String>>) -> MicrosandboxResult<i32>

Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Your terminal’s stdin, stdout, and stderr are connected to the guest process. Press Ctrl+] (or configured detach keys) to disconnect without stopping the process - it keeps running and can be reattached via its session ID. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to run
args	`impl IntoIterator<Item = impl Into<String>>`	Command arguments

Returns

Type	Description
`i32`	Exit code of the process

attach_shell()

async fn attach_shell(&self) -> MicrosandboxResult<i32>

Attach to the sandbox’s default shell (configured via SandboxBuilder::shell(), defaults to /bin/sh). Returns

Type	Description
`i32`	Exit code

attach_with()

async fn attach_with(&self, cmd: impl Into<String>, f: impl FnOnce(AttachOptionsBuilder) -> AttachOptionsBuilder) -> MicrosandboxResult<i32>

Interactive PTY attach with options for environment variables, working directory, user, and custom detach keys. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to run
f	`AttachOptionsBuilder`	Configure attach options (env, cwd, user, detach keys).

Returns

Type	Description
`i32`	Exit code of the process

exec()

async fn exec(&self, cmd: impl Into<String>, args: impl IntoIterator<Item = impl Into<String>>) -> MicrosandboxResult<ExecOutput>

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 exec_stream() instead. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to execute (e.g. `"python"`, `"/usr/bin/node"`)
args	`impl IntoIterator<Item = impl Into<String>>`	Command arguments (e.g. `["-c", "print('hello')"]`)

Returns

Type	Description
`ExecOutput`	Collected stdout, stderr, and exit status

exec_stream()

async fn exec_stream(&self, cmd: impl Into<String>, args: impl IntoIterator<Item = impl Into<String>>) -> MicrosandboxResult<ExecHandle>

Run a command with streaming output. Returns a handle that emits stdout, stderr, and exit events as they happen, rather than buffering everything until the command finishes. Use this for long-running processes, large output, or when you need to process output incrementally. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to execute
args	`impl IntoIterator<Item = impl Into<String>>`	Command arguments

Returns

Type	Description
`ExecHandle`	Streaming handle for receiving events and controlling the process

exec_stream_with()

async fn exec_stream_with(&self, cmd: impl Into<String>, f: impl FnOnce(ExecOptionsBuilder) -> ExecOptionsBuilder) -> MicrosandboxResult<ExecHandle>

Streaming execution with per-execution overrides. Enable stdin_pipe() to write to the process’s stdin, and tty(true) to allocate a pseudo-terminal for interactive programs like shells, REPLs, or editors. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to execute
f	`ExecOptionsBuilder`	Configure execution options.

Returns

Type	Description
`ExecHandle`	Streaming handle

exec_with()

async fn exec_with(&self, cmd: impl Into<String>, f: impl FnOnce(ExecOptionsBuilder) -> ExecOptionsBuilder) -> MicrosandboxResult<ExecOutput>

Run a command with per-execution overrides. The closure receives an ExecOptionsBuilder to configure working directory, environment variables, timeout, resource limits, stdin mode, and TTY allocation. These overrides apply only to this execution and don’t change the sandbox’s defaults. Parameters

Name	Type	Description
cmd	`impl Into<String>`	Command to execute
f	`ExecOptionsBuilder`	Configure execution options.

Returns

Type	Description
`ExecOutput`	Collected stdout, stderr, and exit status

shell()

async fn shell(&self, script: impl Into<String>) -> MicrosandboxResult<ExecOutput>

Run a command through the sandbox’s configured shell (defaults to /bin/sh). The script is passed as sh -c "<script>", so shell syntax like pipes, redirects, and && chains works. Parameters

Name	Type	Description
script	`impl Into<String>`	Shell command string (e.g. `"ls -la /app && echo done"`)

Returns

Type	Description
`ExecOutput`	Collected stdout, stderr, and exit status

shell_stream()

async fn shell_stream(&self, script: impl Into<String>) -> MicrosandboxResult<ExecHandle>

Shell command with streaming output. Parameters

Name	Type	Description
script	`impl Into<String>`	Shell command string

Returns

Type	Description
`ExecHandle`	Streaming handle

Types

ExecEvent

Events emitted by a streaming execution.

Variant	Fields	Description
`Exited`	`code: i32`	The process has exited. `code` is the exit code.
`Started`	`pid: u32`	The process has started. `pid` is the guest-side PID.
`Stderr`	`Bytes`	A chunk of stderr data.
`Stdout`	`Bytes`	A chunk of stdout data. May arrive in arbitrary sizes.

ExecHandle

A handle to a running streaming execution. Receives events as the process produces output, and provides control over stdin and signals.

Method	Returns	Description
collect()	`ExecOutput`	Wait for exit and collect all remaining stdout/stderr.
id()	`String`	Session ID for this execution. Can be used to reattach later.
kill()	`()`	Send SIGKILL to the process.
recv()	`Option<ExecEvent>`	Receive the next event. Returns `None` when the process has exited and all output has been delivered.
signal(signal)	`()`	Send a POSIX signal to the process (e.g. `libc::SIGTERM`).
take_stdin()	`Option<ExecSink>`	Take the stdin writer. Only available if `stdin_pipe()` was enabled. Returns `None` after the first call.
wait()	`ExitStatus`	Wait for the process to exit, discarding any remaining output.

ExecOptionsBuilder

Builder for per-execution overrides. Does not change the sandbox’s defaults.

Method	Parameters	Description
args()	`impl IntoIterator<Item = impl Into<String>>`	Append command-line arguments.
cwd()	`impl Into<String>`	Override the working directory for this command.
env()	- `key: impl Into<String>` - `value: impl Into<String>`	Set an environment variable. Merged on top of sandbox-level env vars.
envs()	`impl IntoIterator<Item = (String, String)>`	Set multiple environment variables at once.
rlimit()	- `resource:` `RlimitResource` - `limit: u64`	Set a POSIX resource limit (soft = hard). Applied via `setrlimit()` before exec.
rlimit_range()	- `resource:` `RlimitResource` - `soft: u64` - `hard: u64`	Set a resource limit with different soft and hard values.
stdin_bytes()	`impl Into<Vec<u8>>`	Provide fixed bytes as stdin. The process reads them and then sees EOF.
stdin_null()	-	Stdin reads from `/dev/null`. This is the default.
stdin_pipe()	-	Enable a stdin writer via `ExecSink`. Use with `ExecHandle::take_stdin()`.
timeout()	`Duration`	Kill the process with SIGKILL if it hasn’t exited within this duration.
tty()	`bool`	Allocate a pseudo-terminal. Enable for interactive programs (shells, editors, `top`); disable for scripts and batch jobs. Default: `false`.
user()	`impl Into<String>`	Override the guest user for this command.

ExecOutput

The result of a completed command execution. Holds the exit status and all captured output.

Field / Method	Type	Description
status()	`ExitStatus`	Exit code and success flag
stderr()	`Result<String>`	Collected stderr decoded as UTF-8
stderr_bytes()	`&Bytes`	Raw stderr bytes without decoding
stdout()	`Result<String>`	Collected stdout decoded as UTF-8. Returns `Err` if the output is not valid UTF-8.
stdout_bytes()	`&Bytes`	Raw stdout bytes without decoding

ExecSink

A writer for sending data to a running process’s stdin. Obtained via ExecHandle::take_stdin().

Method	Parameters	Description
close()	-	Close stdin. The process sees EOF on its stdin.
write()	`data: impl AsRef<[u8]>`	Write bytes to the process’s stdin.

ExitStatus

The exit status of a completed process.

Field	Type	Description
code	`i32`	Exit code. `0` typically means success.
success	`bool`	`true` if code is `0`

RlimitResource

POSIX resource limit identifiers. Maps to RLIMIT_* constants.

Value	Description
`As`	Max address space size
`Core`	Max core file size
`Cpu`	Max CPU time in seconds
`Data`	Max data segment size
`Fsize`	Max file size in bytes
`Locks`	Max file locks
`Memlock`	Max locked memory
`Msgqueue`	Max bytes in POSIX message queues
`Nice`	Max nice priority
`Nofile`	Max open file descriptors
`Nproc`	Max number of processes
`Rss`	Max resident set size
`Rtprio`	Max real-time priority
`Rttime`	Max real-time timeout
`Sigpending`	Max pending signals
`Stack`	Max stack size

Getting Started

Rust SDK

TypeScript SDK

attach()

attach_shell()

attach_with()

exec()

exec_stream()

exec_stream_with()

exec_with()

shell()

shell_stream()

Types

ExecEvent

ExecHandle

ExecOptionsBuilder

ExecOutput

ExecSink

ExitStatus

RlimitResource

Getting Started

Rust SDK

TypeScript SDK

​attach()

​attach_shell()

​attach_with()

​exec()

​exec_stream()

​exec_stream_with()

​exec_with()

​shell()

​shell_stream()

​Types

​ExecEvent

​ExecHandle

​ExecOptionsBuilder

​ExecOutput

​ExecSink

​ExitStatus

​RlimitResource

attach()

attach_shell()

attach_with()

exec()

exec_stream()

exec_stream_with()

exec_with()

shell()

shell_stream()

Types

ExecEvent

ExecHandle

ExecOptionsBuilder

ExecOutput

ExecSink

ExitStatus

RlimitResource