Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

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.
​
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

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

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

@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