Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Exec

Accessed via sandbox.exec.

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

Run a command synchronously via sh -c. HTTP API →
body commandstrrequired
Shell command
body timeoutintdefault: 60
Timeout in seconds
body envdict[str, str]
Environment variables
body cwdstr
Working directory
Returns: ProcessResult
python
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 →
body commandstrrequired
Command
body argslist[str]
Arguments
body envdict[str, str]
Environment variables
body cwdstr
Working directory
body timeoutint
Timeout in seconds
body max_run_after_disconnectint
Seconds to keep running after disconnect
body on_stdoutCallable[[bytes], None]
Stdout callback
body on_stderrCallable[[bytes], None]
Stderr callback
body on_exitCallable[[int], None]
Exit callback
Returns: ExecSession
python
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".
python
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.
body cwdstr
Initial working directory
body envdict[str, str]
Initial environment variables
Returns: Shell
python
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

MemberTypeDescription
session_idstrUnderlying exec session ID
run(cmd, on_stdout=?, on_stderr=?)ProcessResultRun a command, blocking until it exits
close()NoneWrite 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.
body session_idstrrequired
Session ID
body on_stdoutCallable[[bytes], None]
Stdout callback
body on_stderrCallable[[bytes], None]
Stderr callback
body on_exitCallable[[int], None]
Exit callback
body on_scrollback_endCallable[[], 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

MemberTypeDescription
session_idstrSession ID
doneasyncio.Future[int]Resolves with exit code
send_stdin(data)coroutineSend input (str or bytes)
kill(signal=9)coroutineKill process
close()coroutineDetach WebSocket (process keeps running)

Types

ProcessResult
python
@dataclass
class ProcessResult:
    exit_code: int
    stdout: str
    stderr: str
ExecSessionInfo
python
@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