Related Pages

Related topics: App Server, Sandbox Services, and Integrations, Frontend Application and User Experience, LLM Profiles, Models, and Sandbox Runtime

Overview and System Architecture

1. Purpose and Scope

OpenHands is a self-hosted developer control center for running, orchestrating, and automating coding agents. As described in the project README, it provides a unified UI for "Run OpenHands, Claude Code, Codex, Gemini, or any ACP-compatible agent across local, remote, and cloud backends" (README.md). The product is also referred to as Agent Canvas, a name emphasizing its role as the canvas on which different agents operate.

The repository contains everything required to run the platform end-to-end:

• A React/Remix frontend that delivers the chat, conversation, and automation UI (frontend/README.md).
• A Python app server (openhands/app_server/) that exposes REST endpoints for conversations, sandboxes, integrations, and event callbacks.
• An enterprise server (Keycloak-authenticated SaaS deployment) with its own persistence and maintenance task system (enterprise/doc/architecture/README.md).
• A shared UI component library (openhands-ui/) published to npm for both internal and external use (openhands-ui/README.md).
• A growing library of skills/microagents that inject expertise into agent prompts (skills/README.md).

2. High-Level Component Architecture

The system is composed of several loosely coupled layers that communicate over HTTP and WebSocket:

flowchart TB
  User[User / Browser]
  FE[Frontend<br/>Remix SPA + React]
  UI[openhands-ui<br/>Component Library]
  AS[App Server<br/>FastAPI]
  ENT[Enterprise Server<br/>Keycloak + SaaS APIs]
  SBX[Sandbox Runtime<br/>Docker / VM / Cloud]
  INT[Integration Services<br/>GitHub, GitLab, Bitbucket DC]
  WH[Event Callbacks / Webhooks]
  SK[Skills & Microagents]

  User --> FE
  FE --> UI
  FE <-->|REST + WebSocket| AS
  AS <--> SBX
  AS <--> INT
  AS --> WH
  ENT --> AS
  FE -.->|loads| SK

Source: README.md; frontend/README.md; openhands/app_server/utils/README.md.

Frontend Layer

The frontend is a Remix SPA built with React, TypeScript, Redux, TanStack Query, and Tailwind. It uses Vite for bundling, i18next for localization (Catalan was added in 1.6.0), and Vitest + MSW for testing (frontend/README.md). Configuration is driven by environment variables such as VITE_BACKEND_BASE_URL, VITE_BACKEND_HOST, VITE_USE_TLS, and VITE_MOCK_API. The frontend talks to the backend through a typed API client whose types live alongside the implementation (for example, frontend/src/api/sandbox-service/sandbox-service.types.ts).

App Server Layer

The openhands/app_server/ directory is the canonical backend. It exposes:

• Sandbox service — manages sandbox lifecycle, with states MISSING, STARTING, RUNNING, PAUSED, ERROR (frontend/src/api/sandbox-service/sandbox-service.types.ts).
• Conversation service — V0 and V1 endpoints for starting, resuming, and clearing conversations. The V1 start task state machine includes WORKING, WAITING_FOR_SANDBOX, PREPARING_REPOSITORY, RUNNING_SETUP_SCRIPT, STARTING_CONVERSATION, READY, ERROR (frontend/src/api/conversation-service/v1-conversation-service.types.ts).
• Integration service — typed resources for GitHub, GitLab, and Bitbucket Data Center webhooks (frontend/src/api/integration-service/integration-service.types.ts).
• Event callbacks — webhook registration, filtering, and retry logic for outbound notifications (openhands/app_server/event_callback/README.md).
• Utility layer — get_impl / import_from allow downstream deployments to substitute base-class implementations without forking (openhands/app_server/utils/README.md).

Enterprise Layer

The enterprise/ tree layers Keycloak authentication, SaaS billing, and additional background services on top of the core app server. The architecture documentation explicitly delegates non-SaaS topics to the core docs (enterprise/doc/architecture/README.md). A MaintenanceTaskProcessor framework runs short, idempotent background jobs after each deploy to upgrade user state (enterprise/server/maintenance_task_processor/README.md).

Skills and Microagents

Skills provide context-aware expertise that is injected into agent prompts. Two flavors exist: knowledge agents in the public skills/ directory (keyword-triggered, e.g. github.md, docker.md) and repository agents loaded from .openhands/microagents/ (V0) or .openhands/skills/ (V1) inside a target repo (skills/README.md).

3. Conversation Versions: V0 vs V1

Two conversation APIs coexist:

• V0 uses .openhands/microagents/ for repo-level instructions and is gradually deprecated.
• V1 adopts .openhands/skills/ as the preferred location, supports backward compatibility with the V0 path, and enables features introduced in 1.6.0+ such as the /clear command and hooks (skills/README.md).

Several TypeScript types in the frontend carry @deprecated markers pointing V0 consumers to the V1 equivalents (for example, GitChangeStatus vs V1GitChangeStatus in frontend/src/api/open-hands.types.ts). New integrations and UI work should target the V1 surface.

4. Recent Evolution (1.8.0)

The 1.8.0 release (2026-06-10) introduced three notable architectural concepts:

Community threads show that LLM-profile editing still has rough edges (a bug where editing one profile overwrites the model and api_key of others, issue #14800) and that the in-app webview used for testing web apps is currently broken (issue #14569). The agent-server Docker image also needs --no-sandbox for headless Chromium (issue #14779), and make docker-dev leaves root-owned files in the host tree (issue #13434). On the API side, the Cloud runtime pool silently pauses older sandboxes when concurrency is exceeded instead of returning HTTP 429 (issue #13126). These known issues are good starting points when onboarding.

See Also

• Frontend Architecture & Tooling
• Enterprise Architecture
• Event Callbacks & Webhooks
• Skills and Microagents
• Release 1.8.0 notes

Related Pages

Related topics: Overview and System Architecture, LLM Profiles, Models, and Sandbox Runtime

App Server, Sandbox Services, and Integrations

Overview

The OpenHands App Server is the FastAPI-based control plane that exposes REST endpoints for managing conversations, sandboxes, events, secrets, and user settings in OpenHands V1 deployments. It sits between the React frontend (or third-party ACP-compatible agents) and the underlying agent runtime, providing a stable, versioned surface for clients to start, monitor, and tear down coding sessions. Source: openhands/app_server/README.md.

The server is organized into focused sub-packages: app_conversation/, sandbox/, event/, git/, secrets/, settings/, status/, user/, config_api/, web_client/, and shared helpers under utils/. This modular layout allows deployments to swap implementations (for example, Docker versus remote sandboxes) without changing upstream callers. Source: openhands/app_server/README.md.

A get_impl / import_from extensibility pattern in import_utils.py lets derived products (Enterprise, Cloud) override base classes by configuration, which is how the same code base serves both self-hosted and SaaS deployments. Source: openhands/app_server/utils/README.md.

Sandbox Services

Because agents execute arbitrary code, OpenHands isolates work inside sandboxes. The sandbox/ package defines an abstract SandboxService together with concrete implementations such as DockerSandboxService, RemoteSandboxService, and a Local variant. A companion SandboxSpecService manages reusable sandbox templates, while SandboxRouter exposes the HTTP surface. Source: openhands/app_server/sandbox/README.md.

The frontend mirrors this state with the V1SandboxStatus enum, which models a sandbox's lifecycle as MISSING → STARTING → RUNNING → PAUSED → ERROR. Each V1SandboxInfo carries the owner, the sandbox_spec_id it was started from, a session_api_key, and a list of V1ExposedUrl entries for browser access. Source: frontend/src/api/sandbox-service/sandbox-service.types.ts.

The 1.3.0 release added CORS support to the Docker sandbox service so that a remote browser can reach the sandbox. To use it, operators set WEB_HOST (for example, WEB_HOST=192.168.1.100:3000) together with SANDBOX_CONTAINER_URL_PATTERN. Source: Release notes 1.3.0. The 1.7.0 release introduced SANDBOX_KVM_ENABLED, which mounts /dev/kvm into the sandbox so KVM-accelerated VMs can run inside it. Source: Release notes 1.7.0.

A long-standing community concern is how the Cloud API handles the per-user runtime cap: when the maximum number of concurrent runtimes is reached, the server silently PAUSED older sandboxes instead of returning HTTP 429 to the caller, which makes client-side backoff and quota reporting difficult. Source: Issue #13126. In the 1.8.0 release, users can now select the sandbox grouping strategy, giving operators a knob to influence how new sandboxes are allocated and grouped. Source: Release notes 1.8.0.

flowchart LR
    Client[Frontend / ACP Client] -->|REST| Router[App Server Routers]
    Router --> ConvSvc[AppConversationService]
    Router --> SbxSvc[SandboxService]
    Router --> GitSvc[Git / Integration Service]
    ConvSvc --> SbxSvc
    SbxSvc -->|Docker / Remote / Local| Runtime[Sandbox Runtime]
    Runtime --> Agent[OpenHands Agent SDK]
    GitSvc -->|GitHub / GitLab / Bitbucket| Providers[External Git Hosts]

Conversations and User Context

Conversations are the unit of user-visible work. The app_conversation/ package exposes AppConversationService (abstract CRUD) and LiveStatusAppConversationService (real-time status streaming), with AppConversationRouter providing the HTTP layer. Search supports filters by title, date, and status, plus cursor-based pagination. Source: openhands/app_server/app_conversation/README.md.

A V1AppConversationStartTask walks the agent from WORKING through PREPARING_SANDBOX, WAITING_FOR_SANDBOX, PREPARING_REPOSITORY, RUNNING_SETUP_SCRIPT, SETTING_UP_GIT_HOOKS, SETTING_UP_SKILLS, STARTING_CONVERSATION, and finally READY (or ERROR). The V1AppConversation payload exposes the active sandbox_id, selected_repository, selected_branch, git_provider, llm_model, and agent_kind, plus accumulated metrics. Source: frontend/src/api/conversation-service/v1-conversation-service.types.ts.

The user/ package resolves the caller's identity via UserContext, wraps it for backwards compatibility in AuthUserContext, and exposes a UserContextInjector FastAPI dependency so route handlers can request a UserContext directly. This is what enables per-user sandbox access control and per-user secrets. Source: openhands/app_server/user/README.md.

Integrations

OpenHands integrates with external code hosts and SaaS tooling through the git/, event_callback/, and secrets/ modules on the server, and dedicated API clients in the frontend. The git service supports paginated repository search filtered by provider and installation ID, with cursor-based pageId parameters. Source: frontend/src/api/git-service/git-service.api.ts.

The integration service types cover GitLab projects and groups (with webhook enrollment state), Bitbucket Data Center resources (per-repository webhook enrollment), and a generic ResourceIdentifier shape for reinstall flows. Each resource tracks webhook_installed, webhook_uuid, and last_synced so the UI can show sync health. Source: frontend/src/api/integration-service/integration-service.types.ts.

Enterprise deployments extend these integrations through Keycloak-based authentication, Slack, Jira, and additional Git providers; see enterprise/doc/architecture/README.md and the linked Authentication Flow and External Integrations documents.

Community demand is steadily expanding the integration surface. The most engaged integration request is Gitea/Forgejo support (issue #9354), building on the earlier additions of GitHub and GitLab providers. The GitHub Copilot provider request (issue #6468) is similarly popular, pointing to a future where subscription-based LLM backends plug in alongside direct API keys. Source: Issue #9354, Issue #6468.

Common Failure Modes

See Also

• Enterprise Architecture
• App Server Conversation Management
• App Server Utilities & Extensibility
• Frontend API: Sandbox Service
• Frontend API: Git Service
• OpenHands Release 1.8.0

Related Pages

Related topics: Overview and System Architecture, LLM Profiles, Models, and Sandbox Runtime

Frontend Application and User Experience

Overview

The OpenHands frontend is a single-page application that delivers the end-user control center for autonomous coding agents. It is built with Remix SPA Mode (React + Vite + React Router) and TypeScript, and it consumes a FastAPI-based app server that exposes conversation, sandbox, event, and settings endpoints. The frontend is also complemented by a reusable component library, openhands-ui, which standardizes visual primitives across the application.

Source: frontend/README.md Source: openhands/app_server/README.md

Technology Stack and Project Layout

The frontend combines several modern web technologies:

• Remix SPA Mode for routing and data loading
• TypeScript for static typing
• Redux for global state (LLM settings, conversation cache)
• TanStack Query for server-state caching and invalidation
• Tailwind CSS for utility-first styling
• i18next for internationalization (English and community-contributed languages such as Catalan, added in 1.6.0)
• Vitest, React Testing Library, and Mock Service Worker (MSW) for testing

The project is organized by responsibility rather than by technical layer. Routes live under frontend/src/routes/, feature components under frontend/src/components/features/, shared primitives under frontend/src/components/ui/, and API clients under frontend/src/api/.

graph LR
  User[User Browser] --> SPA[Remix SPA Frontend]
  SPA --> MSW[MSW Mock Layer]
  SPA --> AppServer[OpenHands App Server]
  AppServer --> SDK[Agent SDK]
  SDK --> Sandbox[Docker / Remote Sandbox]
  SPA -. real-time .-> Events[Event Stream / Webhooks]
  Events --> AppServer

Source: frontend/README.md

UI Component System (openhands-ui)

All reusable visual primitives are packaged in the openhands-ui workspace. The library ships components such as Button, Checkbox, Input, Scrollable, Toggle, Tooltip, and a Typography family (H1–H6, Text, Code). The package is built with Bun for fast local iteration, and any contributor who needs to change dependencies must develop with Bun so that bun.lock stays authoritative.

The package is automatically published to npm when a version bump is merged to main. To test a local change in another project, contributors can run bun run build, then bun pm pack to produce a .tgz file, and install it with npm install path/to/openhands-ui-x.x.x.tgz.

Source: openhands-ui/README.md

Backend Integration and Domain Types

The frontend talks to the backend exclusively through the app_server package, which exposes REST endpoints for conversations, sandboxes, events, secrets, settings, and user management. The OpenHands app server is split into focused submodules such as app_conversation/, sandbox/, event/, event_callback/, git/, settings/, user/, and web_client/, each providing a FastAPI router.

Frontend API clients mirror this layout. For example, git-service.api.ts defines a typed wrapper around the Git repositories endpoint:

static async retrieveUserGitRepositories(
  provider: string,
  pageId?: string,
  limit = 30,
  installationId?: string,
): Promise<RepositoryPage>

The corresponding response types (e.g., GitLabResource, BitbucketDCResource) live in integration-service.types.ts, while shared domain models such as Microagent, GitChange, and ResultSet<T> are centralized in open-hands.types.ts. This separation lets UI code remain type-safe even as the backend grows to support additional providers (GitHub, GitLab, Bitbucket Data Center, and requested Gitea/Forgejo integrations tracked in community issue #9354).

Source: frontend/src/api/git-service/git-service.api.ts Source: frontend/src/api/integration-service/integration-service.types.ts Source: frontend/src/api/open-hands.types.ts Source: openhands/app_server/README.md

User Identity, Webhooks, and Real-Time UX

The user experience depends on two backend subsystems:

1. User Management – handled by app_server/user/, which provides a UserContext abstraction, a UserRouter with endpoints for the current user, and a UserContextInjector for FastAPI dependency injection. JWT-based authentication is integrated through the services/ module.
2. Event Callbacks – handled by app_server/event_callback/, which exposes EventCallbackService for CRUD operations, a SQL-backed SqlEventCallbackService, and an EventWebhookRouter that delivers webhook notifications when conversation events occur. The frontend surfaces these events through a WebSocket channel so the UI can update the chat, task list (added in 1.5.0), and conversation status in real time.

This architecture supports recent UX improvements such as the dismissable, truncated error messages (1.2.1), the LLM model badge on conversation cards (1.7.0), and the /clear command for V1 conversations (1.6.0). Community-reported issues — for example, editing one LLM profile overwriting another (issue #14800) and the broken in-app browser used to test web apps (issue #14569) — highlight areas where this layer still needs hardening.

Source: openhands/app_server/user/README.md Source: openhands/app_server/event_callback/README.md

Development Workflow

Two run modes are supported:

Required Node.js is 22.12.x or later. The backend can also be started separately via make start-backend, with the frontend served from frontend/ on port 3001.

Source: frontend/README.md

See Also

• OpenHands App Server
• openhands-ui Component Library
• Skills and Microagents
• Testing Strategy

Related Pages

Related topics: App Server, Sandbox Services, and Integrations, Frontend Application and User Experience

LLM Profiles, Models, and Sandbox Runtime

OpenHands exposes three tightly coupled concepts to users configuring a conversation: LLM Profiles (named bundles of provider settings), LLM Models (the catalogue of available model identifiers), and Sandbox Runtimes (the isolated environments that execute the agent). This page explains how these three concepts interact across the V1 backend and frontend.

1. LLM Profiles and Settings

What an LLM Profile is

An LLM Profile is a reusable, named configuration that pairs an LLM model identifier with credentials and provider-level options. Profiles were introduced in release 1.8.0 (PR #14149) and are persisted per user so the active profile can be switched without re-entering API keys for every conversation.

The profile and its sibling settings live in the settings module. The service abstraction lives in openhands/app_server/settings/llm_profiles.py, the persistence and validation schemas in settings_models.py, and the HTTP surface in settings_router.py. A profile typically carries:

• A model field referencing one of the catalogue identifiers served by the config API.
• An api_key (or reference to a secret) used to authenticate against the model provider.
• Optional fields such as base_url, custom headers, or reasoning effort.

Known Issue: Profile Edit Overwrites Siblings

A reported regression — Issue #14800 — describes editing one profile overwriting the model (and sometimes api_key) of other profiles. After editing several profiles in one session, they all collapse to the active profile's model. This indicates that the settings router is not always differentiating per-profile edits from "set the active profile" calls. The bug is acknowledged against the app image docker.openhands.dev/openhands/app and remains a high-priority issue for the 1.8.x line.

Settings Router Surface

The settings router exposes CRUD endpoints for profiles so the frontend can list, create, update, and activate them. The router delegates to the LLM profile service, which in turn relies on the user context provided by openhands/app_server/user/README.md to scope operations to the authenticated user.

2. LLM Models and Providers

The Config API Catalogue

The model catalogue is served separately from user settings. It is implemented by the config API services — abstract llm_model_service.py and its default implementation default_llm_model_service.py. These services expose paginated searches for providers and models.

The frontend TypeScript mirrors this shape in config-service.types.ts:

export interface LLMModel {
  provider: string | null;
  name: string;
  verified: boolean;
  hidden?: boolean;     // served but not offered in dropdowns
  canonical?: string;   // visible alias target
}

export interface LLMProvider { name: string; verified: boolean; }

The hidden and canonical fields are used when a managed LiteLLM proxy exposes a legacy alias route that should not be offered as a selectable option but still resolves to a visible "canonical" model — see the comments in config-service.types.ts for the exact contract.

Recent Model Additions

Each release typically extends the catalogue. Release 1.4.0 (PR #12835) added MiniMax-M2.5 model support, and release 1.7.0 (PR #13616) added the active LLM model to conversation cards and headers so users can see at a glance which model a conversation is running against. Helper utilities that build model/provider descriptors live in openhands/app_server/utils/llm.py.

3. Sandbox Runtime

Status Model

A sandbox is the container or VM in which an agent executes. The frontend models a sandbox's lifecycle in sandbox-service.types.ts as a finite set of states:

The full sandbox info object exposes id, sandbox_spec_id, session_api_key, exposed_urls, and created_at, with session_api_key being the credential the frontend must present when proxying runtime calls.

Conversation Bootstrapping

When the frontend launches a conversation it calls the V1 start endpoint defined in v1-conversation-service.api.ts. The request body carries sandbox_id (optional), agent_type, plugins, and llm_model. If sandbox_id is omitted the backend allocates a new sandbox from the active spec; if llm_model is set the conversation will be pinned to that model identifier, overriding the active profile's default. The backend returns a V1AppConversationStartTask that the frontend polls until READY to obtain the resulting app_conversation_id — see app_conversation/README.md for the full task lifecycle.

Grouping, KVM, and CORS

Several release-level knobs shape runtime behavior:

• Sandbox grouping strategy — selectable by the user since release 1.8.0 (PR #14291), letting multiple conversations share a single sandbox when appropriate.
• SANDBOX_KVM_ENABLED — added in release 1.7.0, passes /dev/kvm into sandbox containers so KVM-accelerated VMs can run instead of slow emulation.
• CORS for remote browsers — release 1.3.0 added CORS to the Docker sandbox service. Users running OpenHands on remote servers should set WEB_HOST (e.g. WEB_HOST=192.168.1.100:3000) along with SANDBOX_CONTAINER_URL_PATTERN.

Known Runtime Issues

Two runtime-class bugs are worth flagging:

• Browser sandbox launch failures — Issue #14779 reports that browser-use in the agent-server:1.28.0-python image launches Chromium without --no-sandbox, causing BrowserLaunchEvent timeouts and "Root CDP client not initialized" errors.
• Silent runtime pausing under load — Issue #13126 requests that the Cloud API return 429 Too Many Requests when concurrent runtimes are exhausted instead of silently pausing older sandboxes.

4. End-to-End Flow

sequenceDiagram
    participant U as User (Frontend)
    participant SET as Settings Router
    participant CONF as Config API
    participant SB as Sandbox Service
    participant CONV as Conversation Service
    U->>SET: List / activate LLM Profile
    U->>CONF: Search models & providers
    U->>CONV: Start conversation (sandbox_id?, llm_model?)
    CONV->>SB: Provision / attach sandbox
    SB-->>CONV: V1SandboxInfo (RUNNING)
    CONV-->>U: V1AppConversationStartTask (READY)

The flow shows how a profile selection, a model catalogue lookup, and a sandbox allocation converge on a single conversation start task.

See Also

• Agent Canvas & Agent Backends
• OpenHands V1 Architecture
• Frontend API Conventions
• Conversations and Tasks

Doramagic Pitfall Log

Found 33 structured pitfall item(s), including 6 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13827

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13647

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: [Bug] Conversation polling fails with ValidationError when secrets contain null values
• User impact: Developers may expose sensitive permissions or credentials: [Bug] Conversation polling fails with ValidationError when secrets contain null values
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Conversation polling fails with ValidationError when secrets contain null values. Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12714

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: [Feature]: Docker / Docker Compose Instructions
• User impact: Developers may expose sensitive permissions or credentials: [Feature]: Docker / Docker Compose Instructions
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Docker / Docker Compose Instructions. Context: Observed when using docker, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14882

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14912

6. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14882

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/OpenHands/OpenHands

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: 1.5.0 - 2026-03-11
• User impact: Upgrade or migration may change expected behavior: 1.5.0 - 2026-03-11
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 1.5.0 - 2026-03-11. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.5.0

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: 1.6.0 - 2026-03-30
• User impact: Upgrade or migration may change expected behavior: 1.6.0 - 2026-03-30
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 1.6.0 - 2026-03-30. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.6.0

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: 1.7.0 - 2026-05-01
• User impact: Upgrade or migration may change expected behavior: 1.7.0 - 2026-05-01
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 1.7.0 - 2026-05-01. Context: Observed when using docker
• Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.7.0

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Improve timeout handling and feedback for slow local LLMs
• User impact: Developers may fail before the first successful local run: Improve timeout handling and feedback for slow local LLMs
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Improve timeout handling and feedback for slow local LLMs. Context: Observed when using docker
• Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/8768

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Self-hosting OpenHands
• User impact: Developers may fail before the first successful local run: Self-hosting OpenHands
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Self-hosting OpenHands. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13827

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using OpenHands with real data or production workflows.

• API keys carry full user privileges — add scoped (reduced-privilege) cre - github / github_issue
• [[Feature]: option to send message when pressing enter, not create a new](https://github.com/OpenHands/OpenHands/issues/14861) - github / github_issue
• [[Feature]: Docker / Docker Compose Instructions](https://github.com/OpenHands/OpenHands/issues/14882) - github / github_issue
• Improve timeout handling and feedback for slow local LLMs - github / github_issue
• [[Enterprise] Admin setting for auto-delete of inactive user data after X](https://github.com/OpenHands/OpenHands/issues/12656) - github / github_issue
• [[Bug] Conversation polling fails with ValidationError when secrets conta](https://github.com/OpenHands/OpenHands/issues/12714) - github / github_issue
• Port Jira Data Center Integration to Plugin Architecture - github / github_issue
• [[Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even th](https://github.com/OpenHands/OpenHands/issues/13647) - github / github_issue
• [[Bug]: Pending Messages Not Sent After Conversation Is Ready](https://github.com/OpenHands/OpenHands/issues/13716) - github / github_issue
• Self-hosting OpenHands - github / github_issue
• Negative time values displayed in UI due to timezone mismatch - github / github_issue
• Installation risk requires verification - GitHub / issue