Run an agent in a sandbox

An agent session is a Claude Agent SDK instance running inside a sandbox. You send a prompt, the agent works autonomously — writing files, running commands, iterating on errors — and streams events back to your code. You own the sandbox and drive the loop directly: no deploy step, no hosting.

There are two ways to run agents on OpenComputer. This is the SDK path — you create a sandbox yourself and drive a Claude session inside it directly, owning the sandbox and the loop. If you’d instead like the platform to manage an agent definition for you — reached through persistent instances or ephemeral sessions, and connectable to messaging channels or a public API — see Hosted Agents (Hermes, OpenClaw).

import { Sandbox } from "@opencomputer/sdk";

const sandbox = await Sandbox.create();
const session = await sandbox.agent.start({
  prompt: "Create a Next.js app with a landing page",
  onEvent: (event) => console.log(`[${event.type}]`, event),
});

const exitCode = await session.done;
await sandbox.kill();

from opencomputer import Sandbox

sandbox = await Sandbox.create()
session = await sandbox.agent.start(
    prompt="Create a Next.js app with a landing page",
    on_event=lambda event: print(f"[{event.type}]", event),
)

exit_code = await session.wait()
await sandbox.kill()

How It Works

The SDK spawns the Claude Agent SDK inside the sandbox VM as a regular process. Claude gets bash and file tools, then works in a think → act → observe loop. Events stream back to your code over WebSocket as JSON lines. The agent has full access to the sandbox filesystem, network, and shell — the same environment you’d get with sandbox.exec or oc shell.

Starting an Agent

sandbox.agent.start() creates an agent session and returns immediately. Events arrive via callbacks.

Parameters

Parameter	Type	Description
`prompt`	string	Initial prompt for the agent
`model`	string	Claude model (default: `claude-sonnet-4-20250514`)
`systemPrompt`	string	System prompt
`allowedTools`	string[]	Restrict which tools the agent can use
`permissionMode`	string	Permission mode for tool use
`maxTurns`	number	Maximum conversation turns (default: 50)
`cwd`	string	Working directory inside the sandbox
`mcpServers`	object	MCP server configuration (see Tools)
`onEvent`	callback	Called for each event
`onError`	callback	Called on error

TypeScript only:

Parameter	Type	Description
`resume`	string	Resume a previous session by ID
`onExit`	callback	Called when agent process exits
`onScrollbackEnd`	callback	Called when scrollback replay completes

Python uses snake_case: system_prompt, allowed_tools, permission_mode, max_turns, mcp_servers, on_event, on_error.

AgentSession

The returned session object lets you interact with the running agent.

Method	TypeScript	Python	Description
Send follow-up	`sendPrompt(text)`	`send_prompt(text)`	Send a follow-up prompt
Wait for completion	`await session.done`	`await session.wait()`	Returns exit code
Collect all events	—	`await session.collect_events()`	Collect events until exit
Interrupt	`session.interrupt()`	`session.interrupt()`	Stop the current turn
Reconfigure	`session.configure(opts)`	`session.configure(...)`	Update model, tools, cwd
Kill	`await session.kill()`	`await session.kill()`	Terminate the process (SIGKILL)
Close	`session.close()`	`await session.close()`	Close WebSocket connection

Property	TypeScript	Python
Session ID	`session.sessionId`	`session.session_id`

Attaching to an Existing Session

Reconnect to a running agent session to resume receiving events:

const session = await sandbox.agent.attach(sessionId, {
  onEvent: (event) => console.log(event),
});

session = await sandbox.agent.attach(
    session_id,
    on_event=lambda event: print(event),
)

Listing Sessions

const sessions = await sandbox.agent.list();
// [{ sessionID, sandboxID, running, startedAt }]

sessions = await sandbox.agent.list()
# [AgentSessionInfo(session_id, sandbox_id, running, started_at)]

Events

Understanding the event stream

Tools

Configure tools and MCP servers

Multi-turn

Follow-ups, resume, session management

Full reference: TypeScript SDK · Python SDK · HTTP API.

Getting Started

Sandboxes

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Run an agent in a sandbox

How It Works

Starting an Agent

Parameters

AgentSession

Attaching to an Existing Session

Listing Sessions

Events

Tools

Multi-turn

​How It Works

​Starting an Agent

​Parameters

​AgentSession

​Attaching to an Existing Session

​Listing Sessions

Events

Tools

Multi-turn

How It Works

Starting an Agent

Parameters

AgentSession

Attaching to an Existing Session

Listing Sessions