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

# Runtimes

> Runtime engine selected per agent

A **runtime** executes the agent loop: provider SDK, model calls, and tool use. You pick one per agent with `runtime`; it defaults to `claude`. The model is separate configuration, so an agent is a runtime, a `provider/model`, and a model source — **Managed** (billed to your OpenComputer credits, no key) or a matching [credential](/agent-sessions/credentials).

| Runtime                        | Models                                                                                           | Credential                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------- |
| `claude`                       | `anthropic/…` (e.g. `anthropic/claude-opus-4-8`)                                                 | Managed, or an Anthropic key |
| `codex`                        | `openai/…` (e.g. `openai/gpt-5-codex`)                                                           | Managed, or an OpenAI key    |
| `pi`                           | `anthropic/…` today — the runtime is provider-agnostic by construction; more providers land next | Managed, or an Anthropic key |
| `flue` <sup>experimental</sup> | `anthropic/…` today, declared by your [Flue](/agent-sessions/flue) app                           | Managed                      |

For the built-in runtimes, `model` is passed straight through to the provider. The **`provider/` prefix** is validated against the runtime; an unknown provider model fails on the first turn. A [session](/agent-sessions/sessions#model) can override the model for one run. Flue instead declares its model in the app and `agent.toml`, and rejects per-session overrides. Common choices:

* **`claude`:** `anthropic/claude-sonnet-5` (default, balanced), `anthropic/claude-opus-4-8` (most capable), `anthropic/claude-fable-5`, `anthropic/claude-haiku-4-5` (fastest/cheapest).
* **`codex`:** `openai/gpt-5-codex`.
* **`pi`:** the `anthropic/…` catalog above. The runtime itself is provider-agnostic; additional providers are next.
* **`flue`** (experimental): an `anthropic/…` model declared in your app and routed through Managed access. See [Run Flue agents](/agent-sessions/flue).

Sessions, [events](/agent-sessions/events), [steering](/agent-sessions/messaging), and [webhooks](/agent-sessions/webhooks) share the same consumer API across runtimes. Execution, tools, persistence, and recovery depend on the runtime. `runtime` is fixed once the agent exists; to switch engines, create a new agent.

## `claude`

The managed Claude agent loop (Claude Agent SDK / Claude Code). It works in a sandbox through remote tools, streams its steps into the session as events, and runs Claude models on your [Anthropic key](/agent-sessions/credentials).

```http theme={null}
POST https://api.opencomputer.dev/v3/agents
Authorization: Bearer $OPENCOMPUTER_API_KEY
Content-Type: application/json

{
  "name": "reviewer",
  "runtime": "claude",
  "model": "anthropic/claude-opus-4-8",
  "prompt": "Review code in the sandbox. Run tests. Explain risks.",
  "key": "sk-ant-..."
}
```

## `codex`

The managed Codex agent loop (OpenAI Codex SDK). It runs OpenAI models on your [OpenAI key](/agent-sessions/credentials), and drives the same sandbox tools and event stream as `claude` — only the engine and the provider change.

```http theme={null}
POST https://api.opencomputer.dev/v3/agents
Authorization: Bearer $OPENCOMPUTER_API_KEY
Content-Type: application/json

{
  "name": "reviewer",
  "runtime": "codex",
  "model": "anthropic/claude-sonnet-5",
  "prompt": "Review code in the sandbox. Run tests. Explain risks.",
  "key": "sk-..."
}
```

## `pi`

The [pi](https://github.com/earendil-works/pi) coding agent (MIT). `pi` is provider-independent by design: it drives whatever provider the model's `provider/` prefix names. Today it ships with `anthropic/…` models, on Managed billing or your Anthropic key; additional providers land next. Sandbox tools, the event stream, steering, and recovery are the same as the other built-in runtimes.

```http theme={null}
POST https://api.opencomputer.dev/v3/agents
Authorization: Bearer $OPENCOMPUTER_API_KEY
Content-Type: application/json

{
  "name": "reviewer",
  "runtime": "pi",
  "model": "anthropic/claude-sonnet-5",
  "prompt": "Review code in the sandbox. Run tests. Explain risks.",
  "credential": "managed"
}
```

The provider is taken from the model's `provider/` prefix — so as more providers land, switching provider is just a different `model` on the same `pi` agent, not a separate runtime.

## `flue` <sup>experimental</sup>

Unlike the runtimes above, `flue` does not run a platform-provided coding agent. It
runs **your compiled Flue app** as an agent Worker, with one Durable Object
instance holding each session's conversation. OpenComputer durably accepts
input, dispatches turns, routes managed model calls, and projects Flue's
durable updates into the shared event log.

A Flue agent has no Linux sandbox by default. Add `ocSandbox` only when the
agent needs shell or file operations; the first real operation creates it.
This different hosting and recovery model is explained in
[How Flue differs from the built-in runtimes](/agent-sessions/flue#how-flue-differs-from-the-built-in-runtimes).

The runtime, model, and credential have to agree. `claude` needs an `anthropic/…` model and an Anthropic key; `codex` needs an `openai/…` model and an OpenAI key; `pi` runs `anthropic/…` models today and needs an Anthropic key (or Managed). A mismatch is rejected when you create the agent, with a clear error — so a session never starts on a broken pairing. See [model credentials](/agent-sessions/credentials).

## Built-in runtime architecture

The remainder of this page describes `claude`, `codex`, and `pi`. Flue uses the
Worker and Durable Object architecture described on the [Flue page](/agent-sessions/flue).

The model is configuration, not part of the runtime image. The provider is always taken from the model's `provider/` prefix, never from the runtime — a runtime only declares which providers it can drive: `claude` and `pi` drive Anthropic today (`pi` is built to drive any provider — more land next), `codex` drives OpenAI. You choose the exact `provider/model` and key.

A runtime has two components:

* the **brain**, a resident server around the provider's agent SDK;
* the **adapter**, managed by OpenComputer, which connects that brain to the durable session log.

The brain knows the SDK, the model, the prompt, its resumable state directory, and the sandbox tools exposed to it. It does **not** write OpenComputer events directly and does not call the sandbox API itself. The adapter reads new input from the [event log](/agent-sessions/events), sends a bounded turn to the brain, translates the brain's stream into session events, handles fencing/idempotency, and only declares the turn done after committed output is durable.

The built-in runtimes are built this way. See [example runtimes](https://github.com/diggerhq/oc-runtime-examples) for `claude` and `codex` brain servers side by side, and [custom runtimes](/agent-sessions/custom-runtimes) in Labs for the same brain/adapter contract applied to your own runtime implementation.

A runtime also **starts fast**: the engine is prepared ahead of time and baked into the image, so a new or recreated session doesn't wait on a per-session download before its first step.

### Brain and hands

The runtime runs the agent loop in its **own per-session sandbox** (the *brain*). The agent's file and shell tools don't run there — they run in a **separate sandbox** (the *hands*) exposed to the brain through tools, so commands and file edits stay isolated from the model loop. The brain carries the [sealed model key](/agent-sessions/credentials) (egress-allowlisted to the model API, swapped in by a host proxy so the key never enters the VM); the hands sandbox holds no secrets.

### Each turn is bounded

A turn is one bounded request from the adapter to the brain:

1. the adapter reads new input from the [event log](/agent-sessions/events);
2. it sends that input, the model, prompt, tool endpoint, and state directory to the brain;
3. the brain drives the provider SDK and acts only through [runtime tools](/agent-sessions/runtime-tools);
4. the adapter commits the brain's stream as session events with stable ids;
5. the turn ends when the brain returns `done`, asks for input, hits a deadline, or crashes.

Across turns the brain keeps provider-specific state under a checkpointed state directory — for example a local Claude journal or a Codex thread id. The durable record is the event log plus that state directory, which the platform checkpoints at each boundary and restores on recovery.

### Pinned per session

When a session starts it pins the runtime and version it began on (alongside the rest of the [agent snapshot](/agent-sessions/agents#session-pinned-config)). `runtime` is fixed at agent creation — to run a different engine, create a new agent. Other agent edits (`model`, `prompt`, `limits`) never affect a running or resumed session: new sessions pick up the change, in-flight ones keep what they started with.

## Built-in supervision and recovery

OpenComputer supervises runtime execution:

* **One writer at a time.** Only one adapter advances a session at any moment; a stale or slow writer is rejected, so the log never forks.
* **The brain is supervised.** If the resident brain crashes or stops answering health checks, it is restarted and the turn is retried from durable state.
* **Hangs are bounded.** A turn has a deadline; a stuck model or tool path ends `deadline_exceeded` instead of staying stuck.
* **A lost machine is restored.** If the brain sandbox is lost, OpenComputer recreates it, restores the checkpointed state directory, and replays from the durable log.
* **A turn that can't start fails cleanly.** If the model key can't be resolved or the runtime image can't start, the turn ends with an **`error` event carrying the reason** and the session returns to idle — it doesn't hang.
* **Safety sweep.** A periodic sweep picks up sessions whose work was missed or left mid-flight.
* **Lifecycle events.** Turn and sandbox transitions are logged, so you can see where a session is and why a turn ended.

### Failure behavior

| Failure                     | What happens                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------ |
| Client disconnects          | Reconnect from your cursor ([events](/agent-sessions/events)); nothing lost.         |
| Session idles               | Sandbox hibernates; resumes intact on the next message.                              |
| Brain **crashes**           | Restarted; the turn resumes from committed events and checkpointed state.            |
| Brain **hangs**             | Bounded by the turn deadline; the turn ends `deadline_exceeded` — steer to continue. |
| Sandbox lost **while idle** | Recreated from the last checkpoint before the next turn.                             |
| Sandbox lost **mid-turn**   | Recreated, restored from checkpointed state, and replayed from the durable log.      |

Work since the last committed step may repeat, so **make side effects idempotent** and treat the event log (and delivered webhooks) as the durable record. Recovery resumes from committed steps and checkpointed runtime state, not from arbitrary CPU instruction state. Uncommitted hands-sandbox files are not restored after sandbox loss — commit or push to keep them.