Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 introduces 8 user-facing features, headlined by the new Electron desktop app (macOS and Windows installers), a plugin contents viewer in the plugin detail modal, and one-click restart for chat-installed skills. There are no breaking changes. Several UI additions in Settings and the Customize sidebar also need documentation — including MCP connection health indicators, a title-generation profile preference, cloud-aware navigation changes, and an update-availability card.

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 — macOS and Windows installers (#1864, #1911, #1897)
  Agent Canvas is now available as a standalone desktop application. On macOS, users download Agent-Canvas-<version>-arm64.dmg, drag the app to Applications, and run xattr -d com.apple.quarantine on it (required because the app is ad-hoc signed). On Windows, users download Agent-Canvas-Setup-<version>.exe and run the NSIS installer. The desktop app bundles its own Node and uv runtimes, starts the agent-server and automation backend automatically, and presents a loading splash screen during startup. Intel macOS is not distributed as a pre-built binary — users must build from source. The loading screen includes an expandable startup-log console (#1878) where users can click "Show details" to see real-time agent-server boot logs, copy them for debugging, or quit if startup fails.

• Plugin contents in the plugin detail modal (#1690)
  Clicking a plugin card in Customize > Plugins now opens a detail modal that shows what the plugin contains. The modal includes a "Skills in this plugin bundle" section listing each bundled skill (icon, name, description — including command-derived skills), and a "Files" section with an expandable directory tree and inline syntax-highlighted file viewer. Re-clicking a selected file closes the viewer. These fields are optional; older agent-server versions show the existing metadata-only view.

• One-click restart to activate chat-installed skills (#1830)
  After a user installs a skill in-chat via /add-skill, a banner now appears above the composer saying the skill was installed. The banner names the installed skill and offers two actions: "Dismiss" and "Start new conversation with this skill". Clicking the restart button creates a new conversation with the skill's workspace as the selected workspace. This is needed because the SDK loads skills once per conversation — a freshly installed skill is inert until a new conversation begins.

• Actionable MCP connection health on installed server cards (#1833)
  Installed MCP server cards in Customize > MCP Servers now display persistent connection health status instead of only showing test results in a transient modal. Each card goes through a "checking" state, then shows green (healthy), red with a "credentials" failure label, or red with a "connection" failure label. Failed cards show action buttons: "Retry", "Update credentials", and "View documentation". Secrets in error messages are redacted (shown as **********). Fixing a server's URL or credentials in the editor and saving flips the card to healthy without a page reload.

• Cloud-aware Skills/Plugins navigation and new Integrations link (#1890)
  When the active backend is an OpenHands Cloud backend: the Customize > Skills item relabels to "Skills and Plugins" and becomes an external link opening {cloudHost}/settings/skills in a new tab; the Plugins item is hidden entirely; Settings > Cloud is renamed to "All Cloud Settings"; and a new Settings > Integrations item appears linking to {cloudHost}/settings/integrations/ in a new tab. When the active backend is local, the navigation is unchanged.

• Agent Canvas update-availability card in settings (#1898)
  A new card appears on the Settings page that checks the npm registry for newer versions of @openhands/agent-canvas. It shows one of three states: a green "Up to date" badge with the current version and a link to release notes; an "Update available" badge showing the new version number; or a quiet inline message if the registry is unreachable. Users can click "Check for updates" to bypass the 1-hour cache. The card also displays the two update commands (npm update -g @openhands/agent-canvas and npx @openhands/agent-canvas@latest).

• Title generation profile preference (#1910)
  A new "Conversation titles" section under Settings > Application lets users choose which LLM profile generates conversation titles. The default is "Automatic" (resolves to the active local profile). Users can pick any saved LLM profile — useful for choosing a cheaper or faster model for title generation instead of using the agent's primary LLM. The preference persists across sessions and stays consistent when profiles are renamed or deleted.

• Cloud org ID and automation telemetry context (#1924, #1917)
  Internal telemetry change — no documentation needed.

Bug Fixes

• Preserve secret values on edit (#1889)
  Previously, editing or renaming a secret in Settings > Secrets could lose the stored value. Secrets now preserve their values on edit, and renaming a secret correctly deletes the old entry. This fix corrects behavior that users of the Secrets page would notice.

• Keep LLM Profiles reachable while an ACP agent is active (#1915)
  When an ACP agent (e.g., Claude Code) was the active agent profile and no LLM profiles existed, the Settings > LLM sidebar item was disabled and the page redirected to Settings > Agent, locking users out. LLM Profiles are now always reachable regardless of the active agent type.

• Fix paginated workspace folder listings (#1566)
  The "Add Workspace" folder browser previously only showed the first page of subdirectories. Users with many folders now see all of them.

• Streaming and reconnect fixes (#1865, #1896, #1807)
  Internal rendering and reconnect improvements — no documented behavior changes.

Maintenance

• Bump @openhands/extensions to 0.11.0 (#1880)
• Bump software-agent-sdk to 1.37.0 and automation to 1.2.0 → 1.3.1 (#1906, #1934)
• CI, refactor, and Helm maintenance (#1861, #1873, #1884)

---

Current doc coverage

Already covered (relevantly)

Page	Path	Relevance
Install	openhands/usage/agent-canvas/setup.mdx	Covers npm, npx, Docker, VM, and from-source install methods. Does not mention the desktop app. The install method table and "Choose An Install Method" section need a new row/tab.
Plugins	openhands/usage/agent-canvas/plugins.mdx	Mentions "Inspect plugin details" in the feature list but does not describe the new contents view (skills list, file tree, file viewer).
Customize and Settings	openhands/usage/agent-canvas/customize-and-settings.mdx	Lists Settings sections (Agent, LLM, Condenser, Verification, Application, Secrets). Does not mention the update-availability card, cloud-aware nav, Integrations link, or title generation preference.
LLM Profiles	openhands/usage/agent-canvas/llm-profiles.mdx	Covers profile creation and /model switching. Does not mention the title-generation profile preference.
Conversations	openhands/usage/agent-canvas/conversations.mdx	Mentions conversation titles exist but does not cover the title-generation profile setting.
MCP Settings	openhands/usage/settings/mcp-settings.mdx	Covers MCP server configuration. Does not mention the new persistent connection health indicators on server cards.
Troubleshooting	openhands/usage/agent-canvas/troubleshooting.mdx	Existing troubleshooting page. No desktop-specific troubleshooting content.

Still missing or thin

1. Desktop app install path — No documentation exists for the Electron desktop app. The setup.mdx page needs a new install method (tab, table row, prerequisites, install steps, macOS quarantine workaround, Windows installer steps, and uninstall).
2. Plugin contents viewer — The plugins page mentions "Inspect plugin details" but does not describe the new skills-list and file-tree sections in the modal.
3. Skill install-and-restart flow — No mention of the /add-skill restart banner anywhere in docs.
4. MCP connection health indicators — Not covered in mcp-settings.mdx or anywhere else.
5. Cloud-aware navigation behavior — Not documented. The customize-and-settings.mdx page does not explain that nav items change when a Cloud backend is active.
6. Update-availability card — Not mentioned on any page.
7. Title generation profile preference — Not covered in customize-and-settings.mdx, llm-profiles.mdx, or conversations.mdx.

---

Proposed doc work

1. Add desktop app install method to setup.mdx

Type: Section addition to existing page
File: openhands/usage/agent-canvas/setup.mdx

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 self-contained app with no manual dependency setup.	Bundles its own Node and uv runtimes. Runs directly on your machine.

Add a new <Tab title="Desktop app"> inside each tabbed section:

• Verify Prerequisites: No prerequisites — the app bundles Node and uv. Note that macOS Intel is not supported as a pre-built binary (build from source instead).
• Install And Run: Download the .dmg (macOS) or .exe (Windows) from the GitHub Releases page. macOS: drag to Applications, then run xattr -d com.apple.quarantine /Applications/Agent\ Canvas.app because the app is ad-hoc signed and macOS quarantines downloaded unsigned apps. Windows: run the NSIS installer and follow the prompts. On launch, the app shows a loading splash while the agent-server starts; click "Show details" to expand the startup log console.
• Update: Describe the update-availability card in Settings (or link to new section, see item 6).
• Uninstall: macOS: move the app to Trash. Windows: use the system uninstaller ("Add or remove programs").

Also add a row to the existing table and update the <Note> recommending first-time users.

2. Expand plugin detail modal documentation in plugins.mdx

Type: Section addition to existing page
File: openhands/usage/agent-canvas/plugins.mdx

Under the existing "Open the Plugins Area" section (or as a new "## Inspect Plugin Contents" section after "Installed and Local Plugins"), add:

• Explain that clicking a plugin card opens a detail modal
• Describe the "Skills in this plugin bundle" section: lists each bundled skill with its icon, name, and description, including command-derived skills (e.g., city-weather:now)
• Describe the "Files" section: expandable directory tree showing the plugin's file structure, with an inline syntax-highlighted viewer for selected files; re-clicking a file closes the viewer; binary files show a fallback message
• Note that these sections only appear when the agent-server provides plugin content metadata; older backends show metadata only

3. Document the skill install-and-restart banner

Type: Section addition to existing page
File: openhands/usage/agent-canvas/customize-and-settings.mdx (Customize section)

Add a subsection under "## Customize" (e.g., "### Installing skills from chat") explaining:

• Users can install skills mid-conversation using the /add-skill <github-url> command
• After a successful install, a banner appears above the composer naming the installed skill
• The banner offers "Dismiss" and "Start new conversation with this skill"
• Clicking the restart button creates a new conversation with the skill's install directory as the workspace
• Explain why: the SDK loads skills once per conversation, so a restart is needed to activate the new skill
• Link to the Skills overview page

4. Document MCP connection health on server cards

Type: Section addition to existing page
File: openhands/usage/settings/mcp-settings.mdx

Add a section (e.g., "## Connection Health Indicators") explaining:

• Installed MCP server cards now show persistent connection health status
• Cards cycle through: "checking" → green (healthy) / red "credentials" failure / red "connection" failure
• Failed cards display action buttons: "Retry", "Update credentials", and "View documentation"
• Secrets in error messages are automatically redacted (shown as **********)
• Fixing a server's configuration and saving immediately updates the card status without a page reload
• Servers without authentication show "Reachable — credentials not verified" when healthy

5. Document cloud-aware navigation changes

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

Add a section (e.g., "## Cloud Backend Navigation") explaining that when the active backend is OpenHands Cloud:

• Customize > Skills relabels to "Skills and Plugins" and opens {cloudHost}/settings/skills in a new tab
• The Plugins item is hidden (plugin management is handled by the Cloud UI)
• Customize > MCP Servers remains an in-app link on both local and Cloud backends
• Settings > Cloud is renamed to "All Cloud Settings"
• A new Settings > Integrations item appears, linking to {cloudHost}/settings/integrations/ in a new tab
• When the active backend is local, all navigation items behave as before

6. Document the update-availability card — Optional

Type: Section addition to existing page
File: openhands/usage/agent-canvas/setup.mdx (under "## Update") or openhands/usage/agent-canvas/customize-and-settings.mdx (under Settings)

Add a brief section explaining:

• The Settings page shows an update-availability card that checks the npm registry for newer versions
• Three states: "Up to date" (green badge), "Update available" (with the new version number), or a quiet inline message if the check fails
• Users can click "Check for updates" to bypass the 1-hour cache
• The card shows the update commands (npm update -g @openhands/agent-canvas or npx @openhands/agent-canvas@latest)
• Links to the GitHub Releases page for release notes

7. Document the title generation profile preference — Optional

Type: Section addition to existing page
File: openhands/usage/agent-canvas/llm-profiles.mdx or openhands/usage/agent-canvas/customize-and-settings.mdx

Add a short section (e.g., "### Title Generation Profile" under the LLM Profiles page or under the Application settings row in the Settings table) explaining:

• A "Conversation titles" section under Settings > Application lets users choose which LLM profile generates conversation titles
• The default is "Automatic", which resolves to the active local LLM profile
• Users can select a cheaper or faster profile for title generation to save costs
• The preference persists across sessions and updates automatically if the selected profile is renamed or deleted

---

Notes for the implementer

Key PRs to reference

• Desktop app: #1864, #1897, #1911, #1878
• Plugin contents modal: #1690
• Skill restart banner: #1830
• MCP connection health: #1833
• Cloud-aware nav: #1890
• Update card: #1898
• Title profile: #1910

Technical notes

• The desktop app bundles Node and uv inside the Electron app resources directory. No system-level Node or uv is required.
• The macOS app is ad-hoc signed (no Apple Developer certificate), so xattr -d com.apple.quarantine is required after download. The older xattr -cr flag does not work on macOS Sequoia.
• The update-availability card checks the npm registry (registry.npmjs.org) client-side; this is not an agent-server endpoint.
• Plugin contents (skills list, file tree) come from optional fields on the existing plugins API responses; the agent-server must be recent enough to surface them.
• MCP connection health uses the existing POST /api/mcp/test endpoint, but now the result is persisted on the card rather than shown only in a transient modal.
• The title-generation profile preference is stored client-side as part of application settings and passed to POST /api/conversations on conversation creation.

Style reminders

• Follow openhands/DOC_STYLE_GUIDE.md: Title Case for H1/H2, sentence case in sidebar navigation entries in docs.json, present tense, fenced code blocks for commands.
• Use absolute internal links (e.g., /openhands/usage/agent-canvas/setup).
• Run mint broken-links after editing to catch dead links.
• If adding a new page (unlikely for this release), add it to the docs.json Agent Canvas tab.