OpenHands Administrator & Developer Guide

OpenHands (formerly OpenDevin) is an autonomous AI software development agent platform. Agents write code, execute terminal commands, browse the web, and interact with APIs inside sandboxed runtime environments. This guide covers architecture, deployment, configuration, security, and developer internals for administrators and contributors operating OpenHands at any scale.

1. Architecture Overview

1.1 System Architecture

                        ┌──────────────────────────────────┐
                        │          Frontend (React)         │
                        │   Vite 7 / React 19 / Zustand 5  │
                        │        React Router 7 / i18n      │
                        └──────────────┬───────────────────┘
                                       │ WebSocket / REST
                        ┌──────────────▼───────────────────┐
                        │        Application Server         │
                        │  ┌─────────┐  ┌────────────────┐ │
                        │  │ V1 App  │  │ V0 Legacy API  │ │
                        │  │ Server  │  │   (FastAPI)    │ │
                        │  └────┬────┘  └───────┬────────┘ │
                        │       │               │          │
                        │  ┌────▼───────────────▼────────┐ │
                        │  │     Agent Controller         │ │
                        │  │  (execution loop, state)     │ │
                        │  └────────────┬─────────────────┘ │
                        │               │                   │
                        │  ┌────────────▼─────────────────┐ │
                        │  │        Event Stream           │ │
                        │  │  (append-only, subscribers)   │ │
                        │  └────────────┬─────────────────┘ │
                        └───────────────┼───────────────────┘
                                        │
              ┌─────────────────────────┼─────────────────────────┐
              │                         │                         │
    ┌─────────▼──────────┐  ┌───────────▼──────────┐  ┌──────────▼─────────┐
    │    LLM Layer       │  │     Runtime Layer     │  │   Storage Layer    │
    │  litellm (100+     │  │  ┌─────────────────┐  │  │  Local / S3 / GCS  │
    │  providers)        │  │  │ Docker Runtime   │  │  │  Memory / Webhook  │
    │  LLM / AsyncLLM /  │  │  │ K8s Runtime     │  │  └────────────────────┘
    │  StreamingLLM      │  │  │ Local Runtime   │  │
    │  LLMRegistry       │  │  │ CLI Runtime     │  │
    └────────────────────┘  │  │ Remote Runtime  │  │
                            │  └────────┬────────┘  │
                            │           │           │
                            │  ┌────────▼────────┐  │
                            │  │   Sandboxed      │  │
                            │  │   Container      │  │
                            │  │  (code exec,     │  │
                            │  │   browser, tools) │  │
                            │  └─────────────────┘  │
                            └───────────────────────┘

1.2 Component Inventory

1.3 Technology Stack

1.4 V0 vs V1 Architecture

OpenHands is undergoing a major architectural migration from V0 to V1 (Software Agent SDK).

Important

The V0 server in openhands/server/ is deprecated as of v1.0.0. New deployments should use the V1 app server with ENABLE_V1=true. The V0 code path remains for backward compatibility but receives no new features.

2. System Requirements

2.1 Hardware Requirements

2.2 Software Dependencies

2.3 Runtime Resource Limits

The runtime sandbox enforces configurable resource constraints:

• Memory: Controlled by RUNTIME_MAX_MEMORY_GB (no default limit unless set)
• Memory monitoring: Enable with RUNTIME_MEMORY_MONITOR=true
• CPU: Kubernetes deployments use resource_cpu_request (default: 1)
• Storage: Kubernetes PVC default 2Gi, configurable via pvc_storage_size

Note

Each agent session spawns its own sandboxed container. Plan capacity for N concurrent sessions * per-session resource limits. The SANDBOX_BASE_CONTAINER_IMAGE defaults to the official OpenHands runtime image from ghcr.io/openhands/runtime.

3. Configuration Reference

3.1 Configuration System

OpenHands uses TOML-based configuration with 14 config files in openhands/core/config/. Configuration is loaded in this precedence order:

1. Environment variables (highest priority)
2. config.toml file
3. Default values (lowest priority)

The config system uses Pydantic models for validation. Key config classes:

3.2 Core / Server Variables

3.3 LLM Variables

LLM retry configuration (set in config.toml under [llm]):

[llm]
model = "claude-sonnet-4-20250514"
api_key = "sk-..."
num_retries = 8
retry_min_wait = 15
retry_max_wait = 120
retry_multiplier = 2

Warning

Issue #14028 documents a known bug where Gemini model base URLs get doubled, causing 404 errors. If using Google Gemini models, verify your base_url does not include the /v1 suffix — litellm appends it automatically.

3.4 Runtime Variables

3.5 Storage Variables

3.6 Agent & Skill Variables

3.7 Secret Management Variables

3.8 Enterprise Variables

3.9 Enterprise Database Variables

3.10 MCP Variables

3.11 Sample config.toml

[core]
workspace_base = "./workspace"
run_as_openhands = true
max_iterations = 100
max_budget_per_task = 4.0

[llm]
model = "claude-sonnet-4-20250514"
api_key = "sk-ant-..."
temperature = 0.0
num_retries = 8
retry_min_wait = 15
retry_max_wait = 120

[agent]
codeact_enable_browsing = true
codeact_enable_jupyter = true
codeact_enable_llm_editor = false

[sandbox]
base_container_image = "ghcr.io/openhands/runtime:latest"
timeout = 120
enable_auto_lint = true

[security]
confirmation_mode = false
security_analyzer = ""

[mcp]
# MCP servers configuration

4. Deployment & Scaling

4.1 Docker Deployment (Single Node)

The simplest production deployment uses Docker directly:

# Pull the latest image
docker pull ghcr.io/openhands/openhands:latest

# Run with Docker socket mounted (required for sandbox containers)
docker run -d \
  --name openhands \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/home/openhands/.openhands \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e LOG_LEVEL=INFO \
  ghcr.io/openhands/openhands:latest

Caution

Mounting the Docker socket (/var/run/docker.sock) grants the container full Docker access on the host. In production, consider using Docker-in-Docker or a remote Docker daemon with TLS authentication. Never expose the Docker socket to untrusted workloads.

4.2 Docker Compose Deployment

version: "3.8"
services:
  openhands:
    image: ghcr.io/openhands/openhands:latest
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - openhands-data:/home/openhands/.openhands
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - LOG_LEVEL=INFO
      - SERVE_FRONTEND=true
    restart: unless-stopped

volumes:
  openhands-data:

4.3 Kubernetes Deployment

OpenHands supports native Kubernetes runtime for sandbox containers. Set RUNTIME=kubernetes and configure the Kubernetes section:

[kubernetes]
namespace = "openhands"
ingress_domain = "openhands.example.com"
pvc_storage_size = "2Gi"
pvc_storage_class = "standard"
resource_cpu_request = "1"
resource_memory_request = "1Gi"
resource_memory_limit = "2Gi"
image_pull_secret = "ghcr-pull-secret"
ingress_tls_secret = "openhands-tls"
node_selector_key = "workload-type"
node_selector_val = "compute"
tolerations_yaml = ""
privileged = false

Each agent session creates a Kubernetes Pod with:

• A PersistentVolumeClaim for workspace data
• Resource requests and limits as configured
• Optional node selectors and tolerations for scheduling
• Optional ingress with TLS termination

4.4 KIND (Local Kubernetes Development)

The kind/ directory provides a complete local Kubernetes development environment:

# Create KIND cluster
kind create cluster --config kind/kind-config.yaml

# Apply manifests
kubectl apply -f kind/manifests/

# Set runtime to kubernetes
export RUNTIME=kubernetes

4.5 Runtime Types

_DEFAULT_RUNTIME_CLASSES = {
    'eventstream': DockerRuntime,
    'docker': DockerRuntime,
    'remote': RemoteRuntime,
    'local': LocalRuntime,
    'kubernetes': KubernetesRuntime,
    'cli': CLIRuntime,
}

Third-party runtimes are auto-discovered from third_party.runtime.impl via pkgutil, enabling custom runtime implementations without modifying core code.

Tip

For production deployments serving multiple users, Kubernetes runtime is strongly recommended. It provides proper resource isolation, automatic cleanup of terminated sessions, and horizontal scaling via standard Kubernetes primitives (HPA, node autoscaling).

4.6 Enterprise Deployment

Enterprise deployments add authentication, billing, and organization management:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Keycloak   │     │  PostgreSQL  │     │    Redis     │
│   (Auth)     │     │   (Data)     │     │   (Cache)    │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                   ┌────────▼────────┐
                   │   OpenHands     │
                   │   Enterprise    │
                   │   App Server    │
                   └────────┬────────┘
                            │
                   ┌────────▼────────┐
                   │     Stripe      │
                   │   (Billing)     │
                   └─────────────────┘

Required services for enterprise:

• Keycloak: Authentication and SSO (KEYCLOAK_* variables)
• PostgreSQL: User data, organizations, API keys (Alembic migrations)
• Redis: Session cache, rate limiting (REDIS_* variables)
• Stripe: Subscription and credit billing (STRIPE_API_KEY, ENABLE_BILLING=true)

4.7 Container Build System

The containers/ directory holds Docker build configurations for:

• Runtime sandbox images
• Application server images
• Development images

Custom sandbox images extend the base runtime:

FROM ghcr.io/openhands/runtime:latest
RUN apt-get update && apt-get install -y your-custom-tools

5. Operations

5.1 Health Monitoring

The health endpoint provides system status:

curl http://localhost:3000/api/v1/health

For enterprise deployments, a readiness probe is also available:

curl http://localhost:3000/api/v1/ready

5.2 Log Management

Configure logging granularity with these variables:

# Standard logging
export LOG_LEVEL=INFO

# Debug everything
export DEBUG=true
export DEBUG_LLM=true
export DEBUG_RUNTIME=true
export LOG_ALL_EVENTS=true

# Production structured logging
export LOG_JSON=true
export LOG_TO_FILE=true

Key log categories:

• LLM interactions: Enable DEBUG_LLM to see raw request/response payloads. Useful for diagnosing prompt issues or token budget overruns.
• Runtime operations: Enable DEBUG_RUNTIME for sandbox container lifecycle events.
• Event stream: Enable LOG_ALL_EVENTS to trace every action and observation through the system.

Warning

DEBUG_LLM=true logs full LLM payloads including any secrets or sensitive content passed in prompts. Never enable in production environments with user data. Rotate any API keys that appear in debug logs.

5.3 Data Persistence

All persistent data lives under OH_PERSISTENCE_DIR (default: ~/.openhands):

~/.openhands/
├── sessions/          # Active/historical session data
├── file_store/        # Default local file store
└── config.toml        # User configuration

For S3-backed persistence:

export FILE_STORE=s3
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_S3_ENDPOINT=https://s3.amazonaws.com

For Google Cloud Storage:

export FILE_STORE=google_cloud
# Authenticate via GOOGLE_APPLICATION_CREDENTIALS or workload identity

5.4 Session Management

Each agent interaction creates a session with:

• A unique session ID
• An event stream (append-only log of all actions and observations)
• A sandboxed runtime container
• LLM metrics (cost, token counts)

Sessions persist to the configured file store. The event stream supports:

• Subscriber-based real-time notifications
• Filtered queries by type, source, date range, or content
• Batch retrieval for bulk operations

5.5 Backup and Recovery

Local file store: Back up OH_PERSISTENCE_DIR with standard filesystem tools.

S3 file store: Enable S3 versioning on the bucket for point-in-time recovery.

Enterprise PostgreSQL: Standard pg_dump / pg_restore procedures. Alembic migrations track schema version for safe upgrades.

# PostgreSQL backup
pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME > backup_$(date +%Y%m%d).sql

# Restore
psql -h $DB_HOST -U $DB_USER -d $DB_NAME < backup_20260506.sql

5.6 Upgrade Procedures

1. Pull the new image: docker pull ghcr.io/openhands/openhands:latest
2. Stop the running container gracefully (allow active sessions to complete)
3. Run database migrations (enterprise): alembic upgrade head
4. Start the new container
5. Verify health endpoint returns OK

6. Performance

6.1 LLM Performance Tuning

The LLM layer is typically the performance bottleneck. Key tuning parameters:

6.2 Context Window Management

OpenHands implements multiple context condensation strategies to manage long conversations:

Configure in config.toml:

[agent.condenser]
type = "llm_summarizing"
# or
type = "recent_events"
keep_last = 50

6.3 Runtime Performance

• Container startup: SANDBOX_STARTUP_GRACE_SECONDS controls how long to wait for sandbox readiness. Increase for slow Docker hosts.
• Plugin initialization: INIT_PLUGIN_TIMEOUT (default 120s) governs plugin setup. Increase for environments with slow network access.
• Memory: Set RUNTIME_MAX_MEMORY_GB to prevent runaway containers. Enable RUNTIME_MEMORY_MONITOR to track usage.

6.4 Model Routing (Experimental)

OpenHands supports experimental model routing for optimizing which model handles different request types:

6.5 Database Connection Pooling (Enterprise)

For high-concurrency enterprise deployments, tune the PostgreSQL connection pool:

export DB_POOL_SIZE=25       # Base pool size
export DB_MAX_OVERFLOW=10    # Additional connections under load

Total max connections = DB_POOL_SIZE + DB_MAX_OVERFLOW = 35 per application instance.

7. Security

7.1 Sandbox Isolation

Every agent session runs inside an isolated sandbox container. The security model:

┌─────────────────────────────────────────┐
│              Host System                │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │     OpenHands App Server          │  │
│  │  (no direct code execution)       │  │
│  └───────────────┬───────────────────┘  │
│                  │ Docker API / K8s API  │
│  ┌───────────────▼───────────────────┐  │
│  │     Sandbox Container             │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │  Agent code execution       │  │  │
│  │  │  Terminal commands          │  │  │
│  │  │  Web browsing               │  │  │
│  │  │  File operations            │  │  │
│  │  └─────────────────────────────┘  │  │
│  │  Resource limits enforced         │  │
│  │  No host filesystem access        │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Key isolation controls:

• User separation: SU_TO_USER=true (default) runs agent code as non-root inside the sandbox
• Network: Container networking provides L3 isolation; Kubernetes adds network policies
• Filesystem: Sandboxes get ephemeral filesystems; SANDBOX_VOLUMES controls explicit mounts
• Resources: Memory and CPU limits enforced by container runtime
• Privileged mode: privileged = false by default in Kubernetes config

7.2 Authentication

7.3 Secret Management

OpenHands enforces limits on stored secrets:

• Maximum 50 secrets per account (OH_MAX_API_SECRETS_COUNT)
• Secret names up to 256 characters (OH_MAX_API_SECRET_NAME_LENGTH)
• Secret values up to 64KB (OH_MAX_API_SECRET_VALUE_LENGTH)

Secrets injected into the sandbox environment (e.g., SANDBOX_ENV_OPENAI_API_KEY) are scoped to that session's container and destroyed when the session ends.

7.4 Git Security

# Default: HTTPS-only git operations
export ALLOW_INSECURE_GIT_ACCESS=false

Caution

Setting ALLOW_INSECURE_GIT_ACCESS=true permits HTTP (unencrypted) Git operations. This exposes credentials and source code in transit. Only enable for air-gapped environments with no TLS capability.

7.5 Webhook Security

All webhook integrations use HMAC signature verification:

7.6 reCAPTCHA (Enterprise)

Enterprise deployments can enable Google reCAPTCHA to prevent automated abuse:

export RECAPTCHA_PROJECT_ID="project-id"
export RECAPTCHA_SITE_KEY="6Le..."
export RECAPTCHA_HMAC_SECRET="..."
export RECAPTCHA_BLOCK_THRESHOLD=0.3  # Block scores below this threshold

7.7 Security Analyzer

The SecurityConfig supports pluggable security analyzers that evaluate agent actions before execution:

[security]
confirmation_mode = true          # Require confirmation for sensitive ops
security_analyzer = "invariant"   # Pluggable analyzer name

When confirmation_mode is enabled, potentially dangerous operations (file deletion, network access, system commands) require explicit user approval.

8. Developer Internals

8.1 Event System Deep Dive

The event system is the backbone of OpenHands. Every agent interaction produces events flowing through the EventStream:

User Input → UserAction (Event)
    → AgentController processes
    → Agent produces AgentAction (Event)
    → Runtime executes
    → Observation (Event) returned
    → Agent processes observation
    → ... (loop until AgentFinishAction or max_iterations)

Event hierarchy:

Event (base)
├── Action
│   ├── CmdRunAction          # Shell command execution
│   ├── FileEditAction        # Edit file content
│   ├── FileReadAction        # Read file content
│   ├── FileWriteAction       # Write entire file
│   ├── IPythonRunCellAction  # Execute Jupyter cell
│   ├── BrowseURLAction       # Navigate to URL
│   ├── BrowseInteractiveAction  # Interactive browser
│   ├── AgentFinishAction     # Agent declares task complete
│   ├── AgentDelegateAction   # Delegate to sub-agent
│   └── MessageAction         # Send message to user
│
└── Observation
    ├── CmdOutputObservation       # Command output
    ├── FileEditObservation        # Edit result
    ├── FileReadObservation        # File content
    ├── FileWriteObservation       # Write confirmation
    ├── IPythonRunCellObservation  # Jupyter output
    ├── ErrorObservation           # Error details
    ├── BrowserOutputObservation   # Browser page content
    └── FileDownloadObservation    # Downloaded file info

Event properties:

• id: Unique event identifier
• timestamp: ISO 8601 creation time
• source: EventSource.AGENT, EventSource.USER, or EventSource.ENVIRONMENT
• cause: ID of the event that triggered this one
• timeout: Optional timeout for the action
• llm_metrics: Token usage and cost tracking

EventFilter supports filtering by:

• Event type (action vs observation, specific subtypes)
• Source (agent, user, environment)
• Date range
• Content query (text search within event data)

8.2 Agent Architecture

Agents follow a registry pattern:

class Agent(ABC):
    """Abstract base class for all agents."""
    _registry: dict[str, type[Agent]] = {}

    @classmethod
    def register(cls, name: str, agent_cls: type[Agent]):
        cls._registry[name] = agent_cls

    @classmethod
    def get_cls(cls, name: str) -> type[Agent]:
        return cls._registry[name]

The default agent is CodeActAgent, which uses a ReAct-style loop with tool calling. Agent capabilities:

Prompt management: Templates use Jinja2 (system_prompt.j2, system_prompt_long_horizon.j2). Microagents extend base behavior and can be disabled via disabled_microagents in agent config.

8.3 AgentController Execution Loop

The AgentController orchestrates the agent lifecycle:

1. Initialize session (create runtime, load config)
2. Set up event stream with subscribers
3. Enter main loop:
   a. Get agent's next action (LLM call)
   b. Validate action against security policy
   c. Execute action in runtime
   d. Collect observation
   e. Append both to event stream
   f. Check termination conditions:
      - AgentFinishAction received
      - max_iterations exceeded
      - max_budget_per_task exceeded
      - Error threshold reached
4. Cleanup (destroy runtime, persist session)

8.4 LLM Layer Internals

Three LLM client classes handle different execution models:

LLMRegistry manages multiple named LLM instances, allowing different models for different purposes (e.g., a cheap model for summarization, a capable model for code generation).

Function call conversion (fn_call_converter.py): Converts between different tool-calling formats (OpenAI function calling, Anthropic tool use, raw XML) to ensure compatibility across LLM providers.

Model features detection (model_features.py): Auto-detects model capabilities (vision, function calling, streaming) to adapt behavior.

Metrics tracking: The Metrics class accumulates:

• Total tokens (input + output)
• Cost in dollars
• Number of API calls
• Cache hit/miss rates

Note

Issue #13843 documents that LLM cost tracking stops working after a session resume. Costs accumulated before the resume are preserved, but the counter resets for the resumed portion. This is a known limitation tracked for future fix.

8.5 MCP Integration

Model Context Protocol enables agents to use external tools via standardized interfaces:

[mcp]
# Stdio-based MCP server
[[mcp.stdio_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

# Remote MCP server (HTTP/SSE)
[[mcp.remote_servers]]
name = "custom-tools"
url = "https://mcp.example.com/sse"

The MCP client:

• Connects via Stdio (subprocess) or HTTP/SSE (remote) transport
• Wraps discovered tools as MCPClientTool objects for agent consumption
• Handles connection lifecycle (connect, disconnect, reconnect)
• Collects errors via MCPErrorCollector for diagnostic reporting
• Supports dynamic server updates via POST /update_mcp_server endpoint

8.6 Storage Layer

All storage backends implement the FileStore interface:

class FileStore(ABC):
    @abstractmethod
    def write(self, path: str, contents: str | bytes) -> None: ...
    @abstractmethod
    def read(self, path: str) -> str: ...
    @abstractmethod
    def list(self, path: str) -> list[str]: ...
    @abstractmethod
    def delete(self, path: str) -> None: ...
    @abstractmethod
    def exists(self, path: str) -> bool: ...

8.7 Code Intelligence

The src/code_intelligence.py module provides AST-based extraction:

• Function/method definitions
• Class hierarchies
• Import graphs
• CLI command registration patterns

The src/repo_analyzer.py handles repository cloning and intelligent triage, scoring folders as HIGH/LOW/SKIP to focus analysis on the most important code paths.

8.8 Project Structure

openhands/
├── core/
│   ├── config/           # 14 config files, Pydantic models
│   ├── logger/           # Structured logging
│   └── exceptions.py     # Error hierarchy
├── controller/           # AgentController, state machine
├── events/               # Event, EventStream, EventFilter
├── llm/                  # LLM, AsyncLLM, StreamingLLM, LLMRegistry
├── runtime/              # Docker, K8s, Local, CLI, Remote runtimes
├── storage/              # FileStore implementations
├── mcp/                  # Model Context Protocol client
├── agent/                # Agent base class, CodeActAgent
├── server/               # V0 legacy FastAPI server
├── app_server/           # V1 application server
└── utils/                # Shared utilities

frontend/                 # React/TypeScript UI
enterprise/               # SaaS features
openhands-ui/             # Shared component library
containers/               # Docker build configs
kind/                     # Kubernetes dev environment
tests/                    # Test suites

8.9 Testing Strategy

Key testing patterns:

• InMemoryFileStore for storage tests (no filesystem side effects)
• Mock LLM responses for agent behavior tests
• Docker-based integration tests for runtime validation
• Playwright for full browser-to-sandbox E2E flows

8.10 Build System

Backend (Poetry):

poetry install              # Install dependencies
poetry run python -m openhands.core.main  # Run server
poetry run pytest           # Run tests

Frontend (npm):

cd frontend
npm install                 # Install dependencies
npm run dev                 # Development server (Vite HMR)
npm run build               # Production build
npm test                    # Run Vitest suite

Docker images:

# Build runtime sandbox image
docker build -f containers/runtime/Dockerfile -t openhands-runtime .

# Build app server image
docker build -f containers/app/Dockerfile -t openhands-app .

9. Integration Points

9.1 API Endpoint Reference

Core App Server

Runtime Action Execution Server

Enterprise: Authentication

Enterprise: Billing

Enterprise: API Keys

Enterprise: Organizations

Enterprise: Email

Enterprise: Feedback

Enterprise: OAuth Device Flow

Enterprise: Invitations

Enterprise: Service

9.2 LLM Provider Integration

OpenHands supports 100+ LLM providers through litellm. Configuration per provider:

# OpenAI
[llm]
model = "gpt-4o"
api_key = "sk-..."

# Anthropic
[llm]
model = "claude-sonnet-4-20250514"
api_key = "sk-ant-..."

# AWS Bedrock
[llm]
model = "bedrock/anthropic.claude-3-sonnet"
aws_access_key_id = "AKIA..."
aws_secret_access_key = "..."
aws_region_name = "us-east-1"

# Azure OpenAI
[llm]
model = "azure/gpt-4o"
api_key = "..."
base_url = "https://your-resource.openai.azure.com/"
api_version = "2024-02-15-preview"

# Local (Ollama)
[llm]
model = "ollama/llama3"
base_url = "http://localhost:11434"
api_key = "dummy"

9.3 Git Provider Integration (Enterprise)

Important

Issue #14096 documents that the Integrations page renders blank when GITHUB_APP_SLUG is not configured. Ensure all required GitHub App variables are set if enabling the GitHub integration.

9.4 External Service Integration

9.5 Automation Event Forwarding

When AUTOMATION_EVENT_FORWARDING_ENABLED=true, OpenHands forwards agent events to an external automation service:

export AUTOMATION_SERVICE_URL="https://automation.example.com"
export AUTOMATION_WEBHOOK_SECRET="hmac-secret"
export AUTOMATION_EVENT_FORWARDING_ENABLED=true
export AUTOMATION_SERVICE_TIMEOUT=30

10. Troubleshooting

10.1 Agent Errors

10.2 LLM Errors

10.3 Function Call Errors

10.4 Runtime Errors

10.5 Browser Errors

10.6 Storage Errors

10.7 MCP Errors

10.8 Common Operational Issues

Web UI stuck at "Starting" for old conversations (Issue #12684, CLOSED): Old sessions may fail to reconnect. Clear browser storage or start a new conversation.

Gemini models returning 404 (Issue #14028, OPEN): The base_url gets doubled when using Google Gemini models. Remove any /v1 suffix from your configured base URL.

LLM cost tracking stops after session resume (Issue #13843, CLOSED): Costs accumulated before resume are preserved, but the counter resets for the resumed session portion.

Accumulated token usage returns empty dict (Issue #14039, OPEN): The accumulated_token_usage field in the events API may return {}. This is tracked for fix.

Integrations page blank (Issue #14096, OPEN): The integrations page renders blank without GITHUB_APP_SLUG being set. Ensure all GitHub App configuration is complete.

Auto-titling broken for webhook conversations (Issue #14100, CLOSED): Conversations initiated via webhooks were not receiving auto-generated titles. Fixed in recent releases.

Tip

For full event history loading in long-running sessions, see Issue #12616 (OPEN) which tracks improvements to how events are loaded and retained across session boundaries.

10.9 Docker-Specific Issues

"Cannot connect to Docker daemon":

# Verify Docker is running
docker info

# Check socket permissions
ls -la /var/run/docker.sock

# If using rootless Docker, ensure DOCKER_HOST is set
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock

Sandbox container won't start:

# Check available disk space
df -h

# Check Docker resource limits
docker system info | grep -i memory

# Increase startup timeout
export SANDBOX_STARTUP_GRACE_SECONDS=60

10.10 Kubernetes-Specific Issues

Pod eviction: Sandbox pods may be evicted under memory pressure. Increase resource_memory_limit or add dedicated node pools with appropriate taints/tolerations.

PVC provisioning failures: Verify the pvc_storage_class exists in your cluster:

kubectl get storageclasses

Image pull errors: Configure image_pull_secret if using private registries:

kubectl create secret docker-registry ghcr-pull-secret \
  --docker-server=ghcr.io \
  --docker-username=USERNAME \
  --docker-password=TOKEN

10.11 Performance Debugging

Slow agent responses:

1. Enable DEBUG_LLM=true to measure LLM latency
2. Check if context condensation is needed (large event histories)
3. Verify network latency to LLM provider
4. Consider a faster model for iterative tasks

High memory usage:

1. Enable RUNTIME_MEMORY_MONITOR=true
2. Set RUNTIME_MAX_MEMORY_GB to cap per-session usage
3. Check for memory leaks in long-running sessions
4. Review condenser settings to prevent unbounded event accumulation

10.12 Enterprise Database Issues

Connection pool exhaustion:

# Increase pool size
export DB_POOL_SIZE=50
export DB_MAX_OVERFLOW=20

# Monitor active connections
psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname='openhands';"

Migration failures:

# Check current migration state
alembic current

# Run pending migrations
alembic upgrade head

# Rollback one step
alembic downgrade -1

11. Error Classes Reference

11.1 Agent Errors

11.2 LLM Errors

11.3 Function Call Errors

11.4 Runtime Errors

11.5 Browser Errors

12. Module Reference

12.1 openhands/core/config/ (14 files, 106K chars)

The configuration subsystem parses TOML files, environment variables, and CLI arguments into validated Pydantic models. All config classes support serialization to/from TOML and JSON.

Key files:

• app_config.py — Top-level AppConfig aggregating all sub-configs
• llm_config.py — LLMConfig with model, API key, retry, and token settings
• agent_config.py — AgentConfig with tool enables and behavior flags
• sandbox_config.py — SandboxConfig for container runtime settings
• security_config.py — SecurityConfig for confirmation mode and analyzers
• mcp_config.py — MCPConfig for MCP server definitions
• condenser_config.py — Condenser strategy configs (6 types)

12.2 openhands/controller/

The AgentController manages the agent execution lifecycle:

• Initializes runtime and event stream
• Runs the agent loop (action → execute → observe → repeat)
• Enforces iteration and budget limits
• Handles delegation to sub-agents
• Manages state transitions (RUNNING, PAUSED, STOPPED, ERROR)

12.3 openhands/runtime/

Runtime implementations share a common interface for:

• Container/process lifecycle management
• Action execution (commands, file ops, browser, Jupyter)
• File upload/download
• Plugin initialization
• Health checking

The DockerRuntime and KubernetesRuntime provide full production isolation. LocalRuntime runs directly on the host (development only). CLIRuntime enables headless scripted usage.

12.4 openhands/llm/

• llm.py — Synchronous LLM class wrapping litellm
• async_llm.py — AsyncLLM for concurrent operations
• streaming_llm.py — StreamingLLM for real-time token streaming
• llm_registry.py — LLMRegistry managing named LLM instances
• fn_call_converter.py — Cross-format function call conversion
• model_features.py — Auto-detect model capabilities
• metrics.py — Metrics class for cost/token tracking
• bedrock.py — AWS Bedrock-specific integration

12.5 openhands/events/

• event.py — Base Event class with metadata
• stream.py — EventStream append-only store with subscribers
• filter.py — EventFilter for querying events
• action/ — All action types
• observation/ — All observation types
• serialization/ — Event serialization/deserialization

12.6 openhands/storage/

• local.py — LocalFileStore (filesystem-backed)
• s3.py — S3FileStore (AWS S3/MinIO)
• google_cloud.py — GoogleCloudFileStore
• memory.py — InMemoryFileStore (testing)
• webhook.py — WebHookFileStore, BatchedWebHookFileStore

12.7 openhands/mcp/

• client.py — MCPClient connecting via Stdio or HTTP/SSE
• tool.py — MCPClientTool wrapping MCP tools for agent consumption
• error_collector.py — MCPErrorCollector for diagnostic aggregation

12.8 enterprise/

Enterprise service layer:

13. Known Issues & Limitations

13.1 Open Issues

13.2 Closed Issues (Recent, Noteworthy)

Note

MyPy type checking for SQLAlchemy models was not fully configured (Issue #13412). If contributing to the enterprise layer, install sqlalchemy-stubs or sqlalchemy[mypy] to get proper type checking in your editor.

14. Contributing

14.1 Development Setup

# Clone the repository
git clone https://github.com/All-Hands-AI/OpenHands.git
cd OpenHands

# Backend setup
poetry install

# Frontend setup
cd frontend && npm install && cd ..

# Run development server
poetry run python -m openhands.core.main

# Run frontend dev server (separate terminal)
cd frontend && npm run dev

14.2 Code Patterns

Registry pattern (agents, runtimes):

# Register a new agent
@Agent.register("my_agent")
class MyAgent(Agent):
    def step(self, state: State) -> Action:
        ...

Event-driven communication:

# Subscribe to events
event_stream.subscribe(EventStreamSubscriber.AGENT_CONTROLLER, callback)

# Append events
event_stream.add_event(CmdRunAction(command="ls -la"), EventSource.AGENT)

Pydantic config models:

class MyConfig(BaseModel):
    setting_a: str = "default"
    setting_b: int = 42
    model_config = ConfigDict(extra="forbid")

14.3 Testing Conventions

• Unit tests: pure logic, mock external dependencies
• Integration tests: require Docker, test runtime interactions
• E2E tests: require full stack (backend + frontend + Docker)
• Use InMemoryFileStore in unit tests to avoid filesystem side effects
• Mock LLM responses for deterministic agent behavior tests

14.4 Frontend Architecture

The frontend uses a modern React stack:

The openhands-ui/ package provides shared components published as @openhands/ui, used by both the main frontend and enterprise UI.

For basic usage, quick start guides, and user-facing feature documentation, see the OpenHands User Guide.