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

# Durable Agent Sessions

> Define an agent, then run resumable, steerable sessions

Create an agent, start a session, stream its event log, steer it with messages, and receive results by webhook.

<Note>Prefer a console? The [dashboard](https://app.opencomputer.dev) does all of this in a UI — create [agents](/agent-sessions/agents) and [credentials](/agent-sessions/credentials), watch and steer sessions live, and inspect webhook deliveries. The API and SDK below are the same surface, scripted.</Note>

## Core behavior

<CardGroup cols={2}>
  <Card title="Built-in runtime supervision" icon="heart-pulse">
    * Runtime crashes restart automatically
    * Idle sessions hibernate and wake on the next message
    * Hung runs stop cleanly instead of staying stuck
  </Card>

  <Card title="Built-in brain / hands sandboxing" icon="shield-halved">
    * **Brain**: agent loop. **Hands**: files and commands.
    * Untrusted work stays contained in the hands sandbox
    * Your model key stays in the [secret store](/sandboxes/secrets), never in a sandbox
  </Card>

  <Card title="Live streaming and steering" icon="radio">
    * Stream events directly from the browser with a session token
    * Reconnect from any `seq` without gaps
    * Send follow-up messages without exposing your org key
  </Card>

  <Card title="Webhook delivery" icon="paper-plane">
    * Deliver user-level events to your webhook
    * Signed with [Standard Webhooks](https://www.standardwebhooks.com)
    * Retried, dead-lettered, inspectable, and redeliverable
  </Card>
</CardGroup>

<Note>[Flue](/agent-sessions/flue) uses the same session, event, steering, and webhook APIs on a different execution substrate. Your compiled Flue app is the runtime, each session gets its own Durable Object, and no Linux sandbox is created unless the app explicitly uses `ocSandbox`.</Note>

## Get started

<Steps>
  <Step title="Define an agent">
    Create a reusable `{ name, model, prompt, runtime }` from your backend, using `runtime: "claude"` for Anthropic models or `"codex"` for OpenAI models. Run **Managed** (`credential: "managed"`, billed to your OpenComputer credits) or pass your own model key. Built-in runtime deployments support isolated revisions, skills, repo push-to-deploy, and pointer rollback. To deploy your own Flue app instead, use the [Flue guide](/agent-sessions/flue). ([Agents](/agent-sessions/agents))
  </Step>

  <Step title="Start a session">
    Start a session with `{ agent, input }`. The agent starts immediately and returns a browser-safe `client_token`.
  </Step>

  <Step title="Watch, steer, get notified">
    Stream events with `EventSource`, [steer](/agent-sessions/messaging) with the client token, and register a [webhook](/agent-sessions/webhooks) when your backend needs push delivery.
  </Step>
</Steps>

## Architecture

<Frame>
  <img src="https://mintcdn.com/opensandbox/vr0l20ErHl9y4VkC/images/durable-agent-sessions-architecture.svg?fit=max&auto=format&n=vr0l20ErHl9y4VkC&q=85&s=f97e5e72ba68311901ad6004de07f99a" alt="Durable Agent Sessions architecture: your app starts, steers, and streams a durable event-log session; a managed runtime adapter commits events while the brain drives the agent loop and acts through the hands sandbox; the model runs on your key from the secret store, which never enters a sandbox; user-level events are delivered out via your webhook." width="960" height="560" data-path="images/durable-agent-sessions-architecture.svg" />
</Frame>

The event log is the durable consumer record. Your app starts sessions, streams events, and steers with messages. Built-in runtimes drive the agent loop through brain and hands sandboxes. Flue executes in its Worker and Durable Object, then projects the same public milestone events. Managed model credentials stay outside both execution substrates.

## When to use sessions

Use sessions for long-running or interactive agents. For a one-shot command, use a [sandbox](/sandboxes/overview) directly.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/agent-sessions/quickstart">
    Start a session, stream events, and steer it with concise REST examples.
  </Card>

  <Card title="Events" icon="timeline" href="/agent-sessions/events">
    Event shape, visibility levels, cursors, and resume behavior.
  </Card>

  <Card title="Session lifecycle" icon="book" href="/agent-sessions/sessions">
    Statuses, events, results, and limits.
  </Card>

  <Card title="HTTP invocation" icon="link" href="/agent-sessions/agent-urls">
    Invoke an agent from your backend or create a scoped Hook URL for an external system.
  </Card>

  <Card title="Repos & GitHub" icon="github" href="/agent-sessions/repos">
    Private repo checkout with GitHub access kept outside the agent sandbox.
  </Card>

  <Card title="Example apps" icon="github" href="https://github.com/diggerhq/oc-sessions-demos">
    A repo of examples built on this API.
  </Card>
</CardGroup>
