Capability

Process, exec & background sessions

Two ways to run a command in a sandbox. exec runs a shell command synchronously and hands back its exit code, stdout, and stderr once it finishes — good for anything short-lived. For something longer-running (a dev server, a background build, a watcher), start a background process session instead: it keeps running while your agent polls its output, writes to its stdin, and stops it when done.

Run a command

exec.py

result = sb.exec("python3 -c 'print(1 + 1)'")
print(result["stdout"])   # "2\n"
print(result["exit_code"])

timeout defaults to 30 seconds; the CLI and MCP tool both expose it, the SDKs accept it as a keyword argument. An optional description (SDKs only) is purely informational, useful for audit logging.

Background process sessions

Start a tracked background process that survives beyond a single request (e.g. dev server, background builder, watcher, or interactive REPL). Poll its stdout/stderr since a given byte offset, write directly to its stdin, or stop it early:

processes.py

# Start a background process (returns process info with process_id)
proc = sb.start_process("npm run dev", description="dev-server", max_runtime_seconds=3600)
pid = proc["process_id"]

# Poll output since offset 0 (returns status, exit_code, stdout_chunk, next_offset)
out = sb.get_process_output(pid, since_offset=0)
print(out["stdout_chunk"])

# Write to stdin (e.g., answering prompts)
sb.send_process_input(pid, data="yes\n")

# List all background processes in this session
procs = sb.list_processes()

# Stop the process early (SIGTERM then SIGKILL)
sb.stop_process(pid)

Background processes are a Python/JS SDK capability today — boxxkite-mcp's tool set doesn't expose them yet (see the MCP server guide ↗ for what it does expose).

Opt-in features: PTY terminal and Node interpreter

Beyond the default tools, two advanced execution engines are available as opt-in additions to your sandbox toolset:

pty_exec (Agent PTY) — Run a command behind a real pseudo-terminal. Useful for programs that check isatty() and fail with regular stdout redirection. Double-gated: the sidecar needs BOXXKITE_AGENT_PTY_ENABLED=true, and the tool itself is activated via enable_agent_pty=true.
node_interpreter — The Node.js counterpart to the persistent Python interpreter. Keeps a Node.js process alive across tool calls in the session. Activated via enable_node_interpreter=true.

Unrestricted by default

There is no argument validation at this layer — execruns whatever command it's given. If your account has a persisted command allowlist ↗ set, it's enforced here; otherwise every command is allowed, relying entirely on the sandbox pod's own isolation.