# https://github.com/OpenHands/OpenHands Project Manual Generated at: 2026-06-21 09:18:18 UTC ## Table of Contents - [Overview and System Architecture](#page-overview) - [App Server, Sandbox Services, and Integrations](#page-backend) - [Frontend Application and User Experience](#page-frontend) - [LLM Profiles, Models, and Sandbox Runtime](#page-llm-sandbox) ## Overview and System Architecture ### Related Pages Related topics: [App Server, Sandbox Services, and Integrations](#page-backend), [Frontend Application and User Experience](#page-frontend), [LLM Profiles, Models, and Sandbox Runtime](#page-llm-sandbox)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/OpenHands/OpenHands/blob/main/README.md) - [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md) - [skills/README.md](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md) - [openhands-ui/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/README.md) - [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md) - [enterprise/server/maintenance_task_processor/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/server/maintenance_task_processor/README.md) - [openhands/app_server/event_callback/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/event_callback/README.md) - [openhands/app_server/utils/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/README.md) - [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts) - [frontend/src/api/conversation-service/v1-conversation-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts) - [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts)
# 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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/README.md)). - A growing library of **skills/microagents** that inject expertise into agent prompts ([skills/README.md](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md)). ## 2. High-Level Component Architecture The system is composed of several loosely coupled layers that communicate over HTTP and WebSocket: ```mermaid flowchart TB User[User / Browser] FE[Frontend
Remix SPA + React] UI[openhands-ui
Component Library] AS[App Server
FastAPI] ENT[Enterprise Server
Keycloak + SaaS APIs] SBX[Sandbox Runtime
Docker / VM / Cloud] INT[Integration Services
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](https://github.com/OpenHands/OpenHands/blob/main/README.md); [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md); [openhands/app_server/utils/README.md](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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: | Feature | What it adds | Source | | --- | --- | --- | | LLM profiles | Named, persisted model + API-key combinations that can be swapped per conversation | [Release 1.8.0](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0) | | Sandbox grouping strategy | User-selectable policy for packing multiple agents into a single sandbox | [Release 1.8.0](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0) | | Sub-agent delegation | An agent can spawn child agents for subtasks | [Release 1.8.0](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0) | 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](https://github.com/OpenHands/OpenHands/issues/14800)) and that the in-app webview used for testing web apps is currently broken ([issue #14569](https://github.com/OpenHands/OpenHands/issues/14569)). The agent-server Docker image also needs `--no-sandbox` for headless Chromium ([issue #14779](https://github.com/OpenHands/OpenHands/issues/14779)), and `make docker-dev` leaves root-owned files in the host tree ([issue #13434](https://github.com/OpenHands/OpenHands/issues/13434)). On the API side, the Cloud runtime pool silently pauses older sandboxes when concurrency is exceeded instead of returning HTTP 429 ([issue #13126](https://github.com/OpenHands/OpenHands/issues/13126)). These known issues are good starting points when onboarding. ## See Also - [Frontend Architecture & Tooling](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md) - [Enterprise Architecture](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md) - [Event Callbacks & Webhooks](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/event_callback/README.md) - [Skills and Microagents](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md) - [Release 1.8.0 notes](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0) --- ## App Server, Sandbox Services, and Integrations ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [LLM Profiles, Models, and Sandbox Runtime](#page-llm-sandbox)
Related Source Files The following source files were used to generate this page: - [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md) - [openhands/app_server/sandbox/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/sandbox/README.md) - [openhands/app_server/app_conversation/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/app_conversation/README.md) - [openhands/app_server/user/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/user/README.md) - [openhands/app_server/utils/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/README.md) - [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts) - [frontend/src/api/git-service/git-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts) - [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts) - [frontend/src/api/conversation-service/v1-conversation-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts) - [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
# 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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/releases/tag/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](https://github.com/OpenHands/OpenHands/releases/tag/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](https://github.com/OpenHands/OpenHands/issues/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](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0). ```mermaid 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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md) and the linked [Authentication Flow](./authentication.md) and [External Integrations](./external-integrations.md) 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](https://github.com/OpenHands/OpenHands/issues/9354), [Issue #6468](https://github.com/OpenHands/OpenHands/issues/6468). ## Common Failure Modes | Symptom | Likely cause | Where to look | | --- | --- | --- | | `BrowserLaunchEvent` timeout, "Root CDP client not initialized" | `browser-use` launches Chromium without `--no-sandbox` inside the agent-server image | Issue #14779; review `DockerSandboxService` startup flags | | Cloud API silently stops new conversations | Concurrent runtime cap reached, older sandboxes auto-`PAUSED` | Issue #13126; check `V1SandboxStatus` transitions | | `make docker-dev` leaves root-owned files in the source tree | Dev container writes as root into mounted source | Issue #13434; adjust UID mapping in dev compose | | In-app browser cannot reach web apps | Missing CORS / `WEB_HOST` / `SANDBOX_CONTAINER_URL_PATTERN` | Issue #14569; Release 1.3.0 notes | | Editing one LLM profile rewrites another | Profile editor persists against a shared default record | Issue #14800; review LLM settings store | ## See Also - [Enterprise Architecture](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md) - [App Server Conversation Management](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/app_conversation/README.md) - [App Server Utilities & Extensibility](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/README.md) - [Frontend API: Sandbox Service](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts) - [Frontend API: Git Service](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts) - [OpenHands Release 1.8.0](https://github.com/OpenHands/OpenHands/releases/tag/1.8.0) --- ## Frontend Application and User Experience ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [LLM Profiles, Models, and Sandbox Runtime](#page-llm-sandbox)
Related Source Files The following source files were used to generate this page: - [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md) - [openhands-ui/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/README.md) - [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md) - [openhands/app_server/user/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/user/README.md) - [openhands/app_server/event_callback/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/event_callback/README.md) - [frontend/src/api/git-service/git-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts) - [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts) - [frontend/src/api/open-hands.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/open-hands.types.ts)
# 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](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md) Source: [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/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/`. ```mermaid 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](https://github.com/OpenHands/OpenHands/blob/main/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](https://bun.sh) 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](https://github.com/OpenHands/OpenHands/blob/main/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: ```ts static async retrieveUserGitRepositories( provider: string, pageId?: string, limit = 30, installationId?: string, ): Promise ``` The corresponding response types (e.g., `GitLabResource`, `BitbucketDCResource`) live in `integration-service.types.ts`, while shared domain models such as `Microagent`, `GitChange`, and `ResultSet` 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](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts) Source: [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts) Source: [frontend/src/api/open-hands.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/open-hands.types.ts) Source: [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/user/README.md) Source: [openhands/app_server/event_callback/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/event_callback/README.md) ## Development Workflow Two run modes are supported: | Mode | Command | Backend | When to use | | --- | --- | --- | --- | | Development (mocked) | `npm run dev` | MSW partial mock | UI work without a running app server | | Development (SaaS mock) | `npm run dev:mock:saas` | MSW SaaS mode | Working on auth and subscription UI | | Production-like | `make build` then `make run` | Real app server | End-to-end verification | 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](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md) ## See Also - [OpenHands App Server](../backend/app-server.md) - [openhands-ui Component Library](../frontend/openhands-ui.md) - [Skills and Microagents](../agents/skills-and-microagents.md) - [Testing Strategy](../testing/frontend-testing.md) --- ## LLM Profiles, Models, and Sandbox Runtime ### Related Pages Related topics: [App Server, Sandbox Services, and Integrations](#page-backend), [Frontend Application and User Experience](#page-frontend)
Related Source Files The following source files were used to generate this page: - [openhands/app_server/settings/llm_profiles.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/llm_profiles.py) - [openhands/app_server/settings/settings_models.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/settings_models.py) - [openhands/app_server/settings/settings_router.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/settings_router.py) - [openhands/app_server/config_api/llm_model_service.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/config_api/llm_model_service.py) - [openhands/app_server/config_api/default_llm_model_service.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/config_api/default_llm_model_service.py) - [openhands/app_server/utils/llm.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/llm.py) - [frontend/src/api/config-service/config-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/config-service/config-service.types.ts) - [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts) - [frontend/src/api/conversation-service/v1-conversation-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.api.ts) - [openhands/app_server/app_conversation/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/app_conversation/README.md)
# 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)](https://github.com/OpenHands/OpenHands/pull/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](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/llm_profiles.py), the persistence and validation schemas in [settings_models.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/settings_models.py), and the HTTP surface in [settings_router.py](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/settings/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](https://github.com/OpenHands/OpenHands/issues/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](https://github.com/OpenHands/OpenHands/blob/main/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`](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/config_api/llm_model_service.py) and its default implementation [`default_llm_model_service.py`](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/config_api/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`](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/config-service/config-service.types.ts): ```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`](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/config-service/config-service.types.ts) for the exact contract. ### Recent Model Additions Each release typically extends the catalogue. [Release 1.4.0 (PR #12835)](https://github.com/OpenHands/OpenHands/pull/12835) added `MiniMax-M2.5` model support, and [release 1.7.0 (PR #13616)](https://github.com/OpenHands/OpenHands/pull/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`](https://github.com/OpenHands/OpenHands/blob/main/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`](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts) as a finite set of states: | Status | Meaning | |------------|--------------------------------------------------------| | `MISSING` | Sandbox record exists but no live runtime is attached. | | `STARTING` | Runtime is being provisioned. | | `RUNNING` | Runtime is live and accepting requests. | | `PAUSED` | Runtime is intentionally suspended (resource control). | | `ERROR` | Runtime failed to start or crashed. | 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`](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/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`](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/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)](https://github.com/OpenHands/OpenHands/pull/14291), letting multiple conversations share a single sandbox when appropriate. - **`SANDBOX_KVM_ENABLED`** — added in [release 1.7.0](https://github.com/OpenHands/OpenHands/releases/tag/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](https://github.com/OpenHands/OpenHands/releases/tag/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](https://github.com/OpenHands/OpenHands/issues/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](https://github.com/OpenHands/OpenHands/issues/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 ```mermaid 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](https://docs.openhands.dev/openhands/usage/agent-canvas/backends) - [OpenHands V1 Architecture](https://docs.openhands.dev/openhands/usage/architecture/backend) - [Frontend API Conventions](./frontend-api-conventions.md) - [Conversations and Tasks](./conversations-and-tasks.md) --- --- ## Pitfall Log Project: OpenHands/OpenHands Summary: 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 - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13827 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13647 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14912 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14882 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - 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. - Repro command: `docker run -it --rm -p 8000:8000 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.0.0-rc.11` - Evidence: identity.distribution | https://github.com/OpenHands/OpenHands ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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 - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/8768 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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 - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13827 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: [Bug]: Pending Messages Not Sent After Conversation Is Ready - User impact: Developers may fail before the first successful local run: [Bug]: Pending Messages Not Sent After Conversation Is Ready - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13716 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE - User impact: Developers may fail before the first successful local run: [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13647 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/8768 ## 16. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13716 ## 17. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/OpenHands/OpenHands ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.2.0 - 2026-01-15 - User impact: Upgrade or migration may change expected behavior: 1.2.0 - 2026-01-15 - Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.2.0 ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.3.0 - 2026-02-02 - User impact: Upgrade or migration may change expected behavior: 1.3.0 - 2026-02-02 - Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.3.0 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Port Jira Data Center Integration to Plugin Architecture - User impact: Developers may misconfigure credentials, environment, or host setup: Port Jira Data Center Integration to Plugin Architecture - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12976 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [Enterprise] Admin setting for auto-delete of inactive user data after X days - User impact: Developers may misconfigure credentials, environment, or host setup: [Enterprise] Admin setting for auto-delete of inactive user data after X days - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12656 ## 22. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [Feature]: option to send message when pressing enter, not create a new line - User impact: Developers may misconfigure credentials, environment, or host setup: [Feature]: option to send message when pressing enter, not create a new line - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14861 ## 23. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14148 ## 24. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/12976 ## 25. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/OpenHands/OpenHands ## 26. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: 1.8.0 - 2026-06-10 - User impact: Upgrade or migration may change expected behavior: 1.8.0 - 2026-06-10 - Evidence: failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.8.0 ## 27. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: [Feature]: Introduce support for displaying queued messages in the conversation UI - User impact: Developers may hit a documented source-backed failure mode: [Feature]: Introduce support for displaying queued messages in the conversation UI - Evidence: failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14181 ## 28. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/OpenHands/OpenHands ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/OpenHands/OpenHands ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/OpenHands/OpenHands ## 31. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands/issues/12714 ## 32. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/OpenHands/OpenHands ## 33. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/OpenHands/OpenHands