OpenHands

OpenHands implements a provider-agnostic LLM abstraction layer that normalizes API calls across OpenAI, Anthropic, Claude, GPT, and other models through a unified message formatting and serialization system. The layer handles model-specific quirks, token counting, cost tracking, and retry logic transparently, allowing agents to switch between providers without code changes. Built on LiteLLM integration with metrics collection and budget management per model.

OpenHands provides isolated code execution environments through a pluggable Runtime Architecture that supports Docker, Kubernetes, and local process runtimes. The Sandbox Specification Service defines execution contexts with configurable resource limits, file system isolation, and network policies. Actions execute through an Action Execution Server that marshals code/commands into the sandbox, captures output, and enforces timeout constraints without exposing the host system.

OpenHands provides a Frontend Application built with React that enables interactive agent conversations through a web browser. The UI implements real-time message streaming via WebSocket, conversation history browsing, and settings management. State Management handles client-side state for conversations, messages, and UI state; Internationalization supports multiple languages. The UI integrates with the backend through REST API (V1) or WebSocket (V0) for seamless real-time updates.

OpenHands provides a Development Environment Setup with Docker Compose configuration for local development, enabling developers to run the full stack (backend, frontend, database, sandbox) locally. The Local Development Workflow supports hot-reload for code changes without restarting services. Testing Strategy includes unit tests, integration tests, and end-to-end tests; Code Quality and Linting enforce standards through automated checks.

OpenHands exposes agent functionality through a comprehensive REST API (V1 Conversation Endpoints, Settings Endpoints, Secrets Endpoints, Git Endpoints) and WebSocket protocol (V0 WebSocket Protocol) for real-time communication. The API enables programmatic agent creation, message sending, action execution, and conversation management. REST API follows standard HTTP conventions with JSON payloads; WebSocket protocol uses event-based messaging for streaming updates.

OpenHands implements a planning-reasoning system where agents decompose user requests into discrete actions (code execution, file operations, tool calls) through an Agent Controller that manages conversation state and action sequencing. The system uses chain-of-thought reasoning to decide which actions to take next, with support for both synchronous step-by-step execution and asynchronous parallel action batching. Conversation Lifecycle management tracks state across multiple agent iterations, enabling multi-turn problem solving.

OpenHands implements a Skill Loading System that dynamically discovers and registers tools available to agents through Model Context Protocol (MCP) integration. Skills are loaded at conversation start, exposing capabilities like Git operations, file manipulation, and custom tools through a unified function-calling interface. The Microagent Discovery System allows agents to find and compose smaller specialized agents as tools, enabling hierarchical task decomposition.

OpenHands manages agent state through a Conversation Service that tracks all actions, messages, and results across multiple agent iterations. The system uses an event-driven architecture where each action generates events (action_start, action_end, error) that are streamed to clients in real-time via WebSocket (V0) or REST polling (V1). Conversation metadata is persisted to SQL storage, enabling conversation history retrieval, resumption, and analysis.

OpenHands provides Git Repository Setup and Git Provider Integration that abstracts version control operations across GitHub, GitLab, and other providers. Git operations are exposed through both MCP tools and dedicated REST API endpoints, enabling agents to clone repositories, create branches, commit changes, and open pull requests. Provider Token Management handles authentication securely through a secrets management system.

OpenHands implements a Settings Architecture with multi-tenant support for enterprise deployments, including User and Organization Management, Authentication Flow, and BYOR (Bring Your Own Reason) API Keys. The system separates configuration sources (environment variables, config files, API) with clear precedence rules. Secrets Management stores sensitive data securely, and LiteLLM Integration with Budget Management enables per-user or per-organization cost controls and billing.

OpenHands collects comprehensive metrics throughout the agent lifecycle including LLM token usage, action execution times, error rates, and cost tracking. The Metrics and Cost Tracking system integrates with LiteLLM to capture per-model costs; the Event Callback system persists all events to SQL for analysis. Real-time monitoring is exposed through WebSocket streams (V0) or REST endpoints (V1), enabling dashboards and alerting systems.

OpenHands provides Application Docker Image Building and Runtime Image Building for containerized deployments, with native Kubernetes support through the Kubernetes runtime implementation. The system includes CI/CD Pipeline integration for automated builds and Deployment Options for various environments (local, cloud, on-premise). Docker Compose configuration enables local development; Kubernetes manifests support production deployments with auto-scaling and resource management.

OpenHands implements a Runtime Builder Extensibility system that allows custom runtime implementations beyond Docker and Kubernetes. The Runtime Plugins architecture enables teams to add support for custom execution environments (e.g., cloud functions, HPC clusters). Storage Backend Extension allows pluggable storage implementations for conversation history and events, decoupling the system from specific databases.