Commands

Execute commands, stream output, and interact with sandboxes

Command execution doesn’t use SSH or the network. There’s a dedicated channel between the host and a guest agent running inside the VM, completely separate from the sandbox’s network stack. The agent spawns processes, streams output back, and reports exit codes.

One nice consequence: exec works even when a sandbox has networking fully disabled.

Run the image default workload

Sandbox creation is boot-only: configuring an image, ENTRYPOINT, or CMD does not execute that workload. Use the default-workload methods when you want the SDK to resolve the effective OCI ENTRYPOINT + CMD and run it. A configured CMD override replaces the image CMD, while the effective entrypoint is preserved. If neither field supplies an executable, these methods return the typed NoDefaultCommand error instead of falling back to a shell.

Rust

let sb = Sandbox::builder("worker")
    .image("example/worker:latest")
    .cmd(["worker.py", "--once"])
    .create()
    .await?;
let output = sb.exec_default().await?;

Streaming variants are exec_default_stream, execDefaultStream, and ExecDefaultStream. Interactive variants are attach_default, attachDefault, and AttachDefault. Literal exec and attach continue to ignore ENTRYPOINT and CMD.

Execute a command

Run a command and wait for it to complete. You get back the exit code, stdout, and stderr.

Rust

let output = sb.exec("python", ["-c", "print('hello')"]).await?;
println!("{}", output.stdout()?);     // "hello\n"
println!("{}", output.status().code); // 0

Execution options

These options apply to a single execution and don’t change the sandbox’s defaults.

Rust

let output = sb.exec_with("python", |e| e
    .args(["compute.py"])
    .cwd("/app")
    .env("PYTHONPATH", "/app/lib")
    .timeout(Duration::from_secs(30))
    .rlimit(RlimitResource::Nofile, 1024)
).await?;

Shell commands

Run a command through the sandbox’s configured shell (defaults to /bin/sh). Useful for pipelines, redirects, and other shell syntax that exec doesn’t interpret.

Rust

let output = sb.shell("ls -la /app && echo done").await?;

Stream output

For long-running processes or large output, streaming gives you stdout, stderr, and exit events as they happen instead of buffering everything until the command finishes.

Rust

let mut handle = sb.exec_stream("tail", ["-f", "/var/log/app.log"]).await?;

while let Some(event) = handle.recv().await {
    match event {
        ExecEvent::Stdout(data) => print!("{}", String::from_utf8_lossy(&data)),
        ExecEvent::Stderr(data) => eprint!("{}", String::from_utf8_lossy(&data)),
        ExecEvent::Exited { code } => break,
        _ => {}
    }
}

Interactive attach

Bridges your terminal directly to a process inside the sandbox for a fully interactive PTY session. Useful for debugging, running REPLs, or anything that expects a real terminal.

Rust

let exit_code = sb.attach_shell().await?;

let exit_code = sb.attach_with("python", |a| a
    .env("DEBUG", "1")
    .cwd("/app")
    .detach_keys("ctrl-q")
).await?;

Press Ctrl+] (or your configured detach keys) to detach from the session without stopping the process. The process keeps running inside the VM and you can reattach later via its session ID.

Write stdin

Streaming handles can also accept stdin. Enable stdin_pipe and write bytes to it. Combined with tty: true, this lets you drive interactive processes programmatically.

Rust

let mut handle = sb.exec_stream_with("python", |e| e.stdin_pipe().tty(true)).await?;
let stdin = handle.take_stdin().unwrap();
stdin.write(b"print('hello')\n").await?;
stdin.write(b"exit()\n").await?;
handle.wait().await?;

Session IDs

Each streaming exec creates a session ID that you can use to correlate stream events and persisted log entries.

Rust

let handle = sb.exec_stream("python", ["server.py"]).await?;
let session_id = handle.id().to_string();