> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an agent in a sandbox

> Run Claude inside a sandbox you control, with the SDK

An agent session is a Claude Agent SDK instance running inside a [sandbox](/sandboxes/overview). 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.

<Info>
  **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](/agents-api/overview) (Hermes, OpenClaw).
</Info>

<CodeGroup>
  ```typescript TypeScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## 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](/agents/tools)) |
| `onEvent`        | callback  | Called for each [event](/agents/events)               |
| `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 |

<Note>
  Python uses snake\_case: `system_prompt`, `allowed_tools`, `permission_mode`, `max_turns`, `mcp_servers`, `on_event`, `on_error`.
</Note>

## 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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const session = await sandbox.agent.attach(sessionId, {
    onEvent: (event) => console.log(event),
  });
  ```

  ```python Python theme={null}
  session = await sandbox.agent.attach(
      session_id,
      on_event=lambda event: print(event),
  )
  ```
</CodeGroup>

## Listing Sessions

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sessions = await sandbox.agent.list();
  // [{ sessionID, sandboxID, running, startedAt }]
  ```

  ```python Python theme={null}
  sessions = await sandbox.agent.list()
  # [AgentSessionInfo(session_id, sandbox_id, running, started_at)]
  ```
</CodeGroup>

<CardGroup cols={3}>
  <Card title="Events" icon="stream" href="/agents/events">
    Understanding the event stream
  </Card>

  <Card title="Tools" icon="wrench" href="/agents/tools">
    Configure tools and MCP servers
  </Card>

  <Card title="Multi-turn" icon="comments" href="/agents/multi-turn">
    Follow-ups, resume, session management
  </Card>
</CardGroup>

<Tip>
  Full reference: [TypeScript SDK](/reference/typescript-sdk#agent) · [Python SDK](/reference/python-sdk#agent) · [HTTP API](/reference/api#agent-sessions).
</Tip>