jcardena.com › Blog › Reading OpenHands: What to Borrow from an Open Agent Runtime, and What to Refuse
184 posts
EN ES

Reading OpenHands: What to Borrow from an Open Agent Runtime, and What to Refuse

AI

An architecture review of OpenHands against production guarantees: the event log, run governor and path rules worth borrowing, and the advisory security we refuse.

Reading OpenHands: What to Borrow from an Open Agent Runtime, and What to Refuse

Published November 2026, dated to the month the work was done.

An agent runtime is not ready for production because it can finish a coding task. It is ready when its actions are bounded, its history can be replayed, and every result traces back to a contract that was enforced. That is the standard our team holds our own agent platform to, and the standard we used to review OpenHands, the open-source platform where an AI agent writes, runs and fixes code inside a sandbox.

The design is strong and worth studying, and five of its patterns are worth carrying into our architecture. But its security model is advisory, and model credentials travel with the agent. My recommendation is to treat it as a bounded, replaceable worker behind one narrow interface, never as the control plane.

Build a view ofthe event logCall the modelwith toolsTurn the replyinto actionsCheck the securitypolicyRun the tool,record the resultCount steps, cost,stuck
One step of the OpenHands agent loop

What it is

OpenHands started in 2024 under the name OpenDevin and was renamed later that year. It is MIT licensed and works with many model providers. It has since been rewritten: the old single application was replaced by an agent SDK, and the main repository became a front-end application for running and watching agents. In the new version, the whole agent loop runs inside the sandbox.

We read it from pinned source snapshots and public documentation. A project that moves this fast changes shape between reads, so the version under review is part of the evaluation contract, not a footnote.

What is good

The core design is clear.

  • Everything is an event. A conversation is a start state plus an append-only list of typed, frozen events: messages, actions, observations and errors. Nothing is edited in place.
  • The log is a tree, not a list. Each event points to its parent, so forking and rewinding a conversation are built in.
  • Forgetting is also an event. When the context gets too long, the system does not delete history. It adds a marker that says "forget these events, here is a summary". The agent reads a view with the markers applied.
  • A run governor. There is an iteration cap, an optional cost budget summed across every model in the run, and a stuck detector that watches for repeated patterns. When it sees one, it nudges the agent once, then stops the run.
  • Rules that load by path. Skills can be triggered by keywords, by task, or by the files the agent touches. A rule about database migrations loads only when the agent opens migration files.
  • Prompt tiers. The fixed part of the system prompt comes first and the changing part last, so the provider's prompt cache can be reused across conversations.
  • Compatibility for models without native tool calling. For models without native tool calling, tools are written into the prompt and the reply is parsed back, so local models still work.

The patterns worth carrying

Five ideas survived our architecture review as proposed requirements:

  1. A typed, frozen, tree-shaped event log, with condensation recorded as a new event rather than a change. Our design adds one requirement it lacks: every event hashed and chained to the one before, with large outputs stored by content hash, so the log is tamper-evident.
  2. The run governor: iteration cap, cost budget, a stuck detector that nudges then halts, and a confirmation policy, all held as state and emitted as events.
  3. Path-triggered rules, so an agent loads a rule only when it touches matching files.
  4. Fixed and changing prompt tiers for cache reuse.
  5. One narrow workspace interface with many backends: execute, upload, download, list and alive.
CONTROL PLANERun governorMandatory gatesCredentials stayhereEVIDENCEHash-chained eventlogContent-addressedoutputsSnapshot at eachgateWORKSPACE CONTRACTExecuteUpload anddownloadList and aliveBOUNDED WORKEROpen agent runtimeIsolated sandboxFiltered egress
A bounded worker behind a narrow workspace contract

What we refuse to import

  • Advisory security. By default the confirmation policy never asks, and the model rates the risk of its own actions. Our gates are mandatory, not suggestions.
  • Credentials inside the sandbox. When the loop runs in the sandbox, the model credentials run there too. Our security contract keeps credentials in the control plane and sends only authorized actions to isolated workers.
  • A workspace that cannot be replayed. The workspace is a mutable mounted folder, so the exact files cannot be rebuilt from the log. We require a snapshot pinned at every gate.
  • Churn. The project went through major rewrites in a short time, and its earlier command-line tool was deprecated. Any use pins versions and integrates at exactly one boundary.
  • The security record. Public advisories describe past issues, including token exfiltration through prompt injection and a published CVE. Historical issues do not mean current ones, but they set the terms: any trial runs with no ambient secrets, filtered network egress and short-lived tokens.

A different promise

None of this makes OpenHands a weak project. It is built for a different promise. It is a good, vendor-neutral manager for coding agents. Our platform's promise is provenance: being able to show exactly what ran and which bytes it produced. Reviewing a strong project that makes a different promise clarifies your own.

How to evaluate any agent runtime

The next step is a bounded trial in an isolated environment: a disposable repository, one model, restricted egress, short-lived credentials, and a design for the adapter that lets the runtime act as one worker among others. The same questions apply to any runtime a team is considering:

  • Can every result be traced to the exact events and files that produced it?
  • Are the safety gates mandatory, or does the model grade itself?
  • Do credentials ever share a process with the model's actions?
  • Can the workspace be rebuilt exactly from the record?
  • Is there one integration boundary, pinned to a version?

This is Governance-Driven Contract Design applied to someone else's code: outcome first, guarantees second, a contract at every door. Frameworks will keep changing. A runtime that cannot show its work does not earn a place in production.

Every answer is earned.

JC
Juan Cardena
Enterprise AI & Agentic Systems Architect

Enterprise architect with 25 years across web, software, data, and AI. MIT CDAO ’25. Writing on agentic AI in production.