OpenComputer Documentation

Durable Agent Sessions allow you to define an agent and run resumable, steerable sessions. You can create an agent, start a session, stream its event log, steer it with messages, and receive results via webhooks.

Key capabilities include:

• Runtime Supervision: Automatic restarts on crashes, hibernation for idle sessions, and clean stops for hung runs.
• Sandboxing: Separation of the Brain (agent loop) and Hands (files and commands). Untrusted work is contained in the hands sandbox, while model keys are kept secure in a secret store outside the sandbox.
• Live Interaction: Stream events using a session token and reconnect from any seq without gaps. You can send follow-up messages without exposing your organization key.
• Webhook Delivery: User-level events are delivered via signed Standard Webhooks with retries and dead-lettering support.

In OpenComputer, an agent is a configuration object, not a compute instance. It defines the agent's knowledge (prompt, skills), its drivers (runtime, model), its triggers, its policies, and its connection (the scope of repositories it can act upon).

Key characteristics:

• Decoupled from compute: An agent defines what to do, but it does not run itself. Instead, sessions reference an agent to perform work.
• Repo-agnostic: An agent is not bound to a single repository. Its connection defines a candidate set of repositories. At runtime, a session resolves which specific repository to work in based on the trigger, the conversation, an optional repo default, or user input.
• Immutable Versions: Every change to an agent (config, deployment, or model switch) creates a new immutable version. Sessions are pinned to the version they started with; updates only affect new sessions.

Flue is a TypeScript framework for building durable agents. Unlike OpenComputer's built-in runtimes (which manage agents like Claude Code or Codex), a Flue agent is a custom application where your application is the runtime.

Key differences include:

• Agent Loop: In Flue, your compiled application contains the agent loop.
• Compute: Flue uses a single deployed app with one Durable Object instance per session, rather than managed per-session sandboxes.
• State: Flue stores conversation state in Durable Object SQLite, while OpenComputer projects public milestones into its event log.
• Tools: Tools are defined via defineTool code and packaged skill imports compiled into the Worker.
• Deployment: You build and deploy a compiled application rather than just uploading prompts and skills.

Under the hood, OpenComputer runs the Flue Cloudflare target as an agent Worker. This allows sessions to start without provisioning a virtual machine, using an ocSandbox only when specific operations require a Linux workspace.

OpenComputer provides two primary workflows for defining sandbox environments programmatically using the Image builder:

1. Declarative images: You define an Image and pass it directly to Sandbox.create(image=...). The system builds the image on-the-fly during the first run and caches it by content hash. Subsequent sandboxes with the same image manifest will reuse the cached version instantly.
2. Pre-built snapshots: You create a named, persistent snapshot using the Snapshots API. This is ideal for heavy environments (e.g., data science stacks) that you want to share across multiple sandboxes without rebuilding. Sandboxes created from snapshots boot instantly without a build step.

Use Declarative images for rapid iteration and Snapshots for stable, reusable, and production-ready environments.

# Pattern 1: On-demand image
image = Image.base().apt_install(["curl"])
sandbox = await Sandbox.create(image=image)

# Pattern 2: Pre-built snapshot
snapshots = Snapshots()
await snapshots.create(name="my-snap", image=image)
sandbox = await Sandbox.create(snapshot="my-snap")

When writing prompts for built-in runtimes (claude or codex), it is important to understand that the agent operates within a sandbox. The agent has no direct access to your local filesystem, shell, or network. Instead, it interacts with the sandbox through a fixed set of tools.

Key Sandbox Constraints

• Filesystem/Shell: All commands must be executed via the bash tool. Each call to bash is a fresh shell session, so you must use absolute paths or cd /workspace && ... to maintain state.
• Network: The sandbox has open outbound internet by default (allowing git clone, package installs, etc.), but access to private, loopback, link-local, and cloud-metadata addresses is blocked.
• Execution Events: A bash command execution surfaces as an exec.completed event containing the command, exit_code, and a summary. Large outputs are provided via a content_ref.