Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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)
    }
}
​
cmd
string
required
Shell command to execute inside the sandbox.
​
WithRunEnvs
map[string]string
Additional environment variables for this command.
​
WithUser
string
default:"server default"
Unix user to run the command as. Server defaults to "user" when not specified.
​
WithCwd
string
Working directory. Defaults to the user’s home directory.
​
WithOnStdout
func(string)
Callback invoked for each line of stdout after the command completes.
​
WithOnStderr
func(string)
Callback invoked for each line of stderr after the command completes.
​
WithStdin
(no argument)
Enables stdin for the command, allowing data to be sent via SendStdin.
​
WithRunTimeout
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)
​
cmd
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")
​
data
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"