OpenHands / the product, behavior by behavior openhands-features

The feature map,
for humans.

What a user can do in Agent Canvas, how to take that path, and what should happen next. Each family has its own page: readable scripts, literal commands, expected observations, and real screenshots.

families: 27
behaviors: 743
recipes & checks: 722

A snapshot of upstream main at 8793c111 · 9 October 2026.
The maintained map owns the inventory. The verification story, CLI guide and issues list explain how it came about.

Choose a family

Starting work

F01

First run, onboarding and sign-in

What a user sees before the normal app shell.

22 behaviors · 26 recipesopenhands-features F02

App shell, sidebar and command menu

Every page inside the root layout shares one shell.

26 behaviors · 26 recipesopenhands-features F03

Home and starting work

Home is the "What do you want to work on?" screen at `/` and `/conversations`.

39 behaviors · 34 recipesopenhands-features F04

Conversation list and folders

The expanded sidebar always shows the user's conversations under a **Conversations** header.

40 behaviors · 40 recipesopenhands-features

Conversation & workspace

F05

Composer, slash commands and plan mode

The composer is the input box at the bottom of the home page and of every conversation.

25 behaviors · 27 recipesopenhands-features F06

Agent activity: messages, events and lifecycle

Inside a conversation the user watches the agent work: their own messages appear at once (optimistically), the agent's replies render as markdown, tool calls are grouped into collapsible "N actions completed" blocks whose cards show commands, outputs, diffs and task lists, and a live chip says what the agent is doing right now.

35 behaviors · 28 recipesopenhands-features F07

Conversation page, header and management menu

The conversation page (`/conversations/<id>`) shows the chat pane: a header with the runtime status dot, the editable title, the "..." management menu and the Git actions, Overview and panel toggles, then the message history and the composer.

25 behaviors · 26 recipesopenhands-features F08

Workspace drawer: files and changes

Next to the chat, a conversation has a right-hand drawer with tabs.

33 behaviors · 31 recipesopenhands-features F27

Workspace tools: terminal, browser, planner, tasks and usage

The conversation's right-hand drawer holds the agent's workspace tools: a read-only Terminal that mirrors the agent's shell commands, a Browser tab that shows the agent browser tool's last screenshot, a Planner that renders `.agents_tmp/PLAN.md` (or starts a planning helper), a Task List that mirrors the agent's `task_tracker`, and a Usage tab with the context meter, a manual "Compact context" action and token/cost totals.

30 behaviors · 21 recipesopenhands-features

Settings & configuration

F09

Settings shell and navigation

Settings is one shell around eight pages (Agent, LLM, Model Router, Condenser, Agent Context, Verification, Application, Secrets).

25 behaviors · 21 recipesopenhands-features F10

LLM profiles

An LLM profile is a named model configuration: provider and model (or a custom model and base URL), an API key or a ChatGPT subscription, an optional provider-connection link, and every advanced LLM option.

34 behaviors · 33 recipesopenhands-features F11

Provider connections

A provider connection is a named, shared credential (provider, API key, optional base URL) that many LLM profiles link to instead of carrying their own key.

21 behaviors · 23 recipesopenhands-features F12

Model router (meta-LLM profiles)

A model router (the UI also calls it a "meta-profile") names a classifier LLM profile, a prompt template and a model table.

25 behaviors · 23 recipesopenhands-features F13

Agent profiles

Settings → Agent is a library of named agent profiles.

20 behaviors · 21 recipesopenhands-features F14

Secrets

Secrets are named values the agent can use during conversations.

11 behaviors · 14 recipesopenhands-features F15

Condenser, agent context and verification settings

Three settings pages are generated from the Agent Server's settings schemas: **Condenser** (summarize long chats), **Agent Context** (persistent agent memory) and **Verification** (confirmation mode, security analyzer and the critic).

23 behaviors · 24 recipesopenhands-features F16

Application settings

Settings → Application holds the user's app-wide preferences: UI language, colour theme, anonymous usage data, sound notifications, the sidebar Getting Started checklist, which LLM profile writes conversation titles, an optional voice-input transcription endpoint, and the git identity used for commits.

19 behaviors · 21 recipesopenhands-features

Customization

F17

Customize hub and MCP servers

Customize groups MCP Servers, Skills, Plugins and Apps behind one sidebar entry.

30 behaviors · 30 recipesopenhands-features F18

Skills catalog

The Skills page (Customize → Skills, `/skills`) lists every skill the backend can load: the built-in catalog bundled with the frontend plus personal and project skills reported by the Agent Server.

22 behaviors · 27 recipesopenhands-features F19

Plugins and plugin launch

Plugins bundle skills, commands and files that the agent loads into a conversation.

25 behaviors · 27 recipesopenhands-features F20

Canvas apps

Canvas apps (Canvas Extensions) are trusted browser modules installed on the active local Agent Server.

24 behaviors · 26 recipesopenhands-features

Automations

F21

Automations dashboard and actions

The Automate dashboard (`/automations`) is where a user sees every automation at a glance and acts on one without opening it.

34 behaviors · 34 recipesopenhands-features F22

Creating automations: templates, setup and import

A user adds an automation in three ways.

29 behaviors · 29 recipesopenhands-features F23

Automation detail, runs and editing

The detail page (`/automations/<id>`) shows one automation: a **Back to Automations** link, a header with the name, an **Active**/**Inactive** badge, **Run now**, an on/off switch and a kebab (Export, Tarball, Edit, Turn on/off, Delete); a **Why this is paused** banner when it was turned off; the Prompt (or, for a script automation, the Script bundle); Configuration (repositories, trigger, schedule or event source/type/filter, LLM profile); a **Plugins** card when it has plugins; an Activity card (Created, Last run); and the **Activity Log** of runs with status, summary, cost, a logs dialog, a link to each run's conversation and JSON/CSV export.

39 behaviors · 29 recipesopenhands-features F24

Automation Git Sync

Git Sync keeps an organization's automation definitions in a git repository.

26 behaviors · 26 recipesopenhands-features

Backends & runtimes

F25

Backends, Cloud and sharing

One Canvas can drive several agent servers.

29 behaviors · 27 recipesopenhands-features F26

Launcher modes, Docker, desktop and library

Agent Canvas ships one UI in several runtime shapes.

32 behaviors · 28 recipesopenhands-features

Before you start

The CLI drives an installed OpenHands checkout. It launches an isolated real stack, keeps a browser open between actions, and records evidence. Run it from the checkout directory with Node 24 or later, installed npm dependencies, uv/uvx, and a supported Chromium browser. The skill has the complete setup and run contract.

export PATH="$PWD/.agents/skills/verify-openhands/scripts:$PATH"
export OH_VERIFY_RUN=$(control-openhands launch --new --print-run)
control-openhands doctor
control-openhands onboard --skip
# For model-backed recipes, with your configured DeepSeek key:
control-openhands llm preset deepseek
# When finished:
control-openhands stop

Walk onboarding instead of skipping it when F01 is the subject. Start no-LLM checks before configuring a model. Keep OH_VERIFY_RUN set so every command addresses your own run. Desktop is 1440 × 1000; phone is 390 × 844.

Fixtures, API writes and LLM presets arrange preconditions. The user path is proved through the real UI. After saving or deleting, observe again: reload, reopen, or make a read-only API check. Record each actual result with evidence add: pass, fail, blocked, or not-run.

Use deepseek-flash for small model checks and keep prompts confined to the run workspace. Add Do not run any tools when the check only needs a reply. Cloud, enterprise, microphones, Docker and desktop recipes require the environment named in their preconditions.

How to read the scripts

Each recipe keeps the maintained map’s order and exact code. Numbered rows separate actions and checks; prose explains the expected result. Short forms and placeholders remain as documented. A known failure or blocked prerequisite stays visible.

Selected recipes have fresh screenshots captured with control-openhands browser screenshot from this pinned checkout. Each caption states its scope, and the capture commands are available below it. A screenshot demonstrates the pictured state; API persistence, downloads, sound and timing still need their stated observations. Mapped behaviors are an inventory, not a fresh all-pass ledger.

This category mirrors a dated source revision. The earlier presentation and issue list retain their original dates and counts. Download the category inventory and provenance.

Coverage boundaries from the maintained map

Everything else a user can reach is mapped. These are left out on purpose:

src/components/features/context-menu: a shared menu primitive, not a feature of its own. Its behavior is checked through the menus that use it (F04, F07, F21, F27).
OpenHands Cloud behavior (Cloud login and device flow, organizations, sharing, task URLs, sandbox pause): needs a Cloud account. The recipes are written up to that point and recorded as blocked (for example F07.cloud-only and the Cloud rows of F25).
Suspended Cloud workspaces (src/components/features/backends/cloud-organization-boundary.tsx, #17988): Mapped prerequisites/local absence: F25.cloud-org-suspended records the expected alert and the prerequisite; a local backend can check only that the Cloud suspension surface is absent. Positive paths not live-mapped: the selected Cloud organization must receive a genuine scoped HTTP 403 with detail: "Organization is suspended" or detail: "User membership is suspended"; recovery also needs another accessible workspace. Desktop/phone alerts, workspace switching and request/backend/organization isolation remain blocked until those genuine states are available. An unrelated 403 is not that prerequisite.
Enterprise Super Admin setup guide (src/components/features/setup-guide, #17969): Mapped prerequisites/local absence: F02.super-admin-setup-guide records its prerequisites and the local check for no guide or /api/admin/setup-state request. Positive paths not live-mapped: an authenticated enterprise Cloud backend must have a selected organization whose /me permissions include manage_super_admins, plus a genuine /api/admin/setup-state response with a non-null guide_org_id, guide_dismissed: false, and at least one unfinished required guide step. A local backend cannot establish those prerequisites. Progress, step destinations, collapse/reopen, server-driven guide removal, progress persistence and desktop/phone layouts remain blocked until an entitled account can drive them; source inspection is not runtime proof.
Setup-guide continuation and Canvas tours (#18138, src/components/features/setup-guide/, src/components/features/manifest/manifest-setup-dialog.tsx, src/hooks/mutation/use-add-mcp-server.ts) are not live-mapped. They share F02.super-admin-setup-guide's genuine Cloud account and setup-state prerequisites above, with the next required step set to first-automation or add-integration. Verification additionally needs a successful direct automation creation or MCP-server addition and a subsequent server response confirming that step complete; assisted setup and out-of-order or unconfirmed completion have different control flow. The next Canvas step/tour, Cloud-host same-tab invitation handoff with org and setup_tour, standalone/Electron Start fallback, and tour entry via setup_tour remain blocked across desktop/phone and those deployment boundaries. The invitation handoff also needs an accessible enterprise invitation page for the guide organization. No positive recipe is accepted from source or mocked enterprise responses.
Locked-to-Cloud deployments: scripts/static-server.mjs --lock-to-cloud exists, but bin/agent-canvas.mjs does not forward it, so control-openhands launch cannot start that mode.
Page-local load errors (for example the LLM profiles or apps list failing while the rest of the backend works) need fault injection; stopping a service with service stop replaces the whole app with the backend-unavailable screen instead. The pages' empty and error copy is mapped where reachable.
Real microphone dictation, native file dialogs outside the browser, and Electron window chrome beyond what F26 drives.

The approach adapts Lauren Tan’s (@poteto) pstack verification-skill generators. Read the adaptation and attribution.