Sandbox agent

The in-sandbox agent (sandbox.agent, exported as SandboxAgent) is a low-level primitive and is deprecated. For most use cases prefer managed Durable Agent Sessions — the OpenComputer client gives you durable, streamable, steerable sessions without managing the sandbox yourself.

Accessed via sandbox.agent.

`sandbox.agent.start(opts?)`

Start an agent session. HTTP API →

string

Initial prompt

string

Claude model

string

System prompt

string[]

Restrict tools

string

Permission mode

number

default:"50"

Max turns

string

Working directory

Record<string, McpServerConfig>

MCP servers

string

Resume session ID

(event: SandboxAgentEvent) => void

Event callback

(data: string) => void

Stderr callback

(exitCode: number) => void

Exit callback

() => void

Scrollback done callback

Returns: Promise<SandboxAgentSession>

const session = await sandbox.agent.start({
  prompt: "Build a todo app",
  onEvent: (e) => console.log(e.type),
});

`sandbox.agent.attach(sessionId, opts?)`

Reconnect to a running agent session. Accepts onEvent, onError, onExit, onScrollbackEnd. Returns: Promise<SandboxAgentSession>

`sandbox.agent.list()`

List all agent sessions. HTTP API → Returns: Promise<SandboxAgentSessionInfo[]>

SandboxAgentSession

Member	Type	Description
`sessionId`	`string`	Session ID
`done`	`Promise<number>`	Resolves with exit code
`sendPrompt(text)`	method	Send follow-up prompt
`interrupt()`	method	Interrupt current turn
`configure(config)`	method	Update agent configuration
`kill(signal?)`	`Promise<void>`	Kill agent process
`close()`	method	Close WebSocket

Types

SandboxAgentEvent

interface SandboxAgentEvent {
  type: string;
  [key: string]: unknown;
}

McpServerConfig

interface McpServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

⌘I

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Self-hosting

`sandbox.agent.start(opts?)`

`sandbox.agent.attach(sessionId, opts?)`

`sandbox.agent.list()`

SandboxAgentSession

Types

​sandbox.agent.start(opts?)

​sandbox.agent.attach(sessionId, opts?)

​sandbox.agent.list()

​SandboxAgentSession

​Types

`sandbox.agent.start(opts?)`

`sandbox.agent.attach(sessionId, opts?)`

`sandbox.agent.list()`

SandboxAgentSession

Types