Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 introduces 7 user-facing features — headlined by a native Electron desktop app (macOS and Windows), an enhanced plugin detail modal with file browsing, and MCP server connection health indicators — along with several UX improvements to Cloud-aware navigation, settings, and skill activation. There are no breaking changes, but multiple existing doc pages need updates and the desktop app install path needs new documentation from scratch.

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 app. On macOS, users download a .dmg (Apple Silicon; Intel is build-from-source only). On Windows, users download an NSIS .exe installer. The app bundles its own Node.js and uv runtimes, so no prerequisites are needed beyond the OS. On macOS, the .dmg is ad-hoc signed and triggers Gatekeeper quarantine — users must run sudo xattr -rd com.apple.quarantine /Applications/Agent\ Canvas.app (or the Sequoia-compatible equivalent) before launching. The desktop app starts an agent server automatically and shows a loading splash screen while services initialize.

• Expandable startup-log console on desktop loading screen (#1878)
  The desktop app's loading splash includes a "Show details" toggle that expands to reveal a live log console streaming agent-server and automation-service startup output. If startup fails, a failure state appears with a "Copy" button (copies all log lines) and a "Quit" button. Error-level lines are highlighted in red.

• Plugin detail modal now shows plugin contents (#1690)
  Clicking a plugin in Customize > Plugins now opens a detail modal that shows two new sections: "Skills in this plugin bundle" (cards for each bundled skill showing icon, name, and description, including command-derived skills) and "Files" (an expandable directory tree of the plugin's files with an inline, syntax-highlighted viewer for the selected file). These sections render only when the backend provides the data, so older backends keep working.

• MCP server connection health indicators on installed server cards (#1833)
  Installed MCP server cards in the MCP Servers settings page now display live connection health status. Each card transitions from "checking" to either a green healthy state or a red failure state with a specific error message. Failed cards show actionable buttons: "Retry" (re-tests the connection), "Update credentials" (opens the server editor), and "View documentation" (links to the server's docs). Secrets embedded in error messages are automatically redacted (replaced with **********). Fixing a misconfigured server via the card's editor refreshes the health status without a page reload.

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

• Update-availability card in Settings (desktop only) (#1898)
  The Settings page shows a new card that checks the npm registry for newer Agent Canvas versions. It displays the running version and either an "Up to date" green badge or an "Update available" badge with the new version number. The expanded card body shows the two update commands (npm update -g @openhands/agent-canvas and npx @openhands/agent-canvas@latest) and links to the GitHub releases page. A "Check for updates" button triggers a manual re-check (bypasses the 1-hour cache). If the registry is unreachable, a quiet inline message appears with no error toast.

• Title generation profile preference (#1910)
  Settings > Application now includes a "Conversation titles" section with a profile selector dropdown. Users can choose a specific LLM profile for generating conversation titles (useful for selecting a cheaper or more reliable model), or leave it on "Automatic" (resolves to the active local profile). The preference persists across sessions and adjusts automatically on profile rename or delete.

• One-click restart to activate chat-installed skills (#1830)
  When a skill is installed during a conversation via the /add-skill command, a banner now appears above the message composer. The banner names the newly installed skill and offers a "Start new conversation with this skill" button. Clicking the button creates a new conversation (preserving the workspace) and navigates to it, so the skill is loaded from the start. Dismissing the banner hides it until another skill is installed. This addresses the limitation that the SDK loads skills once per conversation at startup.

Bug Fixes

• Preserve secret values on edit (#1889)
  Previously, editing a local secret's name would lose the stored value. The secret value is now correctly preserved during edits, and renaming a secret deletes the old entry. This fix is relevant because it changes the behavior described in secrets documentation — editing secrets now works as users would expect.

• Cloud backend reconnect modal (#1807)
  When the Cloud backend connection drops (e.g., auth token expires) on a locked-to-Cloud deployment, the recovery modal now shows "Reconnect to Cloud" with a dedicated Cloud reconnect button that launches the device-flow authentication path, instead of showing generic backend management controls.

• LLM Profiles reachable while an ACP agent is active (#1915)
  Previously, when an ACP agent profile (e.g., Claude Code) was active, the Settings > LLM sidebar item was disabled and navigating directly to /settings/llm redirected to /settings/agents. This deadlocked onboarding for ACP users who needed to configure an LLM profile. The LLM Profiles page is now always reachable regardless of the active agent type.

• Paginated workspace folder listings (#1566)
  The Add Workspace folder browser now loads all subdirectory pages from the API instead of only the first page, so users with many subfolders can now see and select all directories.

Maintenance

• Bump software-agent-sdk to 1.37.0 (#1906) and automation to 1.3.1 (#1934) — relevant only if docs cite specific bundled SDK/automation versions.

Current Doc Coverage

Already covered (relevantly)

Page	File path	Relation to v1.6.0
Install	openhands/usage/agent-canvas/setup.mdx	Covers npm, npx, Docker, from-source install methods. Does not mention the desktop app. Will need a new install method section.
Plugins in Agent Canvas	openhands/usage/agent-canvas/plugins.mdx	Mentions "Inspect plugin details" as a bullet point. Has no section describing the detail modal contents.
Customize and Settings	openhands/usage/agent-canvas/customize-and-settings.mdx	Describes Customize and Settings high-level. Does not mention Cloud-aware nav behavior or the Integrations link.
Application Settings	openhands/usage/settings/application-settings.mdx	Covers budget and Git author settings. No mention of conversation title generation profile.
MCP Settings	openhands/usage/settings/mcp-settings.mdx	Covers MCP configuration and transport protocols. No mention of connection health indicators on server cards.
Secrets Settings	openhands/usage/settings/secrets-settings.mdx	Covers secrets. The edit-preservation fix (#1889) aligns with existing doc intent — no doc change needed unless the page previously described the broken behavior.
Troubleshooting	openhands/usage/agent-canvas/troubleshooting.mdx	Covers npm and Docker troubleshooting. No desktop-specific troubleshooting.
First-time Setup	openhands/usage/agent-canvas/first-time-setup.mdx	Covers onboarding. May need a note about the ACP + LLM Profiles fix (#1915) if it describes that flow.

Still missing or thin

• Desktop app install path: No documentation exists for installing, launching, updating, or uninstalling the Electron desktop app on macOS or Windows. This is the biggest gap — it's an entirely new install method.
• Plugin detail modal contents: The plugins page mentions inspecting details but does not describe the new skills list and file browser sections that appear in the detail modal.
• MCP server connection health: No documentation describes the health indicators, failure states, or actionable buttons on installed MCP server cards.
• Cloud-aware navigation behavior: The Customize and Settings page does not explain how the sidebar changes when a Cloud backend is active.
• Conversation title profile preference: The Application Settings page does not mention the title generation profile selector.
• Update-availability card: No documentation describes the update-availability card in Settings (desktop-specific feature).
• Skill installation banner: No documentation describes the banner that appears after installing a skill via /add-skill during a conversation.

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 "Desktop App" tab alongside the existing "npm" and "Docker" tabs:

• Choose An Install Method table — Add a row: "Desktop app" / "You want a native window with zero prerequisites." / "Runs directly on your machine with a bundled agent server."
• Verify Prerequisites section — Add a "Desktop App" tab stating no prerequisites needed (runtimes are bundled).
• Install And Run section — Add a "Desktop App" tab with:
  • macOS: Download Agent-Canvas-<version>-arm64.dmg from the GitHub Releases page, open the DMG, drag to Applications. Mention the quarantine workaround: sudo xattr -rd com.apple.quarantine /Applications/Agent\ Canvas.app. Note: Intel Macs must build from source.
  • Windows: Download Agent-Canvas-Setup-<version>.exe from GitHub Releases, run the installer, launch from Start Menu.
  • Describe the loading screen and what it shows during startup.
• Update section — Add desktop-specific update instructions (re-download latest DMG/exe from Releases).
• Uninstall section — Add desktop-specific uninstall (macOS: drag to Trash; Windows: Add/Remove Programs or uninstaller).

2. Add desktop troubleshooting to troubleshooting.mdx

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

Add a "Desktop App" section or tab with:

• macOS "damaged" or "unidentified developer" error — Explain the ad-hoc signing limitation and the xattr workaround. Note that the classic xattr -cr may not work on macOS Sequoia; provide the Sequoia-compatible command.
• Startup log console — Mention the "Show details" toggle on the loading screen to diagnose startup failures. Explain the Copy button for sharing logs.
• Windows process lock on uninstall/update — If uv.exe or another file is in use, close terminals running Agent Canvas and stop related processes before retrying.

3. Add plugin detail modal section to plugins.mdx

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

Add a section titled "Inspect Plugin Details" (or expand the existing bullet into a full section):

• Explain that clicking a plugin card opens a detail modal.
• Describe the "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).
• Describe the "Files" section: shows an expandable directory tree of the plugin's files. Clicking a file opens an inline, syntax-highlighted viewer. Clicking the selected file again closes the viewer. Binary files and load errors show fallback messages.
• Note that these sections appear only when the backend provides the data (older backends show metadata only).

4. Document MCP server connection health in mcp-settings.mdx

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

Add a section titled "Connection Health" or "Server Health Status":

• Explain that installed MCP server cards show live connection health after configuration.
• Describe the states: "checking" (spinner), healthy (green), failed (red with error message).
• Describe the actionable buttons on failed cards: "Retry", "Update credentials" (opens server editor), "View documentation".
• Note that secrets in error messages are automatically redacted.
• Mention that fixing a configuration via the card's editor refreshes the health status inline without a page reload.

5. Document Cloud-aware navigation in customize-and-settings.mdx

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

Add a section titled "Cloud Backend Behavior" (or similar) under the existing structure:

• Explain that when a Cloud backend is active, the Customize and Settings sidebars adapt:
  • "Skills" relabels to "Skills and Plugins" and opens the Cloud settings page in a new tab.
  • "Plugins" item is hidden (Cloud manages plugins differently).
  • "MCP Servers" remains an in-app link.
  • "Cloud" in Settings is renamed to "All Cloud Settings".
  • A new "Integrations" link appears in Settings, linking to the Cloud integrations page.
• Note that on local backends, everything renders as before.

6. Add conversation title profile preference to application-settings.mdx

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

Add a section titled "Conversation Title Generation":

• Explain the "Conversation titles" dropdown in Settings > Application.
• Describe the "Automatic" default (uses the active local LLM profile).
• Explain why a user might choose a different profile (e.g., cheaper model, more reliable provider).
• Note that the preference persists and auto-adjusts when profiles are renamed or deleted.

7. Document skill installation banner (Optional)

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

Add a brief note under Skills documentation:

• Explain that after installing a skill with /add-skill in a conversation, a banner appears above the composer.
• The banner offers "Start new conversation with this skill" to activate the skill immediately.
• Dismissing the banner hides it until the next skill install.
• Context: the SDK loads skills once at conversation start, so the new conversation is needed to load the newly installed skill.

8. Document the update-availability card (Optional)

Type: Section addition to existing page
File: openhands/usage/agent-canvas/setup.mdx (under "Update Agent Canvas") or a new brief section

Add under the existing "Update Agent Canvas" heading:

• Explain that the desktop app (and npm installations) display an update-availability card in Settings.
• Describe what the card shows: running version, "Up to date" or "Update available" badge, update commands, link to GitHub releases.
• Mention the "Check for updates" manual re-check button.
• Note that if the npm registry is unreachable, a quiet message appears.

Notes for the Implementer

PRs worth referencing

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

Technical notes

• The desktop app is an Electron wrapper around the same web UI — the loading screen is electron/loading.html in the agent-canvas repo. The app spawns the agent-server and automation service as child processes.
• The MCP connection health check uses the existing POST /api/mcp/test backend endpoint. The health display is purely client-side UI on top of that API.
• The plugin detail modal fetches file content lazily via GET /api/file/download. The skills/files data comes as new optional fields on the plugins API response.
• The Cloud-aware nav changes are entirely client-side — they detect the backend kind and swap links.
• The update-availability card queries the npm registry directly from the browser (https://registry.npmjs.org/@openhands/agent-canvas/latest).
• The title generation profile preference is stored client-side and passed as title_llm_profile in POST /api/conversations.

Style guide reminders

• Follow openhands/DOC_STYLE_GUIDE.md: Title Case for H1/H2 headings, numbered steps for procedures, fenced code blocks, <Note> and <Warning> components where appropriate.
• Use absolute internal links (e.g., /openhands/usage/agent-canvas/setup).
• After edits, run mint broken-links or equivalent link checking.
• New pages require a corresponding entry in docs.json under the Agent Canvas tab.