Execution

Collected stdout, stderr, and exit status.

sb.exec_with()

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

Example

use std::time::Duration;

let out = sb.exec_with("python", |e| e
    .args(["compute.py"])
    .cwd("/app")
    .env("LOG_LEVEL", "debug")
    .timeout(Duration::from_secs(30)))
    .await?;

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

Parameters

cmdimpl Into<String>

Command to execute.

Configure execution options.

Returns

Collected stdout, stderr, and exit status.

sb.shell()

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

Example

let out = sb.shell("cat /etc/os-release | grep PRETTY_NAME").await?;
println!("{}", out.stdout()?);

Run a command through the sandbox’s configured shell (default: /bin/sh, set via SandboxBuilder::shell()). The script is run as <shell> -c "<script>", so shell syntax like pipes, redirects, and && chains works.

Parameters

scriptimpl Into<String>

Shell command string, e.g. “ls -la /app && echo done”.

Returns

Collected stdout, stderr, and exit status.

sb.shell_with()

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

Example

let out = sb.shell_with("env | sort", |e| e.env("STAGE", "build")).await?;

Run a shell command with per-execution overrides and wait for completion. The -c <script> arguments are prepended to whatever the ExecOptionsBuilder configures, so use the builder for env, cwd, user, timeout, and resource limits rather than for positional args.

Parameters

scriptimpl Into<String>

Shell command string.

Configure execution options.

Returns

Collected stdout, stderr, and exit status.

sb.exec_stream()

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

Example

use microsandbox::ExecEvent;

let mut handle = sb.exec_stream("tail", ["-f", "/var/log/app.log"]).await?;
while let Some(event) = handle.recv().await {
    match event {
        ExecEvent::Stdout(chunk) => print!("{}", String::from_utf8_lossy(&chunk)),
        ExecEvent::Exited { code } => { println!("exited {code}"); break; }
        _ => {}
    }
}

Run a command with streaming output. Returns an ExecHandle that emits stdout, stderr, started, 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

cmdimpl Into<String>

Command to execute.

argsimpl IntoIterator

Command arguments.

Returns

Streaming handle for receiving events and controlling the process.

sb.exec_stream_with()

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

Example

let mut handle = sb.exec_stream_with("python", |e| e.stdin_pipe().tty(true)).await?;
if let Some(stdin) = handle.take_stdin() {
    stdin.write(b"print(2 + 2)\n").await?;
    stdin.close().await?;
}

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

Parameters

cmdimpl Into<String>

Command to execute.

Configure execution options.

Returns

Streaming handle.

sb.shell_stream()

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

Example

let mut handle = sb.shell_stream("for i in 1 2 3; do echo $i; sleep 1; done").await?;
let out = handle.collect().await?;

Like shell(), but returns a streaming ExecHandle instead of waiting for completion.

Parameters

scriptimpl Into<String>

Shell command string.

Returns

Streaming handle.

sb.shell_stream_with()

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

Example

let mut handle = sb.shell_stream_with("npm run build", |e| e.cwd("/app")).await?;

Run a shell command with per-execution overrides and streaming I/O. As with shell_with(), the -c <script> arguments are prepended to whatever the builder configures.

Parameters

scriptimpl Into<String>

Shell command string.

Configure execution options.

Returns