---
title: Execution
description: Go SDK - Command execution API reference
---
Run commands inside a running sandbox, collect their output, or stream events live. See [Commands](/sandboxes/commands) for usage examples.
The exec API mirrors `os/exec` conventions: a **non-zero exit code is not a Go error**. Transport, timeout, and spawn-failure paths return an `error`; a program that ran and exited non-zero is a normal [`*ExecOutput`](#execoutput) result, inspect [`Success()`](#out-success) or [`ExitCode()`](#out-exitcode).
Typical flow
```go
import m "github.com/superradcompany/microsandbox/sdk/go"
out, err := sb.Exec(ctx, "python3", []string{"-c", "print(1 + 1)"})
if err != nil {
return err // transport / timeout / spawn failure
}
if !out.Success() {
log.Printf("exited %d: %s", out.ExitCode(), out.Stderr())
}
fmt.Print(out.Stdout())
```
## Sandbox methods
The exec entry points live on [`*Sandbox`](/sdk/go/sandbox#instance-methods).
---
#### sb.Exec()
method
```go
func (s *Sandbox) Exec(ctx context.Context, cmd string, args []string, opts ...ExecOption) (*ExecOutput, error)
```
Run a command in the sandbox and return its collected output. Blocks until the command exits. The returned error is non-nil only on transport or runtime failures; a non-zero exit code is reported via [`ExecOutput.ExitCode`](#out-exitcode), not as an error.
Parameters
ctxcontext.Context
Cancels the wait. The guest process may continue in the background.
cmdstring
Program to run. Passed literally to the guest agent (the image ENTRYPOINT is not consulted).
args[]string
Command arguments. May be nil.
Per-command cwd, timeout, user, and env.
Returns
Collected stdout, stderr, and exit code.
```go
out, err := sb.Exec(ctx, "make", []string{"build"},
m.WithExecCwd("/app"),
m.WithExecEnv(map[string]string{"DEBUG": "1"}),
)
```
---
#### sb.Shell()
method
```go
func (s *Sandbox) Shell(ctx context.Context, command string, opts ...ExecOption) (*ExecOutput, error)
```
Run `/bin/sh -c command` in the sandbox and collect its output. Blocks until the command exits. A convenience wrapper over [`Exec`](#sb-exec) for shell one-liners.
Parameters
ctxcontext.Context
Cancels the wait.
commandstring
Shell command line passed to /bin/sh -c.
Per-command cwd, timeout, user, and env.
Returns
Collected stdout, stderr, and exit code.
```go
out, err := sb.Shell(ctx, "echo $HOME && ls /tmp")
if err != nil {
return err
}
fmt.Print(out.Stdout())
```
---
#### sb.ExecStream()
method
```go
func (s *Sandbox) ExecStream(ctx context.Context, cmd string, args []string, opts ...ExecOption) (*ExecHandle, error)
```
Start a streaming exec session and return an [`*ExecHandle`](#exechandle). The handle MUST be closed with [`Close`](#h-close) when the stream is no longer needed. Nonblocking: the handle returns immediately and the stream starts in the background.
`ctx` controls only the start handshake; individual [`Recv`](#h-recv) calls take their own `ctx`. Non-zero exit codes are not errors, inspect [`ExecEventExited`](#execeventkind).
Parameters
ctxcontext.Context
Controls the start handshake only.
cmdstring
Program to run.
args[]string
Command arguments. May be nil.
Returns
Live exec session. Close it when done.
```go
h, err := sb.ExecStream(ctx, "cat", nil, m.WithExecStdinPipe())
if err != nil {
return err
}
defer h.Close()
```
---
#### sb.ShellStream()
method
```go
func (s *Sandbox) ShellStream(ctx context.Context, command string, opts ...ExecOption) (*ExecHandle, error)
```
Run `/bin/sh -c command` with streaming output. A convenience wrapper over [`ExecStream`](#sb-execstream). Nonblocking: the handle returns immediately and the stream starts in the background.
Parameters
ctxcontext.Context
Controls the start handshake only.
commandstring
Shell command line passed to /bin/sh -c.
Returns
Live exec session. Close it when done.
```go
h, err := sb.ShellStream(ctx, "tail -f /var/log/app.log")
if err != nil {
return err
}
defer h.Close()
for {
ev, err := h.Recv(ctx)
if err != nil {
return err
}
switch ev.Kind {
case m.ExecEventStdout:
os.Stdout.Write(ev.Data)
case m.ExecEventDone:
return nil
}
}
```
## ExecHandle methods
A live streaming exec session returned by [`ExecStream`](#sb-execstream) and [`ShellStream`](#sb-shellstream). Not safe for concurrent use from multiple goroutines.
---
#### h.ID()
method
```go
func (h *ExecHandle) ID() (string, error)
```
Return the unique identifier for this exec session, assigned by the guest agent. Useful for correlating log entries or referencing the session from external tooling.
Returns
string
Session correlation id.
---
#### h.TakeStdin()
method
```go
func (h *ExecHandle) TakeStdin() *ExecSink
```
Return the stdin sink for this exec session. Single-take: returns `nil` if the session was not started with [`WithExecStdinPipe`](#withexecstdinpipe), or if `TakeStdin` was already called on this handle (matching the Node and Python SDKs). The caller is responsible for closing the sink when done writing; closing the sink without closing the exec handle is fine, they own different Rust-side resources.
Returns
Stdin writer, or nil if unavailable.
```go
sink := h.TakeStdin()
sink.Write([]byte("hello\n"))
sink.Close()
```
---
#### h.Recv()
method
```go
func (h *ExecHandle) Recv(ctx context.Context) (*ExecEvent, error)
```
Block until the next event arrives or the stream ends. Returns an event with `Kind == ExecEventDone` when all events have been consumed. `ctx` controls the wait; cancellation causes `Recv` to return `ctx.Err()` immediately. The underlying Rust call may continue to completion in the background.
Parameters
ctxcontext.Context
Cancels the wait for the next event.
Returns
```go
for {
ev, err := h.Recv(ctx)
if err != nil {
return err
}
switch ev.Kind {
case m.ExecEventStarted:
fmt.Printf("started pid=%d\n", ev.PID)
case m.ExecEventStdout:
os.Stdout.Write(ev.Data)
case m.ExecEventStderr:
os.Stderr.Write(ev.Data)
case m.ExecEventExited:
fmt.Printf("exited code=%d\n", ev.ExitCode)
case m.ExecEventDone:
return nil
}
}
```
---
#### h.Collect()
method
```go
func (h *ExecHandle) Collect(ctx context.Context) (*ExecOutput, error)
```
Drain the stream, accumulate all output, and return it as an [`*ExecOutput`](#execoutput). Equivalent to calling [`Recv`](#h-recv) in a loop and assembling the result. The handle should be closed after `Collect` returns.
Parameters
ctxcontext.Context
Cancels the drain.
Returns
Collected stdout, stderr, and exit code.
```go
out, err := h.Collect(ctx)
if err != nil {
return err
}
fmt.Print(out.Stdout())
```
---
#### h.Wait()
method
```go
func (h *ExecHandle) Wait(ctx context.Context) (int, error)
```
Block until the process exits and return its exit code. Unlike [`Collect`](#h-collect), stdout and stderr are discarded. The handle should be closed after `Wait` returns.
Parameters
ctxcontext.Context
Cancels the wait.
Returns
---
#### h.Kill()
method
```go
func (h *ExecHandle) Kill(ctx context.Context) error
```
Send SIGKILL to the running process.
Parameters
ctxcontext.Context
Cancels the call.
---
#### h.Signal()
method
```go
func (h *ExecHandle) Signal(ctx context.Context, signal int) error
```
Send a Unix signal to the running process. Pass values from `syscall` (e.g. `int(syscall.SIGTERM)`).
Parameters
ctxcontext.Context
Cancels the call.
signalint
Signal number, e.g. int(syscall.SIGTERM).
```go
import "syscall"
if err := h.Signal(ctx, int(syscall.SIGTERM)); err != nil {
return err
}
```
---
#### h.Close()
method
```go
func (h *ExecHandle) Close() error
```
Release the Rust-side exec handle. Does not kill the running process; call [`Signal`](#h-signal) or [`Kill`](#h-kill) first if you need to terminate it. Safe to call after `ExecEventDone` has been received.
```go
defer h.Close()
```
## ExecOutput methods
The collected result of a completed command execution, returned by [`Exec`](#sb-exec), [`Shell`](#sb-shell), and [`Collect`](#h-collect).
---
#### out.Stdout()
method
```go
func (e *ExecOutput) Stdout() string
```
Captured standard output as a string.
Returns
---
#### out.StdoutBytes()
method
```go
func (e *ExecOutput) StdoutBytes() []byte
```
Captured standard output as raw bytes. Use when the output may not be valid UTF-8.
Returns
---
#### out.Stderr()
method
```go
func (e *ExecOutput) Stderr() string
```
Captured standard error as a string.
Returns
---
#### out.StderrBytes()
method
```go
func (e *ExecOutput) StderrBytes() []byte
```
Captured standard error as raw bytes.
Returns
---
#### out.ExitCode()
method
```go
func (e *ExecOutput) ExitCode() int
```
The process's exit code, or `-1` if the guest did not report one (e.g. the process was killed by a signal).
Returns
---
#### out.Success()
method
```go
func (e *ExecOutput) Success() bool
```
Reports whether the command exited with code `0`.
Returns
bool
true if ExitCode() is 0.
## ExecSink methods
A write-only pipe to a running process's stdin, obtained from [`ExecHandle.TakeStdin`](#h-takestdin). Implements `io.WriteCloser`. `Write` and `Close` use `context.Background()` under the hood; for caller-controlled cancellation use [`WriteCtx`](#sink-writectx), or tear the session down via [`ExecHandle.Kill`](#h-kill) / [`Close`](#h-close).
---
#### sink.Write()
method
```go
func (sk *ExecSink) Write(p []byte) (int, error)
```
Send data to the process stdin. Implements `io.Writer`. Uses `context.Background()` internally, there is no way to cancel a stuck write through this method alone.
Parameters
p[]byte
Bytes to write to stdin.
Returns
int
Number of bytes written.
```go
h, err := sb.ExecStream(ctx, "cat", nil, m.WithExecStdinPipe())
if err != nil {
return err
}
defer h.Close()
sink := h.TakeStdin()
sink.Write([]byte("hello\n"))
sink.Close()
out, _ := h.Collect(ctx)
fmt.Print(out.Stdout()) // "hello\n"
```
---
#### sink.WriteCtx()
method
```go
func (sk *ExecSink) WriteCtx(ctx context.Context, p []byte) (int, error)
```
Like [`Write`](#sink-write), but with a caller-controlled context, so a stuck stdin write can be cancelled.
Parameters
ctxcontext.Context
Cancels the write.
p[]byte
Bytes to write to stdin.
Returns
int
Number of bytes written.
---
#### sink.Close()
method
```go
func (sk *ExecSink) Close() error
```
Close the stdin pipe, sending EOF to the process. Implements `io.Closer`.
```go
sink.Close()
```
## Types
---
### ExecOutput
struct
Returned by sb.Exec() · sb.Shell() · h.Collect()
The collected result of a command execution. A non-zero `ExitCode` is not treated as a Go error, callers inspect [`Success`](#out-success) or [`ExitCode`](#out-exitcode) explicitly, matching how `os/exec.Cmd.Output` works against a script that exits non-zero.
| Method | Returns | Description |
|--------|---------|-------------|
| [`Stdout()`](#out-stdout) | `string` | Captured stdout as a string |
| [`StdoutBytes()`](#out-stdoutbytes) | `[]byte` | Raw stdout bytes |
| [`Stderr()`](#out-stderr) | `string` | Captured stderr as a string |
| [`StderrBytes()`](#out-stderrbytes) | `[]byte` | Raw stderr bytes |
| [`ExitCode()`](#out-exitcode) | `int` | Exit code, or `-1` if the guest did not report one |
| [`Success()`](#out-success) | `bool` | `true` if `ExitCode()` is `0` |
---
### ExecHandle
struct
Returned by sb.ExecStream() · sb.ShellStream()
A live streaming exec session. Must be closed with [`Close`](#h-close) when done to release Rust-side resources. Not safe for concurrent use from multiple goroutines.
| Method | Returns | Description |
|--------|---------|-------------|
| [`ID()`](#h-id) | `(string, error)` | Session correlation id assigned by the guest agent |
| [`TakeStdin()`](#h-takestdin) | [`*ExecSink`](#execsink) | Take the stdin writer (single-take; only with `WithExecStdinPipe`) |
| [`Recv(ctx)`](#h-recv) | [`(*ExecEvent, error)`](#execevent) | Block until the next event arrives |
| [`Collect(ctx)`](#h-collect) | [`(*ExecOutput, error)`](#execoutput) | Drain remaining output into an `ExecOutput` |
| [`Wait(ctx)`](#h-wait) | `(int, error)` | Wait for exit, discarding output; returns the exit code |
| [`Kill(ctx)`](#h-kill) | `error` | Send SIGKILL |
| [`Signal(ctx, signal)`](#h-signal) | `error` | Send a Unix signal |
| [`Close()`](#h-close) | `error` | Release the Rust-side handle |
---
### ExecSink
type alias
Returned by h.TakeStdin()
```go
type ExecSink = ffi.ExecSink
```
A write-only pipe to a running process's stdin. Implements `io.WriteCloser`.
| Method | Returns | Description |
|--------|---------|-------------|
| [`Write(p)`](#sink-write) | `(int, error)` | Implements `io.Writer` |
| [`WriteCtx(ctx, p)`](#sink-writectx) | `(int, error)` | Write with explicit context |
| [`Close()`](#sink-close) | `error` | Send EOF and finalize |
---
### ExecEvent
struct
Returned by h.Recv()
One event from a streaming exec session. [`Kind`](#execeventkind) identifies which fields are populated.
| Field | Type | Description |
|-------|------|-------------|
| `Kind` | [`ExecEventKind`](#execeventkind) | Identifies which fields are populated |
| `PID` | `uint32` | Guest process id, set on `ExecEventStarted` |
| `Data` | `[]byte` | Chunk of stdout or stderr, set on `ExecEventStdout` / `ExecEventStderr` |
| `ExitCode` | `int` | Process exit code, set on `ExecEventExited` |
| `Failure` | [`*ExecFailure`](#execfailure) | Failure detail, set on `ExecEventFailed` and `ExecEventStdinError` |
---
### ExecEventKind
type alias
Field of ExecEvent
```go
type ExecEventKind = ffi.ExecEventKind
```
Identifies what an [`ExecEvent`](#execevent) carries.
| Constant | Description |
|----------|-------------|
| `ExecEventStarted` | Sent once when the guest process starts; `PID` is valid |
| `ExecEventStdout` | A chunk of stdout; `Data` is valid |
| `ExecEventStderr` | A chunk of stderr; `Data` is valid |
| `ExecEventExited` | The process exited; `ExitCode` is valid |
| `ExecEventFailed` | The user program never started (binary missing, permission denied, ...); `Failure` is valid and `ExitCode` is not meaningful |
| `ExecEventStdinError` | A stdin write failed; `Failure` is valid. Non-terminal: the process may still exit normally |
| `ExecEventDone` | All events have been consumed |
---
### ExecFailure
type alias
Field of ExecEvent
```go
type ExecFailure = ffi.ExecFailure
```
Structured detail about a failed-to-start exec, populated on `ExecEventFailed` and `ExecEventStdinError`. See [Error Handling](/sdk/errors#spawn-time-exec-failures) for the kinds it carries (`not_found`, `permission_denied`, etc.) and how to branch on them.
| Field | Type | Description |
|-------|------|-------------|
| `Kind` | `string` | Failure category, e.g. `not_found`, `permission_denied` |
| `Errno` | `*int` | Underlying errno, if known |
| `ErrnoName` | `string` | Symbolic errno name, if known |
| `Message` | `string` | Human-readable failure message |
| `Path` | `string` | Offending path, if applicable |
---
### ExecConfig
struct
Populated by ExecOption
Configures a single [`Exec`](#sb-exec) or [`ExecStream`](#sb-execstream) call. Most callers set fields through the `WithExec*` functional options; `ExecConfig` is exported for parity with the other SDKs' config types.
| Field | Type | Description |
|-------|------|-------------|
| `Cwd` | `string` | Working directory inside the guest |
| `Timeout` | `time.Duration` | Kill the process after this duration; sub-second precision is rounded up |
| `StdinPipe` | `bool` | Enable a stdin pipe; required for [`TakeStdin`](#h-takestdin) |
| `User` | `string` | Guest user (UID or name) |
| `Env` | `map[string]string` | Per-command environment variables |
---
### ExecOption
type
Accepted by sb.Exec() · sb.Shell() · sb.ExecStream() · sb.ShellStream()
```go
type ExecOption func(*ExecConfig)
```
A functional option that mutates an [`ExecConfig`](#execconfig). Construct them with the `WithExec*` functions below.
---
#### WithExecCwd()
option
```go
func WithExecCwd(path string) ExecOption
```
Set the working directory for a single command.
Parameters
pathstring
Absolute path inside the guest.
---
#### WithExecTimeout()
option
```go
func WithExecTimeout(d time.Duration) ExecOption
```
Set a per-command timeout. When exceeded, the guest terminates the process and the call returns an error with `Kind == ErrExecTimeout`. Sub-second precision rounds up to whole seconds; pass at least 1 second.
Parameters
dtime.Duration
Timeout duration, rounded up to whole seconds.
```go
out, err := sb.Shell(ctx, "long-running-task",
m.WithExecTimeout(30*time.Second))
if m.IsKind(err, m.ErrExecTimeout) {
log.Println("timed out")
}
```
---
#### WithExecStdinPipe()
option
```go
func WithExecStdinPipe() ExecOption
```
Enable a stdin pipe for the exec session, allowing data to be written via [`ExecHandle.TakeStdin`](#h-takestdin).
---
#### WithExecUser()
option
```go
func WithExecUser(user string) ExecOption
```
Run the command as the given guest user (UID or name).
Parameters
userstring
Guest user, as a UID or name.
---
#### WithExecEnv()
option
```go
func WithExecEnv(env map[string]string) ExecOption
```
Add per-command environment variables. Called repeatedly, maps merge; later keys overwrite earlier ones.
Parameters
envmap[string]string
Environment variables for this command.
```go
out, err := sb.Exec(ctx, "make", []string{"build"},
m.WithExecCwd("/app"),
m.WithExecEnv(map[string]string{"DEBUG": "1"}),
)
```