Exec

Accessed via sandbox.exec.

`await sandbox.exec.run(command, ...)`

Run a command synchronously via sh -c. HTTP API →

command

str

required

Shell command

timeout

int

default:"60"

Timeout in seconds

env

dict[str, str]

Environment variables

cwd

str

Working directory

Returns: ProcessResult

result = await sandbox.exec.run("npm test", cwd="/app")

`await sandbox.exec.start(command, ...)`

Start a long-running command with streaming I/O. HTTP API →

command

str

required

Command

args

list[str]

Arguments

env

dict[str, str]

Environment variables

cwd

str

Working directory

timeout

int

Timeout in seconds

max_run_after_disconnect

int

Seconds to keep running after disconnect

on_stdout

Callable[[bytes], None]

Stdout callback

on_stderr

Callable[[bytes], None]

Stderr callback

on_exit

Callable[[int], None]

Exit callback

Returns: ExecSession

session = await sandbox.exec.start(
    "node", args=["server.js"], cwd="/app",
    on_stdout=lambda b: print(b.decode(), end=""),
    on_exit=lambda code: print(f"exited {code}"),
)
exit_code = await session.done

`await sandbox.exec.background(command, ...)`

Alias for start. Same signature, same return type. Use when the intent is “run this in the background and observe it”.

server = await sandbox.exec.background("npm", args=["run", "dev"])

`await sandbox.exec.shell(...)`

Open a stateful shell session. Subsequent .run() calls share the same bash process, so cwd, exported env vars, and shell functions persist — the ergonomics of a terminal tab. Backed by a long-running bash --noprofile --norc session. Foreground-only: concurrent .run() raises ShellBusyError.

cwd

str

Initial working directory

env

dict[str, str]

Initial environment variables

Returns: Shell

sh = await sandbox.exec.shell(cwd="/app")

await sh.run("npm install")
await sh.run("export NODE_ENV=test")
r = await sh.run("npm test", on_stdout=lambda b: print(b.decode(), end=""))
print(r.exit_code)

await sh.close()

Shell

Member	Type	Description
`session_id`	`str`	Underlying exec session ID
`run(cmd, on_stdout=?, on_stderr=?)`	`ProcessResult`	Run a command, blocking until it exits
`close()`	`None`	Write `exit` and wait for bash to terminate

Per-call cwd, env, and timeout are intentionally not supported in v1. Use inline shell syntax (cd /x && cmd, FOO=bar cmd) — the shell state carries across calls.

Errors:

ShellBusyError — another run() is in flight (shell is foreground-only).
ShellClosedError — bash has exited (explicit close(), a command ran exit, or the session dropped).

`await sandbox.exec.attach(session_id, ...)`

Reconnect to a running exec session over WebSocket.

session_id

str

required

Session ID

on_stdout

Callable[[bytes], None]

Stdout callback

on_stderr

Callable[[bytes], None]

Stderr callback

on_exit

Callable[[int], None]

Exit callback

on_scrollback_end

Callable[[], None]

Scrollback replay done

Returns: ExecSession

`await sandbox.exec.list()`

List all exec sessions. HTTP API → Returns: list[ExecSessionInfo]

`await sandbox.exec.kill(session_id, signal=9)`

Kill an exec session. HTTP API → Returns: None

ExecSession

Member	Type	Description
`session_id`	`str`	Session ID
`done`	`asyncio.Future[int]`	Resolves with exit code
`send_stdin(data)`	coroutine	Send input (`str` or `bytes`)
`kill(signal=9)`	coroutine	Kill process
`close()`	coroutine	Detach WebSocket (process keeps running)

Types

ProcessResult

@dataclass
class ProcessResult:
    exit_code: int
    stdout: str
    stderr: str

ExecSessionInfo

@dataclass
class ExecSessionInfo:
    session_id: str
    sandbox_id: str
    command: str
    args: list[str]
    running: bool
    exit_code: int | None
    started_at: str
    attached_clients: int

Getting Started

Sandboxes

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

`await sandbox.exec.run(command, ...)`

`await sandbox.exec.start(command, ...)`

`await sandbox.exec.background(command, ...)`

`await sandbox.exec.shell(...)`

Shell

`await sandbox.exec.attach(session_id, ...)`

`await sandbox.exec.list()`

`await sandbox.exec.kill(session_id, signal=9)`

ExecSession

Types

​await sandbox.exec.run(command, ...)

​await sandbox.exec.start(command, ...)

​await sandbox.exec.background(command, ...)

​await sandbox.exec.shell(...)

​Shell

​await sandbox.exec.attach(session_id, ...)

​await sandbox.exec.list()

​await sandbox.exec.kill(session_id, signal=9)

​ExecSession

​Types

`await sandbox.exec.run(command, ...)`

`await sandbox.exec.start(command, ...)`

`await sandbox.exec.background(command, ...)`

`await sandbox.exec.shell(...)`

Shell

`await sandbox.exec.attach(session_id, ...)`

`await sandbox.exec.list()`

`await sandbox.exec.kill(session_id, signal=9)`

ExecSession

Types