OpenHands Architecture Documentation

OpenHands is an AI-powered autonomous software development platform that enables AI agents to perform real-world software engineering tasks — writing code, running commands, browsing the web, and interacting with APIs — inside sandboxed environments.

Documents

#	Document	Description
0	High-Level Overview	Platform summary, tech stack, directory structure, licensing
1	Entry Points & Execution Flow	CLI, web server, V1 app server, execution pipeline, state machine
2	Core Business Logic & Data Flow	Agent system, controller loop, event system, delegation, memory
3	Key Abstractions & Interfaces	Agent, Runtime, Event, FileStore, LLM interfaces and design patterns
4	Configuration System	TOML config, Python config classes, env vars, loading order
5	LLM Integration	LiteLLM, function calling, model features, prompts, guardrails, tools

Quick Start

For an overview of the architecture, start with 00-overview.md, then read 01-entry-points.md to understand how the system boots and runs.

Note on V0 / V1 Migration

As of version 1.0.0, OpenHands is migrating from V0 (legacy) to V1. Many core modules carry a Legacy-V0 tag and are scheduled for removal by April 2026. The V1 agentic core lives in the Software Agent SDK, and the V1 application server lives under openhands/app_server/. This documentation covers both codepaths where relevant.