Commands

import "github.com/declaw-ai/declaw-go"

sbx.Commands is the *Commands sub-object available on every Sandbox instance. It provides methods to run foreground commands, launch background processes, and list running processes.

`sbx.Commands.Run()`

Run a command and block until it completes, returning stdout, stderr, and exit code.

result, err := sbx.Commands.Run(ctx, "echo hello")
fmt.Println(result.Stdout)   // "hello\n"
fmt.Println(result.ExitCode) // 0

If the command exits with a non-zero code, Run returns both the *CommandResult and a *CommandExitError. You can inspect the result even on failure:

result, err := sbx.Commands.Run(ctx, "exit 1")
if err != nil {
    var exitErr *declaw.CommandExitError
    if errors.As(err, &exitErr) {
        fmt.Println("Exit code:", exitErr.ExitCode)
        fmt.Println("Stderr:", exitErr.Stderr)
    }
}

string

required

Shell command to execute inside the sandbox.

map[string]string

Additional environment variables for this command.

string

default:"server default"

Unix user to run the command as. Server defaults to "user" when not specified.

string

Working directory. Defaults to the user’s home directory.

func(string)

Callback invoked for each line of stdout after the command completes.

func(string)

Callback invoked for each line of stderr after the command completes.

(no argument)

Enables stdin for the command, allowing data to be sent via SendStdin.

time.Duration

Maximum time to wait for the command to complete.

Returns (*CommandResult, error)

`sbx.Commands.Start()`

Start a command in the background and return a *CommandHandle immediately.

handle, err := sbx.Commands.Start(ctx, "sleep 30")
fmt.Println("PID:", handle.PID)

string

required

Shell command to execute.

Options are the same as Run(). Returns (*CommandHandle, error)

`sbx.Commands.List()`

List all running processes in the sandbox.

procs, err := sbx.Commands.List(ctx)
for _, p := range procs {
    fmt.Println(p.PID, p.Cmd)
}

Returns ([]ProcessInfo, error)

CommandHandle

CommandHandle is returned by sbx.Commands.Start(). It provides methods to wait for or kill the process.

`handle.Wait()`

Block until the background command completes.

handle, err := sbx.Commands.Start(ctx, "python3 script.py")
if err != nil {
    log.Fatal(err)
}

// Later, wait for it
result, err := handle.Wait(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout)

Returns (*CommandResult, error) — returns *CommandExitError on non-zero exit.

`handle.Kill()`

Kill the process by PID.

err := handle.Kill(ctx)

`handle.PID`

Type int — the process ID.

`handle.SendStdin()`

Write data to the stdin of a running background process.

Not yet implemented. Returns an error until server-side support is available.

err := handle.SendStdin(ctx, "hello\n")

string

required

Data to write to stdin. Include \n for newlines.

Returns error

Data models

`CommandResult`

type CommandResult struct {
    PID      int
    ExitCode int
    Stdout   string
    Stderr   string
}

`ProcessInfo`

type ProcessInfo struct {
    PID   int
    Cmd   string
    IsPty bool
    Envs  map[string]string
}

Examples

Run with environment variables

result, err := sbx.Commands.Run(ctx, "echo $MY_SECRET",
    declaw.WithRunEnvs(map[string]string{"MY_SECRET": "s3cr3t"}),
)

Run with working directory

result, err := sbx.Commands.Run(ctx, "pwd",
    declaw.WithCwd("/tmp"),
)
// result.Stdout: "/tmp\n"

Capture output with callbacks

var lines []string
result, err := sbx.Commands.Run(ctx, "ls -la /tmp",
    declaw.WithOnStdout(func(line string) {
        lines = append(lines, line)
    }),
)
fmt.Printf("Captured %d lines\n", len(lines))

Background process

handle, err := sbx.Commands.Start(ctx, "python3 -c \"import time; time.sleep(5); print('done')\"")
if err != nil {
    log.Fatal(err)
}

// Do other work...

result, err := handle.Wait(ctx)
fmt.Println(result.Stdout) // "done\n"

Python SDK

TypeScript SDK

Go SDK

`sbx.Commands.Run()`

`sbx.Commands.Start()`

`sbx.Commands.List()`

CommandHandle

`handle.Wait()`

`handle.Kill()`

`handle.PID`

`handle.SendStdin()`

Data models

`CommandResult`

`ProcessInfo`

Examples

Run with environment variables

Run with working directory

Capture output with callbacks

Background process

​sbx.Commands.Run()

​sbx.Commands.Start()

​sbx.Commands.List()

​CommandHandle

​handle.Wait()

​handle.Kill()

​handle.PID

​handle.SendStdin()

​Data models

​CommandResult

​ProcessInfo

​Examples

​Run with environment variables

​Run with working directory

​Capture output with callbacks

​Background process

`sbx.Commands.Run()`

`sbx.Commands.Start()`

`sbx.Commands.List()`

CommandHandle

`handle.Wait()`

`handle.Kill()`

`handle.PID`

`handle.SendStdin()`

Data models

`CommandResult`

`ProcessInfo`

Examples

Run with environment variables

Run with working directory

Capture output with callbacks

Background process