Skip to main content
Accessed via sandbox.agent.

​
sandbox.agent.start(opts?)

Start an agent session. HTTP API →
​
prompt
string
Initial prompt
​
model
string
Claude model
​
systemPrompt
string
System prompt
​
allowedTools
string[]
Restrict tools
​
permissionMode
string
Permission mode
​
maxTurns
number
default:"50"
Max turns
​
cwd
string
Working directory
​
mcpServers
Record<string, McpServerConfig>
MCP servers
​
resume
string
Resume session ID
​
onEvent
(event: AgentEvent) => void
Event callback
​
onError
(data: string) => void
Stderr callback
​
onExit
(exitCode: number) => void
Exit callback
​
onScrollbackEnd
() => void
Scrollback done callback
Returns: Promise<AgentSession> 
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<AgentSession>

​
sandbox.agent.list()

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

​
AgentSession

MemberTypeDescription
sessionIdstringSession ID
donePromise<number>Resolves with exit code
sendPrompt(text)methodSend follow-up prompt
interrupt()methodInterrupt current turn
configure(config)methodUpdate agent configuration
kill(signal?)Promise<void>Kill agent process
close()methodClose WebSocket

​
Types

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

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