Agent Architecture

OpenHands

OpenHands is a self-hosted developer control center for coding agents and automations. It can run OpenHands, Claude Code, Codex, Gemini, and ACP-compatible agents, so the architecture page must separate the local connector row from OpenHands as a multi-agent orchestration host.

Source reviewed #13Checked 2026-07-06

Setup guide Source

Run type

CLI

Adapter

json-stdio

Source

OSS · OpenHands/OpenHands

Stars

★ 86k

Archive Context

This page is one host entry inside the full architecture archive and keeps multi-surface products visible instead of collapsing them into a single run type.

42 host archive

Host page

openhands

Run cohort

CLI: 30

Archive route

/agents

Host Surface Perspectives

The host is the primary architecture boundary. Each runnable surface below separates what the host owns from what agent-connector can safely install for OpenHands.

1 surface entry

CLI

cli

Host entry: A terminal command owns the process, current working directory, stdin/stdout, shell environment, and project file discovery.
Host owns: The CLI host owns agent loop timing, approval prompts, tool execution, session files, and how hook or MCP subprocesses are launched.
Connector role: agent-connector can only write the host's documented CLI config, prompt, memory, hook, MCP, or package files and point them at the home binary. Current wired connector surfaces: MCP server, Hooks, Memory.
Implementation consequence: A CLI surface is byte-addressable and smoke-testable from a temporary HOME, but terminal UI behavior still belongs to the host process. No visible host-native gap is currently tracked for this surface.

Verified Architecture

Source-checked on 2026-07-06. These notes are intentionally separate from the generated surface matrix below.

Sequence #13

Source pass

Current source review findings are kept as the first architecture section so readers can separate external evidence from the generated local coverage model.

OpenHands Agent Canvas is a self-hosted control center that can run multiple agent backends locally, remotely, or in cloud infrastructure.
The architecture source says Agent Canvas is powered by an Agent Server REST API and can connect to multiple agent servers from one frontend.
Because OpenHands can run third-party agents such as Claude Code, Codex, and Gemini, this row should be treated as an orchestration host, not only a CLI.

Runtime boundary

The connector row targets the OpenHands host surface, while OpenHands itself can dispatch multiple coding agents through local, remote, and cloud execution contexts. agent-connector must not collapse OpenHands into the agent it happens to launch.

The public repository describes a developer control center for agents and automations.
OpenHands can host OpenHands, Claude Code, Codex, Gemini, and ACP-compatible agents.
Agent Canvas and Agent Server indicate a split between UI orchestration and backend execution.

MCP registration

MCP should be documented as an available tool and integration rail, but OpenHands' more important boundary is agent orchestration. The adapter page should distinguish tool servers from agent backends and ACP-compatible launches.

A target agent may have its own MCP config that is not the same as OpenHands' orchestration configuration.
Connector support should record which layer receives the MCP server: OpenHands itself or a delegated agent runtime.

Hook bridge

agent-connector treats this row as a json-stdio host, but OpenHands' public architecture is service and automation oriented. Hook language should therefore be careful: lifecycle interception belongs to the adapter bridge or a specific agent backend, not to every OpenHands automation channel.

Slack, GitHub, and Linear automations are product channels and workflow triggers.
Agent launch, session handoff, and backend selection are separate from connector hook payload normalization.

Content surfaces

OpenHands content surfaces include agent workspace context, automations, prompts, and control-center state. When agent-connector writes commands, skills, or memory, the archive should clarify whether those artifacts are consumed by OpenHands or by a hosted downstream agent.

The Agent Canvas and Agent Server split creates an important teaching example for UI/backend architecture.
If a Claude Code or Codex backend is launched, that backend may still need its own native files.

Marketplace and host-only affordances

OpenHands' host-only affordance is orchestration across many agents plus automations for Slack, GitHub, and Linear. That makes it a reference host for control-plane architecture rather than a simple single-agent CLI adapter.

Students should read this row as a control-plane host with delegated agent runtimes.
The page should show ACP compatibility as a host capability that can bridge to external agents.

Host-specific shape

OpenHands keeps MCP and hooks in separate native files and uses AGENTS.md memory; commands, skills, subagents, statusline, and actions remain outside confirmed writable layouts.

Form factor: CLI.
Native surfaces: MCP server, Hooks, Memory.
Wired surfaces: MCP server, Hooks, Memory.
Visible gaps: none.

Hooks

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: none.
User-visible affordances: Users see managed memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Known Limits

Do not represent a delegated Claude Code, Codex, Gemini, or ACP agent feature as an OpenHands-native connector feature without layer-specific evidence.
Automations are host workflows, not necessarily hook events.
Agent Canvas, Agent Server, and software-agent-sdk references should be kept distinct in future source passes.

Evidence checked

OpenHands repository OpenHands documentation OpenHands software-agent-sdk

Architecture Diagram

Host-specific flow for the CLI surface.

json-stdio

1
Entry point: CLI
Terminal agent process reads user/project config and invokes the connector home binary for runtime callbacks.
2
Connector package
defineConnector package declares server, hooks, content, memory, and actions.
3
Adapter module: openhands
json-stdio renderer at src/adapters/openhands/index.ts.
4
Native host artifacts
Adapter writes MCP config + hook config + memory/rules through this host's native file, package, or marketplace surface.
5
Runtime boundary
host launches JSON-stdio hook command
6
User-visible surface
Users see managed memory surfaces after install; runtime-only surfaces stay behind the host boundary.
7
Coverage ceiling
3/3 native surfaces wired. No visible host-native gap in the current coverage matrix.

Component Diagram

Static parts of the OpenHands integration and which side owns each one.

OpenHands host
CLI surface owns the model loop, UI shell, config discovery, and native lifecycle for this integration.
agent-connector package
Normalizes connector declarations into MCP, hook, memory, content, and action payloads before delegating to a host adapter.
openhands adapter
Implements the json-stdio translation layer in src/adapters/openhands/index.ts.
Native artifacts
Adapter writes MCP config + hook config + memory/rules through this host's native file, package, or marketplace surface.
Runtime bridge
host launches JSON-stdio hook command
User-visible surface
Users see managed memory surfaces after install; runtime-only surfaces stay behind the host boundary.

Runtime Sequence Flow

Message order from install to runtime for the CLI surface.

1 · User / project
Choose host adapter
Install or update starts against OpenHands; the selected surface is CLI.
2 · agent-connector
Resolve connector declaration
The package reads connector metadata and routes it to the openhands adapter instead of exposing a generic host contract.
3 · openhands adapter
Render host-native shape
Adapter writes MCP config + hook config + memory/rules through this host's native file, package, or marketplace surface.
4 · OpenHands
Host loads artifacts
host launches JSON-stdio hook command
5 · Agent runtime
Run through host boundary
Users see managed memory surfaces after install; runtime-only surfaces stay behind the host boundary.
6 · Coverage matrix
Expose remaining ceiling
3/3 native surfaces wired. No visible host-native gap in the current coverage matrix.

Architecture Archive

The same five study axes are rendered for every host: runtime shape, hooks, MCP, memory, and host-only affordances.

Host-specific shape

OpenHands keeps MCP and hooks in separate native files and uses AGENTS.md memory; commands, skills, subagents, statusline, and actions remain outside confirmed writable layouts.

Form factor: CLI.
Native surfaces: MCP server, Hooks, Memory.
Wired surfaces: MCP server, Hooks, Memory.
Visible gaps: none.

Hooks

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: none.
User-visible affordances: Users see managed memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Special Feature Inventory

Host-specific capabilities separated from the generic surface matrix: lifecycle hooks, MCP registration, memory/rules, marketplace delivery, and UI or content affordances owned by the host.

Lifecycle hooks

Wired

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP registration

Wired

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory and rules

Wired

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace delivery

Direct files

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Host-only affordances

Not confirmed

Wired host affordances: none. Host-native gaps: none. Not confirmed: Commands, Skills, Subagents, Statusline handler, Action affordances.

Source Review Notes

Latest source pass for host-specific architecture details. This is separate from generated adapter coverage and local drift guards.

Checked 2026-07-06Open review source

OpenHands/OpenHands repository

OpenHands Agent Canvas is a self-hosted control center that can run multiple agent backends locally, remotely, or in cloud infrastructure.
The architecture source says Agent Canvas is powered by an Agent Server REST API and can connect to multiple agent servers from one frontend.
Because OpenHands can run third-party agents such as Claude Code, Codex, and Gemini, this row should be treated as an orchestration host, not only a CLI.

Evidence Map

Each host page ties public source evidence to the local adapter and drift guards that keep the rendered archive aligned with code.

Public source: OpenHands/OpenHands

Primary public repository or product source used for current host status and source links.

external

Open source

Local adapter implementation

Defines the install/uninstall behavior, native config rendering, capability flags, and any runtime parse/format bridge for this host.

local

src/adapters/openhands/index.ts

Platform metadata and host-native matrix

Records the form factor, public source target, ranking source, native host surfaces, and current agent-connector coverage cells.

local

site/src/platform-data.ts

Architecture drift guard

Asserts that every registered host has a page, diagram, host-specific brief, source link, form-factor band, and adapter-aligned surface data.

local

tests/docs/platform-drift.test.ts

Runtime Shape

Hooks are dispatched through a host-launched command. The adapter parses host JSON, calls the connector handler, and formats the reply back to the host contract.

MCP registration: Wired through this adapter
Hook bridge: Wired

Connector Surfaces

Static content

MCP server, Hooks, Memory

Runtime handlers

No runtime handler surfaces wired

Surface Matrix

Wired means agent-connector installs it now. Host native marks support we know about but have not wired yet.

SurfaceStatus

MCP server

Static content

agent-connector installs this surface today.

Wired

Hooks

Static content

agent-connector installs this surface today.

Wired

Commands

Static content

No confirmed host-native surface.

N/A

Skills

Static content

No confirmed host-native surface.

N/A

Subagents

Static content

No confirmed host-native surface.

N/A

Memory

Static content

agent-connector installs this surface today.

Wired

Statusline handler

Runtime handler

No confirmed host-native surface.

N/A

Action affordances

Runtime handler

No confirmed host-native surface.

N/A