Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 adds 7 user-facing features — headlined by a native desktop app for macOS and Windows, an enriched plugin detail modal, and MCP server connection-health cards — plus 4 bug fixes that change observable UI behavior. The setup page (setup.mdx) needs a new Desktop tab, the plugins and settings pages need new sections, and the cloud-aware navigation changes should be reflected in the Customize & Settings page.

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

• Native desktop app (Electron) for macOS and Windows
  (#1864, #1878, #1911, #1897)

  Agent Canvas can now be installed and launched as a native desktop application via .dmg (macOS) or .exe installer (Windows). The app bundles the agent-server, automation service, and frontend into a single Electron shell. On launch, a loading screen with an expandable startup-log console shows backend service progress. On macOS, because the app is ad-hoc signed, downloaded DMGs are quarantine-flagged — the documented workaround uses sudo xattr -rd com.apple.quarantine (the older xattr -cr no longer works on Sequoia). An update-availability card (see below) lets users check for newer versions from Settings. Build workflows produce release assets automatically. The desktop app uses the same http://localhost:8000 default once running.

• Plugin detail modal now shows plugin contents
  (#1690)

  Clicking a plugin in Customize > Plugins opens a detail modal that now renders two additional sections: a "Skills in this plugin bundle" card list (icon, name, description for each bundled skill, including command-derived skills) and a "Files" section with an expandable directory tree and an inline, syntax-highlighted file viewer. File content is fetched lazily. Binary files and load errors show fallback messages. Re-clicking the selected file closes the viewer. These sections render nothing when the backend does not provide the path, skills, or files fields (backwards compatible with older agent-servers).

• One-click restart banner for chat-installed skills
  (#1830)

  When the agent installs a skill during a conversation (via fetch_skill.py), a banner now appears above the composer reading "[Skill name] was installed" with a "Start new conversation with this skill" button. Clicking it creates a new conversation in the same workspace with the newly installed skill loaded. The banner can be dismissed and reappears if another skill is installed in the same session.

• Actionable connection-health indicators on MCP server cards
  (#1833)

  Installed MCP server cards under Customize > MCP Servers now show live connection-health status. After a health probe, each card displays one of: green "Reachable" (with a note if credentials were not verified), red "credentials failure" (with the redacted error and buttons for Retry, Update credentials, and View documentation), or red "connection failure" (with a Retry button). Credential values embedded in URLs are redacted (**********) in error messages. Fixing a server's configuration in the editor and saving re-checks health 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 opens the Cloud settings skills page (https://app.all-hands.dev/settings/skills) in a new tab instead of the local in-app page; the Customize > Plugins item is hidden (plugins are Cloud-managed); the Settings sidebar renames the "Cloud" link to "All Cloud Settings"; and a new "Integrations" link appears linking to https://app.all-hands.dev/settings/integrations/. When the backend is local, everything renders as before.

• Update-availability card in Settings
  (#1898)

  A new card on the Settings page checks the npm registry for newer versions of @openhands/agent-canvas. It shows a green "Up to date" badge when current, an "Update available" badge with the new version number when outdated, or a quiet inline message when the registry is unreachable. The expanded card body shows both update commands (npm install -g @openhands/agent-canvas@latest and npx @openhands/agent-canvas@latest) and a link to the GitHub releases page. A "Check for updates" button bypasses the 1-hour cache.

• 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 select any configured profile — useful for choosing a cheaper or more reliable model than the agent's main LLM for title generation. The preference persists across sessions and stays consistent if the selected profile is renamed or deleted.

Bug Fixes

• Preserve secret values on edit (#1889) — Editing or renaming a secret on a local backend no longer silently drops its value. The old entry is properly deleted on rename.

• Keep LLM Profiles reachable while an ACP agent is active (#1915) — Previously, activating an ACP agent profile could make the LLM Profiles settings page unreachable, creating a UI dead-end during onboarding. This is now fixed.

• Cloud backend reconnect modal (#1807) — When locked to a Cloud backend and authentication expires, the recovery modal now shows a focused "Reconnect to Cloud" flow instead of generic backend-management controls.

• Fix paginated workspace folder listings (#1566) — Workspace folder selection now correctly loads all pages of results instead of showing only the first page.

Maintenance

• Bump software-agent-sdk to 1.37.0 and automation to 1.3.1 (#1906, #1934) — If any docs cite specific SDK or automation versions, update them.
• Bump @openhands/extensions to 0.11.0 (#1880).

---

Current doc coverage

Already covered (relevantly)

Page	Path	Relevance
Install	openhands/usage/agent-canvas/setup.mdx	Covers npm, Docker, npx, and from-source install methods. Has update and uninstall sections. No desktop/Electron tab.
Plugins	openhands/usage/agent-canvas/plugins.mdx	Covers browsing, installing, enabling plugins. Mentions "Inspect plugin details" in a bullet list but does not describe the detail modal contents (skills list, file browser).
Customize and Settings	openhands/usage/agent-canvas/customize-and-settings.mdx	Describes Customize (Skills, MCP Servers) and Settings areas. Does not mention cloud-aware nav behavior changes.
MCP Settings	openhands/usage/settings/mcp-settings.mdx	Documents MCP configuration options and transport protocols. No mention of connection-health indicators on server cards.
Application Settings	openhands/usage/settings/application-settings.mdx	Covers budget limits and Git author settings. No mention of conversation title profile preference.
First Time Setup	openhands/usage/agent-canvas/first-time-setup.mdx	Walks through the 4-step setup wizard.
Overview	openhands/usage/agent-canvas/overview.mdx	High-level intro. Does not mention the desktop app.

Still missing or thin

• Desktop app installation: No documentation exists for the Electron desktop app — no install/launch instructions, no macOS quarantine workaround, no Windows installer guidance.
• Plugin detail modal contents: The plugins page mentions "Inspect plugin details" but never describes what the detail modal shows. The new skills list and file browser sections are undocumented.
• Skill restart banner: No documentation describes the banner that appears when a skill is installed during a chat session, or the one-click "Start new conversation with this skill" flow.
• MCP server connection health: No documentation describes the health probe indicators, the credential/connection failure states, or the remediation actions (Retry, Update credentials, View documentation) on MCP server cards.
• Title generation profile preference: The application settings page does not mention the "Conversation titles" section or the ability to choose a different LLM profile for title generation.
• Update-availability card: No documentation describes the update card in Settings or the "Check for updates" button.
• Cloud-aware navigation behavior: The customize-and-settings page does not explain how the Customize and Settings sidebar items change when connected to a Cloud backend.

---

Proposed doc work

1. Add Desktop App tab to the Install page

File: openhands/usage/agent-canvas/setup.mdx
Type: New tab in existing page

Add a <Tab title="Desktop App"> alongside the existing npm / Docker / npx / From Source tabs in each relevant section:

• "Verify Prerequisites" section: Mention that no separate prerequisites are needed — the desktop app bundles everything.
• "Install And Run" section: Subsections for macOS (download .dmg from GitHub Releases, open and drag to Applications; document the quarantine workaround sudo xattr -rd com.apple.quarantine /Applications/Agent\ Canvas.app) and Windows (download .exe installer from GitHub Releases, run installer). Mention the loading screen with the expandable startup-log console.
• "Stop Agent Canvas" section: Quit the app (Cmd+Q on macOS, close window on Windows).
• "Update Agent Canvas" section: Reference the update-availability card in Settings (link to proposed section in work item 6), plus manual download from GitHub Releases.
• "Uninstall Agent Canvas" section: macOS (drag to Trash); Windows (Add/Remove Programs).
• "Choose An Install Method" table: Add a row for Desktop App — "You want a native app experience with bundled services" / "Runs directly on your machine like the npm method."

Also update the Overview page (openhands/usage/agent-canvas/overview.mdx) with a brief mention that Agent Canvas is available as a desktop app in addition to npm/Docker.

2. Document plugin detail modal contents

File: openhands/usage/agent-canvas/plugins.mdx
Type: Expand existing section

In the existing "Inspect plugin details" area, add a new subsection (e.g., "Plugin Detail Modal") describing:

• How to open the modal (click a plugin card in the Plugins page).
• "Skills in this plugin bundle" section: shows one card per bundled skill with icon, name, and description, including command-derived skills (e.g., city-weather:now).
• "Files" section: an expandable directory tree of the plugin's files. Clicking a file opens an inline, syntax-highlighted viewer. Re-clicking closes it. Binary files and load errors show fallback messages.
• Note that these sections only appear when the backend provides plugin content metadata (backwards compatible).

3. Document skill restart banner

File: openhands/usage/agent-canvas/customize-and-settings.mdx
Type: New subsection under Customize > Skills

Add a subsection (e.g., "Skills Installed During A Conversation") explaining:

• When the agent installs a skill during a chat session, a banner appears above the composer.
• The banner names the installed skill and shows a "Start new conversation with this skill" button.
• Clicking the button creates a new conversation in the same workspace with the skill loaded.
• The banner can be dismissed and reappears if another skill is installed in the session.

4. Document MCP server connection-health indicators

File: openhands/usage/settings/mcp-settings.mdx
Type: New section

Add a section (e.g., "Connection Health") after the existing configuration section, describing:

• Each installed MCP server card shows a health status after the probe runs.
• Possible states: green "Reachable" (with a note when credentials are not verified), red "credentials failure" (shows redacted error message, with Retry, Update credentials, and View documentation buttons), red "connection failure" (with Retry button).
• Credential values in URLs are redacted to ********** in error messages.
• Fixing a server via the editor and saving re-checks health automatically (no page reload needed).
• Consider cross-linking from openhands/usage/agent-canvas/customize-and-settings.mdx.

5. Add title generation profile preference to Application Settings

File: openhands/usage/settings/application-settings.mdx
Type: New section in existing page

Add a section (e.g., "Conversation Title Profile") describing:

• Location: Settings > Application > Conversation titles.
• The dropdown lets you choose which LLM profile generates automatic conversation titles.
• Default is "Automatic", which uses the active local profile.
• Use case: pick a cheaper or more reliable model for title generation when your agent's main LLM is expensive or occasionally unavailable.
• The preference persists across sessions. If the selected profile is renamed or deleted, the setting adjusts automatically.

6. Document the update-availability card (Optional)

File: openhands/usage/agent-canvas/setup.mdx (under "Update Agent Canvas") or openhands/usage/settings/application-settings.mdx
Type: New subsection in existing page

Add a brief subsection describing:

• A card on the Settings page checks the npm registry for newer versions.
• States: green "Up to date", "Update available" (shows the new version), or quiet "Couldn't check for updates" when offline.
• The card body shows both update commands and links to the GitHub releases page.
• "Check for updates" button bypasses the 1-hour cache.
• This is most useful for desktop app and global npm users; npx users always get the latest.

7. Update Customize & Settings for cloud-aware navigation (Optional)

File: openhands/usage/agent-canvas/customize-and-settings.mdx
Type: Update existing sections

Add a note or callout explaining how the sidebar changes when the active backend is a Cloud backend:

• Customize > Skills relabels to "Skills and Plugins" and opens the Cloud settings page in a new tab.
• Customize > Plugins is hidden.
• Settings > Cloud renames to "All Cloud Settings".
• A new "Integrations" link appears in Settings, opening the Cloud integrations page.
• When connected to a local backend, all items render as normal in-app links.

---

Notes for the implementer

Key PRs to reference

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

Technical notes

• The desktop app is an Electron wrapper; it spawns the same agent-server, automation, and static-server processes that the npm/npx CLI starts. The user experience once running is identical to the browser workflow — the Electron shell simply hosts the http://localhost:8000 UI.
• MCP health checks are client-side probes that run when the MCP Servers page loads. The results are not persisted server-side.
• The plugin detail modal's "Files" and "Skills" sections depend on path, skills, and files fields from the plugins API — which are available in agent-server 1.37.0+. Older agent-servers will show the modal without these sections.
• The title generation preference is stored alongside other app-level settings and sent as part of the conversation creation payload for local backends.

Style reminders

• Follow openhands/DOC_STYLE_GUIDE.md: Title Case for H1/H2, present tense, use backticks for UI element names, fenced code blocks for commands, <Note> and <Warning> components, <Tabs> for multiple approaches.
• Use absolute internal links (e.g., /openhands/usage/agent-canvas/setup).
• If adding new pages, add them to the navigation in docs.json.
• Run mint broken-links after edits to verify all links.