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.
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.
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:
- 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.
- 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.
- Path-triggered rules, so an agent loads a rule only when it touches matching files.
- Fixed and changing prompt tiers for cache reuse.
- One narrow workspace interface with many backends: execute, upload, download, list and alive.
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.