Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 ships 12 features spanning a new Electron desktop app (macOS + Windows), richer plugin inspection, MCP server connection-health indicators, a one-click restart banner for chat-installed skills, a title-generation profile preference, an update-availability card in Settings, and several Cloud-aware navigation changes. There are no breaking changes, but at least five features introduce user-facing UI that is not yet covered in the docs.

Release notes source: https://github.com/OpenHands/agent-canvas/releases/tag/v1.6.0

This issue was drafted by an AI agent (OpenHands) on behalf of a maintainer.

---

What changed in the release

Features

• Electron desktop app for macOS and Windows (#1864, #1911, #1897)
  Agent Canvas now ships as a native desktop application via Electron. On macOS, users can download a .dmg installer; on Windows, an NSIS installer is produced. The app bundles the agent-server and automation service, starts them automatically, and displays a loading splash screen while services come up. The splash screen includes an expandable startup-log console (PR #1878) that shows service startup output, with error-level lines highlighted in red, a "Copy" button for all buffered log lines, and a "Quit" button. Once services are ready, the main browser window opens. Cmd-Q / closing the window tears down all background processes cleanly.

• One-click restart banner for chat-installed skills (#1830)
  When an agent installs a skill during a conversation (via fetch_skill.py or similar), a banner now appears above the composer naming the installed skill. The banner offers two actions: dismiss it, or click "Start new conversation with this skill" to open a fresh conversation that loads the newly installed skill. If a second skill-install event occurs, the banner resurfaces. This makes skill activation discoverable — previously, users had to manually start a new conversation to pick up a chat-installed skill.

• MCP server connection-health indicators on installed server cards (#1833)
  Each installed MCP server card in the Customize > MCP Servers area now shows live connection status. Cards cycle through a "checking" state and then display either a green healthy indicator or a red failure indicator. Failures are categorized: credential failures show "Credential check failed" with the HTTP status code and offer "Retry", "Update credentials", and "View documentation" actions; connection failures (unreachable host) show "Connection failure" with a "Retry" action. This gives users actionable next steps when an MCP server is misconfigured.

• Plugin detail modal shows plugin contents (#1690)
  Clicking a plugin in the Customize > Plugins page now opens a detail modal that shows what the plugin contains, not just its metadata. The modal has two new sections: a "Skills in this plugin bundle" section with a card per bundled skill (icon, name, description — including command-derived skills like city-weather:now), and a "Files" section with an expandable directory tree and an inline syntax-highlighted file viewer. Re-clicking the selected file closes the viewer. Binary files and load errors display appropriate fallback content.

• Cloud-aware Skills/Plugins navigation and new Integrations link (#1890)
  When the active backend is a Cloud backend, the sidebar navigation changes: "Customize > Skills" relabels to "Skills and Plugins" and links to the Cloud settings skills page (opens in a new tab); the separate "Plugins" item disappears from the Customize sub-nav; "MCP Servers" remains an in-app link. In the Settings sidebar, the "Cloud" link is renamed to "All Cloud Settings" and a new "Integrations" link is added. These changes are invisible on local backends.

• Update-availability card in Settings (#1898)
  A new card in the Settings page shows whether a newer version of Agent Canvas is available on npm. When the installed version matches the latest, it shows a green "Up to date" badge. When a newer version is available, the card displays the available version and provides an update prompt. This helps users stay on current releases without checking npm manually.

• Title generation profile preference (#1910)
  Users can now choose which LLM profile to use for automatic conversation title generation, independent of the agent profile. The setting appears in Settings > Application under a "Conversation titles" section. This is useful when the agent LLM is expensive or slow — users can select a cheaper, faster profile specifically for title generation.

• Expandable startup-log console on desktop loading screen (#1878)
  The desktop app loading splash screen now has a "Show details" toggle that expands to show a scrolling log console. The window resizes from 460×360 to 460×560. Error-level lines are shown in red. A fatal error message produces a failure state. A "Copy" button copies all buffered lines to the clipboard. This is primarily a troubleshooting aid during desktop startup.

• Cloud org ID and automation telemetry context (#1924, #1917)
  Internal telemetry now includes Cloud organization ID and automation run context. Not user-facing; no documentation needed.

Bug Fixes

• Cloud backend reconnect modal fixed (#1807)
  Previously, when a Cloud backend's authentication expired, the recovery modal showed generic backend-management controls. Now it shows a focused "Reconnect to Cloud" flow. This changes the user experience described in any Cloud backend reconnection docs.

• Secret values preserved on edit (#1889)
  Editing a secret's name or description in Settings > Secrets no longer silently drops the secret's value. On rename, the old secret entry is also cleaned up. This fixes a bug in documented secrets management workflows.

• LLM Profiles remain reachable during ACP agent sessions (#1915)
  A UI deadlock prevented navigating to Settings > LLM when an ACP agent profile was active. Now the LLM Profiles page is always reachable. Relevant to ACP agent onboarding documentation.

• Streaming and reconnect fixes (#1865, #1896)
  Duplicate rendering of streamed reasoning events and reconnect side-effects were fixed. Not directly doc-relevant.

• Paginated workspace folder listings fixed (#1566)
  Workspace selection now correctly handles paginated folder listings. Not directly doc-relevant.

Maintenance

• @openhands/extensions bumped to 0.11.0 (#1880)

• software-agent-sdk bumped to 1.37.0, automation to 1.2.0 (#1906)

• automation bumped to 1.3.1 (#1934)

  Docs do not currently cite specific Agent Canvas dependency versions. No doc changes needed unless a guide references an SDK version floor.

---

Current doc coverage

Already covered (relevantly)

• openhands/usage/agent-canvas/setup.mdx — covers npm, npx, Docker, VM, and from-source installation methods. Does not mention desktop/Electron install.
• openhands/usage/agent-canvas/plugins.mdx — covers plugin browsing, installing, enabling/disabling, and attaching to conversations. Mentions the detail modal but does not describe the new "Skills in this plugin bundle" or "Files" sections.
• openhands/usage/agent-canvas/customize-and-settings.mdx — describes the Customize vs Settings separation. Lists current Settings sections (Agent, LLM, Condenser, Verification, Application, Secrets). Does not mention the "Conversation titles" subsection or the update-availability card.
• openhands/usage/settings/mcp-settings.mdx — covers MCP protocol, configuration, and usage. Does not mention per-server connection health indicators or the credential/connection failure UI.
• openhands/usage/settings/application-settings.mdx — covers budget and Git author settings. Does not mention the new title generation profile preference.
• openhands/usage/settings/secrets-settings.mdx — covers secret CRUD. States "you cannot view or edit the value of an existing secret" — the secret-preservation fix (#1889) doesn't contradict this (values are still hidden), but editing name/description now correctly preserves the value.
• openhands/usage/agent-canvas/llm-profiles.mdx — covers LLM profiles and switching. Does not reference title-generation profile usage.
• openhands/usage/agent-canvas/conversations.mdx — covers conversation branching. Does not mention the skill-install restart banner.
• openhands/usage/agent-canvas/backends.mdx — covers backend management. Does not mention the updated Cloud reconnect flow.
• openhands/usage/agent-canvas/first-time-setup.mdx — covers four-step wizard. Not affected by v1.6.0 changes.

Still missing or thin

1. Desktop app installation — No page or section covers the Electron desktop app (macOS .dmg, Windows NSIS installer), startup behavior, the loading screen, or the startup-log console.
2. Skill-install restart banner — No docs describe the banner that appears when an agent installs a skill mid-conversation.
3. MCP server connection-health indicators — The MCP settings page does not describe the per-server health status UI, failure categories, or the retry/update-credentials/view-documentation actions.
4. Plugin detail modal contents — The plugins page mentions inspecting plugins but does not describe the new "Skills in this plugin bundle" or "Files" sections in the detail modal.
5. Title generation profile preference — Not mentioned in Application Settings or LLM Profiles pages.
6. Update-availability card — Not mentioned anywhere.
7. Cloud-aware navigation changes — The customize-and-settings page doesn't describe the behavioral differences when a Cloud backend is active (relabeled nav items, hidden Plugins item, new Integrations link).

---

Proposed doc work

1. Add "Desktop app" install method to openhands/usage/agent-canvas/setup.mdx

Type: Section addition to existing page

Add a new row to the "Choose An Install Method" table:

Method	Use It When	What The Agent Can Access
Desktop app	You want a native macOS or Windows app with no terminal commands.	Runs directly on your machine; bundles the agent-server and automation service.

Add a new ## Desktop App section (after the existing npm/Docker/npx sections) covering:

• Prerequisites: macOS (Apple Silicon or Intel) or Windows 10+; no npm or uv needed for end users
• Install on macOS: download the .dmg from the GitHub Releases page, drag to Applications, open the app (note the Gatekeeper prompt on first launch)
• Install on Windows: download the .exe installer from GitHub Releases, run the installer, launch from the Start menu
• Startup behavior: the app shows a loading splash screen while the agent-server and automation service start; explain the "Show details" toggle for the startup-log console (useful for troubleshooting); once services are healthy, the main Agent Canvas UI opens automatically
• Quit: closing the app stops all background services
• Update: mention the update-availability card in Settings (cross-link to proposed work item 6)
• Reference PRs: #1864, #1911, #1897, #1878

2. Add "Skill install notifications" section to openhands/usage/agent-canvas/conversations.mdx

Type: Section addition to existing page

Add a ## Skill install notifications section (after "What branching preserves") explaining:

• When an agent installs a skill during a conversation, a banner appears above the composer
• The banner names the installed skill
• Two actions: dismiss the banner, or click "Start new conversation with this skill" to launch a new conversation that loads the skill
• If multiple skills are installed, the banner resurfaces for each
• Explain why a new conversation is needed (skills load at conversation start)
• Reference PR: #1830

3. Add "Connection health" section to openhands/usage/settings/mcp-settings.mdx

Type: Section addition to existing page

Add a ## Connection health section (after the existing configuration content) covering:

• Each installed MCP server card shows live connection status
• Status indicators: checking (spinner), healthy (green), failed (red)
• Failure types:
  • Credential failure: "Credential check failed" with HTTP status; actions: "Retry", "Update credentials", "View documentation"
  • Connection failure: server unreachable; action: "Retry"
• What to do when a server shows a credential failure (check API key, re-authenticate)
• What to do when a server shows a connection failure (check URL, ensure service is running)
• Reference PR: #1833

4. Update plugin detail modal description in openhands/usage/agent-canvas/plugins.mdx

Type: Section addition to existing page

The page already has content about inspecting plugins. Add or expand a ## Inspect plugin contents section covering:

• Clicking a plugin card opens the detail modal
• The modal now shows two additional sections beyond metadata:
  • Skills in this plugin bundle: a card per bundled skill with icon, name, and description (includes command-derived skills)
  • Files: an expandable directory tree of the plugin directory; clicking a file shows syntax-highlighted content inline; clicking it again closes the viewer; binary files show a fallback notice
• Reference PR: #1690

5. Document title generation profile preference

Type: Section additions to two existing pages

a) openhands/usage/settings/application-settings.mdx — add a ## Conversation title generation section:

• Agent Canvas automatically generates a title for new conversations
• By default, it uses the active agent's LLM profile for title generation
• In Settings > Application, under "Conversation titles", you can select a different LLM profile for title generation
• Use case: pick a cheaper or faster profile so title generation doesn't use expensive agent model tokens
• Reference PR: #1910

b) openhands/usage/agent-canvas/llm-profiles.mdx — add a brief mention in the introductory section that LLM profiles are also used for title generation, and link to the Application Settings page.

6. Document update-availability card (Optional)

Type: Section addition to openhands/usage/agent-canvas/setup.mdx or openhands/usage/agent-canvas/customize-and-settings.mdx

Add a short ## Check for updates section:

• A card in Settings shows whether a newer Agent Canvas version is available on npm
• States: "Up to date" (green badge) or displays the available version with an update prompt
• To update, run npm install -g @openhands/agent-canvas@latest (or re-download the desktop installer)
• Reference PR: #1898

7. Document Cloud-aware navigation changes (Optional)

Type: Section addition to openhands/usage/agent-canvas/customize-and-settings.mdx

Add a ## Cloud backend differences section (or a <Note> block) explaining:

• When the active backend is a Cloud backend, the Customize sub-nav changes:
  • "Skills" relabels to "Skills and Plugins" and links to the Cloud settings page (opens in a new tab)
  • The separate "Plugins" nav item is hidden
  • "MCP Servers" remains as an in-app link
• In Settings, "Cloud" is renamed to "All Cloud Settings" and a new "Integrations" link appears
• These changes only apply when connected to a Cloud backend; local backends show the standard layout
• Reference PR: #1890

---

Notes for the implementer

Key PRs to reference

• Desktop app: #1864 (initial Electron), #1911 (macOS build + docs), #1897 (Windows build + docs), #1878 (startup-log console)
• Skill restart banner: #1830
• MCP connection health: #1833
• Plugin detail modal: #1690
• Cloud-aware nav: #1890
• Update-availability card: #1898
• Title generation profile: #1910
• Cloud reconnect fix: #1807 (may warrant a note in backends docs)
• Secret preservation fix: #1889 (no doc change needed — existing text is still accurate)

Technical context

• The desktop app bundles the same agent-server used by the npm/npx install paths; the user experience inside the app is identical to the browser-based Agent Canvas. The key difference is installation method and startup (Electron splash vs terminal).
• MCP connection health is a client-side UI feature — it calls the existing MCP health-check endpoint exposed by the agent server. No new configuration is needed from the user.
• The plugin detail modal fetches plugin contents from new optional fields (path, skills, files) on the existing plugins API endpoint. No user-side setup required.
• The title generation profile preference is a new field in the application settings API (title_llm_profile_id). It defaults to the agent's LLM profile when unset.

Style reminders

• Follow openhands/DOC_STYLE_GUIDE.md: sentence-case headings in nav, present tense, fenced code blocks for commands, absolute internal doc links (e.g. /openhands/usage/agent-canvas/setup)
• If adding a new page, update docs.json navigation under the Agent Canvas tab
• Run mint broken-links after edits to catch dead links