OpenHands
OpenHands/OpenHands
An open platform for coding agents built around an event-driven controller and sandboxed runtimes
93,751 stars12,555 forks
- TypeScript
- agent
- artificial-intelligence
- chatgpt
- claude-ai
- cli
About
🙌 OpenHands: AI-Driven Development
My analysis
Understanding OpenHands Architecture
A walk through how OpenHands structures a coding agent — the controller, the event stream and the sandboxed runtime — and what I would borrow from it.
TIAN NEWS AI
Published Updated 2 min read
OpenHands is an open platform for running software-development agents. Its current system is broader than one in-process controller: Agent Canvas provides the control surface, while Agent Server and the software-agent SDK own conversations, agents, tools and workspaces.
Updated
Describes the multi-repository Agent Canvas and Agent Server architecture documented on September 30, 2026. Pin a release or commit before doing source-level analysis.
Tested with
OpenHands/OpenHands · OpenHands/software-agent-sdk · OpenHands/typescript-client · OpenHands/automation
Four boundaries carry most of the current design.
- Agent Canvas. The frontend and user-facing control centre. It starts conversations, switches backends and orchestrates the local stack.
- TypeScript client. The browser-compatible client that connects Canvas to the Agent Server API.
- Agent Server and software-agent SDK. The canonical server API plus agents, tools, conversations, workspaces and events.
- Automation service and runtimes. Automation schedules or dispatches work; agent backends can run locally, in containers, on VMs or on managed infrastructure.
Key takeaway
The durable idea is the boundary between the control surface, the agent API and the execution environment. Canvas can change backends without owning the agent implementation itself.
The current request flow can be reduced to this conceptual pseudo-code:
conversation = canvas.start_conversation(backend)
client.send(conversation, user_message)
for event in agent_server.run(conversation):
canvas.render(event)
workspace.persist(event)Three details stood out:
- Repository ownership is explicit: Canvas, the Python SDK/server, the TypeScript client and automation live in separate repositories.
- A Canvas instance can connect to multiple Agent Servers and switch between local, remote and hosted backends.
- Conversation execution can run directly on a host or inside separate Docker sandboxes; those choices have different security boundaries.
Note
The separation between the control plane, the agent server and the execution environment is a good default for any agent that touches real systems.
- OpenHands on GitHub — Agent Canvas, repository boundaries and local-stack orchestration.
- OpenHands documentation — current setup, architecture and self-hosting guidance.
- software-agent-sdk — Agent Server, agents, tools, conversations, workspaces and events.