Commands

from declaw import Sandbox, CommandResult, CommandHandle, ProcessInfo

sbx.commands is the Commands sub-module available on every Sandbox instance. It provides methods to run foreground commands, launch background processes, stream real-time output, and interact with running processes via stdin.

`sbx.commands.run()`

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

result = sbx.commands.run("echo hello")
print(result.stdout)   # "hello\n"
print(result.exit_code)  # 0

Pass background=True to launch the command in the background and receive a CommandHandle immediately.

handle: CommandHandle = sbx.commands.run("sleep 30", background=True)
print("PID:", handle.pid)

str

required

Shell command to execute inside the sandbox.

bool

default:"False"

When True, the API returns immediately and the method returns a CommandHandle. When False (default), the method blocks and returns a CommandResult.

dict[str, str] | None

default:"None"

Additional environment variables for this command.

str

default:"'user'"

Unix user to run the command as inside the sandbox.

str | None

default:"None"

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

Callable[[str], None] | None

default:"None"

Callback invoked for each line of stdout after the command completes. For real-time streaming, use run_stream() instead.

Callable[[str], None] | None

default:"None"

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

bool | None

default:"None"

Whether to attach a stdin pipe to the process.

float | None

default:"60"

Maximum time in seconds to wait for the command to complete.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns CommandResult when background=False, CommandHandle when background=True.

`sbx.commands.run_stream()`

Run a command with real-time SSE streaming. Callbacks are invoked as each chunk of output arrives, before the command completes.

def on_line(line: str) -> None:
    print(line, end="", flush=True)

result = sbx.commands.run_stream(
    "python3 -u long_script.py",
    on_stdout=on_line,
    on_stderr=on_line,
)
print("Exit code:", result.exit_code)

str

required

Shell command to execute.

Callable[[str], None] | None

default:"None"

Called in real-time for each stdout chunk as it arrives from the SSE stream.

Callable[[str], None] | None

default:"None"

Called in real-time for each stderr chunk as it arrives.

dict[str, str] | None

default:"None"

Environment variables for the command.

str

default:"'user'"

Unix user to run as.

str | None

default:"None"

Working directory.

float | None

default:"60"

Command execution timeout in seconds.

Returns CommandResult with the accumulated stdout and stderr after the command finishes.

`sbx.commands.list()`

List all running (background) processes in the sandbox.

processes: list[ProcessInfo] = sbx.commands.list()
for p in processes:
    print(p.pid, p.cmd)

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns list[ProcessInfo]

`sbx.commands.kill()`

Send SIGKILL to a running process by PID.

killed = sbx.commands.kill(pid=1234)

int

required

Process ID of the command to kill.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns bool — True if the process was killed, False if it was already dead.

`sbx.commands.send_stdin()`

Write data to the stdin of a running background process.

handle = sbx.commands.run("cat", background=True)
sbx.commands.send_stdin(handle.pid, "hello\n")
sbx.commands.send_stdin(handle.pid, "world\n")

int

required

Process ID of the running command.

str

required

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

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns None

`sbx.commands.connect()`

Create a CommandHandle for an already-running process by PID without making an API call. Useful when you have a PID from list() and want to wait on it.

handle = sbx.commands.connect(pid=5678)
result = handle.wait()

int

required

Process ID of the running command.

Returns CommandHandle

CommandHandle

CommandHandle is returned by sbx.commands.run(background=True) and sbx.commands.connect(). It provides methods to wait for or kill the process.

handle = sbx.commands.run("python3 script.py", background=True)

# Later, wait for it to finish
result = handle.wait(
    on_stdout=lambda line: print("OUT:", line),
    on_stderr=lambda line: print("ERR:", line),
)

`handle.wait()`

Wait for the background command to complete.

Callable[[str], None] | None

default:"None"

Called for each stdout line after the command completes.

Callable[[str], None] | None

default:"None"

Called for each stderr line after the command completes.

Returns CommandResult. Raises CommandExitException if the exit code is non-zero.

`handle.kill()`

Kill the process. Returns bool

`handle.pid`

Type int — the process ID.

Data models

`CommandResult`

@dataclass
class CommandResult:
    stdout: str = ""
    stderr: str = ""
    exit_code: int = 0

`ProcessInfo`

@dataclass
class ProcessInfo:
    pid: int
    cmd: str
    is_pty: bool = False
    envs: dict[str, str] = field(default_factory=dict)

`Stdout` / `Stderr`

Line-level output models used when streaming output with timestamps:

@dataclass
class Stdout:
    line: str
    timestamp: float | None = None

@dataclass
class Stderr:
    line: str
    timestamp: float | None = None

Examples

Run a Python script

result = sbx.commands.run(
    "python3 -c \"import sys; print(sys.version)\"",
    timeout=10,
)
print(result.stdout)

Run with environment variables

result = sbx.commands.run(
    "echo $MY_SECRET",
    envs={"MY_SECRET": "s3cr3t"},
)

Stream long-running output

lines = []

result = sbx.commands.run_stream(
    "for i in $(seq 1 100); do echo $i; sleep 0.05; done",
    on_stdout=lines.append,
)
print(f"Received {len(lines)} lines")

Background process with stdin

import time

handle = sbx.commands.run("python3 -c \"import sys; [print(l.strip()+'!') for l in sys.stdin]\"", background=True)
time.sleep(0.1)
sbx.commands.send_stdin(handle.pid, "hello\nworld\n")
result = handle.wait()
print(result.stdout)  # "hello!\nworld!\n"

Python SDK

TypeScript SDK

Go SDK

`sbx.commands.run()`

`sbx.commands.run_stream()`

`sbx.commands.list()`

`sbx.commands.kill()`

`sbx.commands.send_stdin()`

`sbx.commands.connect()`

CommandHandle

`handle.wait()`

`handle.kill()`

`handle.pid`

Data models

`CommandResult`

`ProcessInfo`

`Stdout` / `Stderr`

Examples

Run a Python script

Run with environment variables

Stream long-running output

Background process with stdin

​sbx.commands.run()

​sbx.commands.run_stream()

​sbx.commands.list()

​sbx.commands.kill()

​sbx.commands.send_stdin()

​sbx.commands.connect()

​CommandHandle

​handle.wait()

​handle.kill()

​handle.pid

​Data models

​CommandResult

​ProcessInfo

​Stdout / Stderr

​Examples

​Run a Python script

​Run with environment variables

​Stream long-running output

​Background process with stdin

`sbx.commands.run()`

`sbx.commands.run_stream()`

`sbx.commands.list()`

`sbx.commands.kill()`

`sbx.commands.send_stdin()`

`sbx.commands.connect()`

CommandHandle

`handle.wait()`

`handle.kill()`

`handle.pid`

Data models

`CommandResult`

`ProcessInfo`

`Stdout` / `Stderr`

Examples

Run a Python script

Run with environment variables

Stream long-running output

Background process with stdin