opencomputer

Preview

Durable Agent Sessions

Resumable, steerable agent sessions

OpenComputer handles session state, runtime lifecycle, streaming, and webhooks, so your app code stays small enough to run on an edge worker.

Start with the quickstart Get API key

Example: PR-review agent repo

Built into every session

Use sessions for durable agents; use sandboxes for one-shot commands.

runtime

Self-healing runtime

  • Runtime crashes restart automatically.
  • Idle sessions hibernate and wake on the next message.
  • Hung runs stop cleanly instead of staying stuck.

sandbox

Brain / hands sandboxing

  • Brain: agent loop. Hands: files and commands.
  • Untrusted work stays contained in the hands sandbox.
  • Your model key stays in the secret store, never in a sandbox.

webhook

Reliable backend delivery

  • Deliver user-level events to your webhook.
  • Requests are signed when the destination has a secret.
  • Deliveries are retried, dead-lettered, inspectable, and redeliverable.

Build a managed coding agent in three steps

Create an agent, start a session, then stream the event log and steer follow-up work.

1. Create an agent

An agent stores name, runtime, model, prompt, and model credential.

TypeScript SDK 
import { OpenComputer } from "@opencomputer/sdk";

const oc = new OpenComputer({
  apiKey: process.env.OPENCOMPUTER_API_KEY,
});

const agent = await oc.agents.create({
  name: "quickstart-coder",
  runtime: "claude",
  model: "anthropic/claude-opus-4-8",
  prompt: "Work in /workspace. Say progress. Ask only when blocked.",
  key: process.env.ANTHROPIC_API_KEY,
  limits: { turns: 4, turnSeconds: 600 },
});

2. Start a session

A session starts work and returns a browser-safe client_token scoped to that session.

Start work 
const session = await oc.sessions.create({
  agent: agent.id,
  input: "Create a todo app with local storage.",
  metadata: {
    projectId: "proj_123",
    taskId: "task_456",
  },
  idempotencyKey: "task_456",
  destinations: [{
    url: "https://your.app/oc-webhook",
    level: "user",
    types: ["turn.completed"],
  }],
});

// session.id + session.clientToken

3. Stream and steer

Use the session token in the browser. EventSource resumes after dropped connections.

Browser client 
import { connectSession } from "@opencomputer/sdk";

const live = await connectSession({ sessionId, clientToken });

for await (const event of live.events({ level: "progress" })) {
  render(event);
}

await live.steer("Add a completed-task filter.", {
  idempotencyKey: "msg_01",
});

Session lifecycle

A session is the durable unit of an agent at work: an append-only event log, pinned agent snapshot, and lifecycle status. Compute attaches, hibernates, and wakes on the next message.

Status Meaning
queuedScheduled; a turn has not started running yet.
runningA turn is executing.
awaiting_inputA turn ended asking a question. Reply by steering.
idleDone for now, quiescent and steerable. The sandbox is hibernated.
failedThe session errored out.
archivedClosed and read-only.
Fetch the result 
const session = await oc.sessions.get("ses_...");
const { lastTurn, result } = await session.result();

// lastTurn.yieldReason: "completed", "needs_input",
// "deadline_exceeded", "budget_exceeded", "max_turns", "canceled"

Event log

Each session has ordered events. Use seq to resume and type to handle structured events.

Turn event sequence 
turn.started
  tool.call          npm test
  exec.completed     exit 1
  agent.message      "3 tests fail"   level: user
turn.completed       needs_input
Event field Use it for
typeStable discriminator: agent.message, turn.completed, tool.call, exec.completed, errors.
levelVisibility filter: user, progress, or internal.
seqMonotonic cursor for ordering and resume.
bodyTyped payload for that event.
actorWho produced the event: human, agent, or system.

Webhooks deliver committed events

Register a destination and user-level events are delivered at least once and retried. Deliveries are signed when the destination has a secret. The envelope includes the session metadata you set at create time.

Delivery envelope 
{
  "type": "turn.completed",
  "sessionId": "ses_...",
  "eventId": "evt_...",
  "metadata": {
    "projectId": "proj_123",
    "taskId": "task_456"
  },
  "event": {
    "id": "evt_...",
    "seq": 12,
    "type": "turn.completed",
    "level": "user",
    "body": { "yield_reason": "completed" }
  }
}
Signed destination 
const session = await oc.sessions.get("ses_...");

await session.destinations.create({
  url: "https://your.app/oc-webhook",
  secret: "whsec_...",
  level: "user",
  types: ["turn.completed"],
});

Dedupe on webhook-id. Verify the raw body with a Standard Webhooks library when a destination secret is set. A delivery succeeds on any HTTP 2xx.

The PR-review agent stores GitHub PR IDs in metadata. Completion webhooks carry them back, so the app can update the PR without a database, queue, or always-on worker.

Runtime tools

The claude and codex runtimes use tools against the hands sandbox. The brain has no direct filesystem or shell; commands and file edits run through the hands tools.

Tool What it does
bashRun a shell command in the sandbox.
readRead a file from the sandbox.
writeWrite a file to the sandbox.
lsList a directory in the sandbox.
sayEmit a user-level message. The final say is the session result.
askAsk a question and yield with needs_input. Reply by steering.

For public repositories, put the repo URL and branch or commit in the task text. Prepared workspaces and private-repo access are coming soon.

How it works

Your app starts, streams, and steers a durable session. The managed runtime drives the agent loop, acts through the hands sandbox, and delivers user-level events to your webhook.

How Durable Agent Sessions connect the app, session event log, managed runtime, brain sandbox, hands sandbox, model provider, and webhook delivery.

Examples and docs

Docs explain the API. Repos show complete apps.

Examples

App-building agent repo PR-review agent repo

Docs

Quickstart Session lifecycle Events Webhooks Runtime tools