Process, exec & background sessions

Run a command

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:

# 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 — boxkite-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

In addition to default tools, you can configure your sandbox toolset with advanced execution engines:

• 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 BOXKITE_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.