Skip to content

Search articles, repositories, topics and pages.

OpenHands

OpenHands/OpenHands

An open platform for coding agents built around an event-driven controller and sandboxed runtimes

93,751 stars12,555 forks

View on GitHub (opens in a new tab)
  • TypeScript
  • agent
  • artificial-intelligence
  • chatgpt
  • claude-ai
  • cli
OpenHands Agent Canvas connecting through its TypeScript client to Agent Server, the software-agent SDK, tools, workspaces and runtimes

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

Architecture

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.

Code analysis

The current request flow can be reduced to this conceptual pseudo-code:

controller_loop.py, python
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.

Resources

  1. OpenHands on GitHub — Agent Canvas, repository boundaries and local-stack orchestration.
  2. OpenHands documentation — current setup, architecture and self-hosting guidance.
  3. software-agent-sdk — Agent Server, agents, tools, conversations, workspaces and events.