Commands

Run commands, read their output, and check exit codes without SSH. Execution uses a dedicated host-to-guest channel, so it works even with networking 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 preserving the effective entrypoint. If neither field supplies an executable, these methods return the typed NoDefaultCommand error instead of falling back to a shell.

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

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

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

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("example/worker:latest"),
    m.WithCmd("worker.py", "--once"),
)
output, err := sb.ExecDefault(ctx)

The default workload also supports streaming and interactive execution:

// Choose one: stream output, or attach the current terminal.
const stream = await sb.execDefaultStream();
// const exit = await sb.attachDefault();

// Choose one: stream output, or attach the current terminal.
let stream = sb.exec_default_stream().await?;
// let exit = sb.attach_default().await?;

# Choose one: stream output, or attach the current terminal.
stream = await sb.exec_default_stream()
# exit_code = await sb.attach_default()

// Choose one: stream output, or attach the current terminal.
stream, err := sb.ExecDefaultStream(ctx)
if err != nil {
    return err
}
defer stream.Close()
// exitCode, err := sb.AttachDefault(ctx)

Consume the stream as shown in Streaming output. Literal command execution and terminal attachment 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.

const output = await sb.exec("python", ["-c", "print('hello')"]);
console.log(output.stdout()); // "hello\n"
console.log(output.success);  // true
console.log(output.code);     // 0

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

output = await sb.exec("python", ["-c", "print('hello')"])
print(output.stdout_text)     # "hello\n"
print(output.success)         # True
print(output.exit_code)       # 0

output, err := sb.Exec(ctx, "python", []string{"-c", "print('hello')"})
fmt.Print(output.Stdout())     // "hello\n"
fmt.Println(output.Success())  // true
fmt.Println(output.ExitCode()) // 0

output = sb.exec("python", ["-c", "print('hello')"])
puts output.stdout     # "hello\n"
puts output.success?   # true
puts output.exit_code  # 0

msb exec worker -- python -c "print('hello')"

Background jobs

Use a background job for a command that should keep running after you disconnect. The local sandbox must already be running. Starting the job returns an ID you can use to check its progress or reconnect.

const job = await sb.execDetachedWith("sh", (e) => e
    .args(["-c", "echo started; sleep 60; echo done"])
    .stdinNull());
console.log(job.id);
const result = await job.wait();
const output = await job.logs();

use microsandbox::sandbox::jobs::JobLogOptions;

let job = sb.exec_detached_with("sh", |e| e
    .args(["-c", "echo started; sleep 60; echo done"])
    .stdin_null()).await?;
println!("{}", job.id());
let result = job.wait().await?;
let output = job.logs(&JobLogOptions::default()).await?;

from microsandbox import Stdin

job = await sb.exec_detached(
    "sh", ["-c", "echo started; sleep 60; echo done"], stdin=Stdin.null(),
)
print(job.id)
result = await job.wait()
output = await job.logs()

job, err := sb.ExecDetached(ctx, "sh",
    []string{"-c", "echo started; sleep 60; echo done"}, m.WithExecStdinNull(),
)
if err != nil {
    return err
}
defer job.Close()
fmt.Println(job.ID())
result, err := job.Wait(ctx)
if err != nil {
    return err
}

job = sb.exec_detached("sh", ["-c", "echo started; sleep 60; echo done"], stdin: :null)
puts job.id
result = job.wait
output = job.logs

msb create alpine --name worker
job=$(msb exec -d --no-stdin worker -- sh -c 'echo started; sleep 60; echo done')
msb logs worker --job "$job" --follow
msb wait worker --job "$job"

Stopping the sandbox stops its jobs. Restarting never reruns them. Finish active jobs before taking a full snapshot or forking; pause and resume remain supported.

Command	Purpose
`msb jobs <sandbox>`	List active jobs; `--all` includes retained history
`msb logs <sandbox> --job ID`	Read output; add `--follow` to stream it
`msb inspect <sandbox> --job ID`	Show command, state, input mode, and exit result
`msb attach <sandbox> --job ID`	Reconnect; Ctrl-] detaches without stopping the job
`msb wait <sandbox> --job ID`	Wait for exit; `--timeout 30s` limits the wait, not the job
`msb signal <sandbox> --job ID --signal TERM`	Send a Linux signal to the process group
`msb kill <sandbox> --job ID`	Request SIGKILL; use `wait` to confirm exit
`msb eof <sandbox> --job ID`	Close pipe input permanently; use Ctrl-D for a terminal

Job IDs belong to one sandbox and are separate from process IDs. Without --job, logs, inspect, and wait refer to the sandbox itself. All commands also support the msb sandbox ... form.

Input and interactive shells

--no-stdin sends EOF and disables automatic terminal allocation. Otherwise, input stays open for a later attachment. --tty forces a terminal; --no-tty uses pipes. Detached launch never reads your terminal’s input and cannot be combined with --stream.

shell_job=$(msb exec -d --tty worker -- sh)
msb attach worker --job "$shell_job"
# Press Ctrl-] to detach, then attach again with the same job ID.

One attachment can write at a time; others can use --read-only. Detaching or reaching local input EOF leaves guest input open. An abrupt disconnect releases input ownership within 30 seconds. Terminal output combines stdout and stderr as output; pipes keep them separate.

History and limits

Job metadata and captured output remain available after disconnect or sandbox shutdown. After a runtime restart, a job without a confirmed exit is marked lost.

Up to 32 active jobs and 256 retained histories per sandbox.
Two 512 KiB output segments per job. Reading pruned output reports a cursor-gap error.
After 65,536 job admissions, restart the sandbox to launch more.

Use --limit N and --cursor ID to page through jobs. jobs, inspect, and wait accept --format json. Logs retain their usual tail, time, source, and format options.If output storage fails, capture stops permanently for that job. Previously saved output stays readable, and the process and live attachments continue. Inspect the job for the cutoff. If metadata storage also fails, its diagnostic stays in memory until a later update can save it.

Timeouts and interrupted input

Execution timeouts still apply after you disconnect. Older runtimes and unsupported backends reject job launch before dispatch. SDK job errors expose stable codes. If launch confirmation is lost, the error includes a job ID; inspect it before retrying to avoid starting the command twice.While paused, you can inspect or wait for jobs, but waiting does not resume them. Signals take effect after resume. Full input buffers do not block signals or deadlines. Input bytes and EOF remain ordered; a signal may interrupt queued input. Inspect reports signal-delivery failures.Ctrl-] remains available while input is blocked, with up to 1 MiB of buffered lookahead. Detaching waits up to two seconds for earlier input to be accepted. Overflow discards further input but keeps the attachment open until you detach, reach local EOF, or the job finishes.input_not_flushed means some input was dropped or could not be confirmed. Do not resend it automatically: the job may already have received it. Detaching restores your terminal without stopping the job or closing its input.A graceful sandbox stop interrupts queued command input while preserving filesystem ordering. If stop times out, it reports failure without forcing termination.

Execution options

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

const output = await sb.execWith("python", (e) =>
    e.args(["compute.py"])
        .cwd("/app")
        .env("PYTHONPATH", "/app/lib")
        .timeout(30_000)
        .rlimit("nofile", 1024),
);

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

from microsandbox import Rlimit

output = await sb.exec(
    "python",
    ["compute.py"],
    cwd="/app",
    env={"PYTHONPATH": "/app/lib"},
    timeout=30.0,
    rlimits=[Rlimit.nofile(1024)],
)

output, err := sb.Exec(ctx, "python", []string{"compute.py"},
    m.WithExecCwd("/app"),
    m.WithExecEnv(map[string]string{"PYTHONPATH": "/app/lib"}),
    m.WithExecTimeout(30*time.Second),
)

output = sb.exec(
  "python", ["compute.py"],
  cwd: "/app",
  env: { "PYTHONPATH" => "/app/lib" },
  timeout: 30.0,
  rlimits: { nofile: 1024 }
)

msb exec worker \
  -w /app \
  -e PYTHONPATH=/app/lib \
  --timeout 30s \
  --rlimit nofile=1024 \
  -- python compute.py

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.

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

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

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

output, err := sb.Shell(ctx, "ls -la /app && echo done")

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

msb exec worker -- sh -c "ls -la /app && echo done"

Stream output

Ruby currently collects command output with exec and shell. It does not expose streaming handles, interactive attach, or session IDs.

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.

const handle = await sb.execStream("tail", ["-f", "/var/log/app.log"]);

for await (const event of handle) {
    switch (event.kind) {
        case "stdout": process.stdout.write(event.data); break;
        case "stderr": process.stderr.write(event.data); break;
        case "exited": console.log(`Exited: ${event.code}`); break;
    }
}

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,
        _ => {}
    }
}

from microsandbox import ExecEventType

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

async for event in handle:
    match event.event_type:
        case ExecEventType.STDOUT: print(event.data.decode(), end="")
        case ExecEventType.STDERR: print(event.data.decode(), end="", file=sys.stderr)
        case ExecEventType.EXITED: print(f"Exited: {event.code}")

handle, err := sb.ExecStream(ctx, "tail", []string{"-f", "/var/log/app.log"})
for {
    event, err := handle.Recv(ctx)
    if err != nil {
        return err
    }
    switch event.Kind {
    case m.ExecEventStdout:
        os.Stdout.Write(event.Data)
    case m.ExecEventStderr:
        os.Stderr.Write(event.Data)
    case m.ExecEventExited:
        fmt.Printf("Exited: %d\n", event.ExitCode)
    case m.ExecEventDone:
        return nil
    }
}

With the local runtime’s dedicated signal channel, kill() and other signals return execution_closed immediately if the execution ended or its start was rejected. Successful delivery does not confirm process exit; wait for completion. A timeout reports whether the signal was queued and may still be delivered.

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.

// Attach to the default shell
const exitCode = await sb.attachShell();

// Attach to a specific command with custom detach keys
await sb.attachWith("bash", (a) =>
    a.env("DEBUG", "1").cwd("/app").detachKeys("ctrl-q"),
);

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

# Attach to the default shell
exit_code = await sb.attach_shell()

# Attach to a specific command with custom detach keys
exit_code = await sb.attach(
    "python",
    env={"DEBUG": "1"},
    cwd="/app",
    detach_keys="ctrl-q",
)

// Attach to the default shell.
exitCode, err := sb.AttachShell(ctx)
if err != nil {
    return err
}
fmt.Println("shell exited with", exitCode)

// Attach to a specific command with options.
exitCode, err = sb.AttachWith(ctx, "python", nil,
    m.WithAttachUser("dev"),
    m.WithAttachEnv(map[string]string{"DEBUG": "1"}),
    m.WithAttachCwd("/app"),
    m.WithAttachDetachKeys("ctrl-q"),
)
if err != nil {
    return err
}
fmt.Println("python exited with", exitCode)

# Attach to the default shell
msb exec -t worker

# Attach to a specific command
msb exec -t worker -e DEBUG=1 -w /app -- python

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

TypeScript, Rust, Python, and Ruby can pass input bytes with the command. Ruby does not expose a streaming stdin writer; Go uses a pipe to supply input and collect the result.

const output = await sandbox.execWith("cat", (e) => e.stdinBytes(Buffer.from("hello\n")));
console.log(output.stdout());

let output = sandbox.exec_with("cat", |e| e.stdin_bytes(b"hello\n".to_vec())).await?;
println!("{}", output.stdout()?);

output = await sandbox.exec("cat", stdin=b"hello\n")
print(output.stdout_text)

handle, err := sandbox.ExecStream(ctx, "cat", nil, m.WithExecStdinPipe())
if err != nil {
    return err
}
defer handle.Close()
stdin := handle.TakeStdin()
if _, err := stdin.Write([]byte("hello\n")); err != nil {
    return err
}
if err := stdin.Close(); err != nil {
    return err
}
output, err := handle.Collect(ctx)
if err != nil {
    return err
}
fmt.Print(output.Stdout())

output = sandbox.exec("cat", stdin: "hello\n")
puts output.stdout

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.

const handle = await sb.execStreamWith("python", (e) => e.stdinPipe().tty(true));
const stdin = await handle.takeStdin();
await stdin!.write("print('hello')\n");
await stdin!.write("exit()\n");
await stdin!.close();
await handle.wait();

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

from microsandbox import Stdin

handle = await sb.exec_stream("python", stdin=Stdin.pipe(), tty=True)
stdin = handle.take_stdin()
await stdin.write(b"print('hello')\n")
await stdin.write(b"exit()\n")
await stdin.close()
await handle.wait()

handle, err := sb.ExecStream(ctx, "python", nil, m.WithExecStdinPipe())
stdin := handle.TakeStdin()
_, _ = stdin.Write([]byte("print('hello')\n"))
_, _ = stdin.Write([]byte("exit()\n"))
_ = stdin.Close()
_, err = handle.Wait(ctx)

Output and stdin buffering

Each command has a 1 MiB output buffer, shared by stdout and stderr. When it fills, the guest stops reading the command’s output; once the guest pipe buffers also fill, the command’s writes block (or return EAGAIN for nonblocking writers) until you consume output. Nothing is dropped, and other threads in the guest keep running. Read output while the command runs; waiting for a completion marker before reading can leave the command blocked. Collecting complete output uses memory proportional to its size. To let a command finish without a reader, redirect its output to a file. This applies to SDK, CLI, and SSH execution. Stdin has a 64 KiB allowance per command. Writes wait for capacity and send straight from your buffer; cancelling a write can leave an already-delivered prefix. When a command both reads input and writes output, send and read concurrently so neither side blocks the other.

Session IDs

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

const handle = await sb.execStream("python", ["server.py"])
const sessionId = handle.id

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

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

handle, err := sb.ExecStream(ctx, "python", []string{"server.py"})
if err != nil {
    return err
}
sessionID, err := handle.ID()

Reference

For exact execution APIs, see TypeScript, Rust, Python, Go, or Ruby. For command-line execution, see msb run and msb exec.

Getting Started

Sandboxes

Networking

Deep dive

Troubleshooting

Run the image default workload

Execute a command

Background jobs

Execution options

Shell commands

Stream output

Interactive attach

Write stdin

Output and stdin buffering

Session IDs

Reference