Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 introduces 5 material user-facing features — most notably a native desktop app for macOS and Windows, richer plugin inspection, and new settings controls — plus several bug fixes that affect documented workflows. None of the new features have existing documentation coverage, so this release requires both new pages and updates to existing ones.

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 for macOS and Windows (#1864, #1911, #1897)
  Agent Canvas is now available as a standalone Electron desktop application. On macOS, users download a .dmg file (Agent-Canvas-<version>-arm64.dmg) from the GitHub Releases page; Intel Macs are documented as build-from-source only. On Windows, an NSIS installer (Agent-Canvas-Setup-<version>.exe) is provided. The desktop app bundles its own Node.js and uv runtimes, so users do not need to install prerequisites separately. On macOS, because the app is ad-hoc signed, downloaded DMGs are quarantined by Gatekeeper — the documented workaround uses xattr -d com.apple.quarantine (the older xattr -cr no longer works on macOS Sequoia). The app starts with a loading splash screen that streams backend startup logs.

• Expandable startup-log console on the desktop loading screen (#1878)
  The desktop app's loading splash includes a "Show details" toggle that expands the window to reveal a live log console showing agent-server and automation service startup output. The console auto-scrolls, color-codes error-level lines in red, and provides a "Copy" button to copy all buffered log lines to the clipboard. If startup fails, the console shows a failure state with a "Quit" button. This is useful for troubleshooting startup issues.

• 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 metadata. The modal displays two new sections: "Skills in this plugin bundle" (one card per bundled skill with icon, name, and description, including command-derived skills) and "Files" (an expandable directory tree with an inline syntax-highlighted file viewer). File content is fetched lazily; re-clicking the selected file closes the viewer. Both sections gracefully render nothing when the backend does not provide the data.

• One-click restart to activate chat-installed skills (#1830)
  When a user installs a skill via the /add-skill chat command, a banner now appears above the chat composer naming the installed skill and offering a "Start new conversation with this skill" button. Clicking this button creates a new conversation with the workspace set to the skill's install root. The banner can be dismissed, and it reappears if another skill is installed in the same session. This addresses the limitation that skills are loaded once per conversation and cannot be hot-reloaded.

• Actionable connection health on installed MCP server cards (#1833)
  Installed MCP server cards in the Customize > MCP Servers page now persistently display connection health status. Each card goes through a "checking" state and then settles on one of: green "Reachable" (with a note "credentials not verified" for public/no-auth servers), red "Credential check failed" (with the error message, e.g., "401 Unauthorized"), or red connection failure. Cards display actionable buttons: "Retry" to recheck, "Update credentials" to open the server editor, and "View documentation" linking to the server's docs. Secrets in server URLs are redacted (displayed as **********). Fixing a server's configuration through the card's editor refreshes its health status in-place without a page reload.

• Cloud-aware Skills/Plugins nav and new Integrations link (#1890)
  When the active backend is an OpenHands Cloud backend: the Customize > "Skills" nav item 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 (plugins are managed Cloud-side); "MCP Servers" remains an in-app link. In the Settings sidebar: the "Cloud" link is renamed to "All Cloud Settings", and a new "Integrations" item is added above it, linking to {cloudHost}/settings/integrations/ in a new tab. Switching back to a local backend restores the original nav (Skills, MCP Servers, Plugins all in-app; Integrations link hidden).

• Update-availability card in Settings (#1898)
  A new card appears on the Settings page showing the current Agent Canvas version and whether an update is available. The card checks the npm registry for the latest published version. States: green "Up to date" badge when current, "Update available" badge with the new version number when outdated, and a quiet inline message when the registry is unreachable. A "Check for updates" button bypasses the 1-hour cache and triggers a fresh check. The card also displays the update commands (npm install -g @openhands/agent-canvas@latest) and links to the GitHub releases page.

• Title generation profile preference (#1910)
  A new "Conversation titles" section appears under Settings > Application. Users can select which LLM profile to use for generating conversation titles, independent of the agent's model. The default is "Automatic", which resolves to the active local LLM profile. The preference is persisted with other application settings and stays consistent across profile rename/delete. On local conversation starts, the resolved title_llm_profile is sent to the backend.

Bug fixes

• Preserve secret values on edit (#1889) — Previously, editing a secret in Settings > Secrets could clear the stored value. Secret values are now preserved correctly during edits. Relevant to any docs describing the Secrets settings workflow.

• Keep LLM Profiles reachable while an ACP agent is active (#1915) — When using an ACP agent profile, the LLM Profiles settings page was unreachable. Users can now access LLM settings regardless of the active agent type. Relevant to llm-profiles.mdx and acp-agents.mdx.

• Deduplicate streamed reasoning and final events (#1865, #1896) — Fixes duplicate rendering of reasoning content and reconnect side-effects in the chat stream. Not a docs change, but worth knowing if any troubleshooting guidance mentioned duplicate messages.

• Fix paginated workspace folder listings (#1566) — Large workspace directories now paginate correctly in the file tree. Not a docs change unless file browsing is documented.

Maintenance

• SDK bumped to 1.37.0 and automation service to 1.2.0 / 1.3.1 (#1906, #1934) — Only relevant if docs cite specific SDK or automation versions.
• @openhands/extensions bumped to 0.11.0 (#1880) — No doc impact unless extension versions are referenced.

---

Current doc coverage

Already covered (relevantly)

• openhands/usage/agent-canvas/setup.mdx — Documents npm, Docker, npx, VM/self-hosted, and from-source install methods. The new desktop app is not listed here yet, but this is the right page to add it.
• openhands/usage/agent-canvas/overview.mdx — Has a "When to use" table and a "Choose an install method" table. Neither mentions the desktop app.
• openhands/usage/agent-canvas/plugins.mdx — Documents the Plugins page: browsing, installing, enabling/disabling, attaching to conversations. Mentions "Inspect plugin details" briefly but does not describe what the detail modal shows.
• openhands/usage/agent-canvas/customize-and-settings.mdx — Lists settings sections in a table (Agent, LLM, Condenser, Verification, Application, Secrets). The Application row says "UI-level preferences and app behavior" but does not detail title generation profile or update card. Does not mention cloud-specific nav behavior.
• openhands/usage/agent-canvas/backend-setup/cloud.mdx — Describes how to add a Cloud backend. Does not mention the renamed "All Cloud Settings" link or the new "Integrations" link.
• openhands/usage/agent-canvas/llm-profiles.mdx — Covers LLM profile configuration. Does not mention title generation profile as a use case.
• openhands/usage/agent-canvas/troubleshooting.mdx — Existing troubleshooting page. Does not cover desktop app startup issues.

Still missing or thin

• Desktop app installation: No page or section covers downloading, installing, or running the desktop app on macOS or Windows. No mention of the macOS quarantine workaround or the startup log console. The setup page's "Choose an install method" table and the overview's "When to use" table both lack a desktop entry.
• Plugin detail modal contents: The plugins page says you can inspect plugin details but does not describe the skill cards or file viewer sections in the modal.
• Chat-installed skill restart banner: No documentation covers the /add-skill chat workflow's new restart banner or the "Start new conversation with this skill" button.
• MCP connection health on server cards: No documentation covers the persistent health indicators, the checking/healthy/failed states, or the actionable buttons (Retry, Update credentials) on installed server cards.
• Cloud-specific nav changes: No documentation describes how the Customize and Settings nav items change when a Cloud backend is active (Skills → Skills and Plugins external link, Plugins hidden, Cloud → All Cloud Settings, new Integrations link).
• Update-availability card: No mention of the update card in Settings, its states, or the manual check button.
• Title generation profile: The Application settings row in customize-and-settings.mdx does not mention this new preference.

---

Proposed doc work

1. Add desktop app install method to setup.mdx and overview.mdx

Type: Section addition to existing pages
Files: openhands/usage/agent-canvas/setup.mdx, openhands/usage/agent-canvas/overview.mdx

Suggested content for setup.mdx:

• Add a Desktop app (macOS / Windows) row to the "Choose an install method" table with a description like: "You want a native app with bundled runtimes and no CLI setup."
• Add a new <Tab title="Desktop app"> inside the "Verify prerequisites" section noting that no prerequisites are needed (runtimes are bundled).
• Add a new <Tab title="Desktop app"> inside the "Install and run" section covering:
  • macOS: Download the .dmg from the GitHub Releases page. Open the DMG, drag Agent Canvas to Applications. On first launch, macOS may report the app as damaged because it is ad-hoc signed — run xattr -d com.apple.quarantine /Applications/Agent\ Canvas.app in Terminal to clear the quarantine flag. Intel Macs are not supported via the pre-built DMG; use the npm or from-source method instead.
  • Windows: Download the .exe installer from GitHub Releases. Run the installer (Windows SmartScreen may prompt for confirmation). Launch Agent Canvas from the Start menu.
  • Note: The desktop app bundles its own Node.js and uv, so users do not need to install them separately.
• Add corresponding "Stop", "Update", and "Uninstall" tabs for the desktop app.

Suggested content for overview.mdx:

• Add a row to the "When to use" table: "Run OpenHands as a native desktop app" → link to the desktop tab in setup.

2. Update plugins.mdx with plugin detail modal contents

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

Suggested content:

• Add a section "Inspect plugin contents" (or expand the existing brief mention) after the "Enable or disable installed plugins" section.
• Describe what the detail modal shows when you click a plugin:
  • Skills in this plugin bundle: Cards for each bundled skill showing name, icon, and description. Includes command-derived skills.
  • Files: An expandable directory tree of the plugin's files. Click a file to view its content inline with syntax highlighting. Click again to close the viewer.
• Note that these sections appear only when the backend provides plugin content data (older backends may show metadata only).

3. Document the chat-installed skill restart banner

Type: Section addition to existing page
File: openhands/usage/agent-canvas/customize-and-settings.mdx (or a dedicated skills page if one exists)

Suggested content:

• Add a section "Install skills from chat" explaining the /add-skill <github-url> workflow briefly and the new restart banner:
  • After a skill is installed via chat, a banner appears above the composer with the skill name and a "Start new conversation with this skill" button.
  • Clicking the button creates a new conversation with the workspace set to the install location.
  • The banner can be dismissed and reappears if another skill install occurs in the same session.
  • Explain why a new conversation is needed (skills load once per conversation).

4. Document MCP connection health on server cards

Type: Section addition to existing page
File: openhands/usage/settings/mcp-settings.mdx (or wherever MCP server management is documented)

Suggested content:

• Add a section "Connection health" explaining the persistent health indicators on installed server cards:
  • States: "Checking…" → green "Reachable" / red "Credential check failed" / red "Connection failure"
  • Public/no-auth servers show "Reachable — credentials not verified"
  • Actionable buttons: "Retry" rechecks immediately, "Update credentials" opens the server editor, "View documentation" links externally
  • Secrets in server URLs are redacted in error messages
  • Fixing configuration through the card's editor refreshes health in-place (no page reload needed)

5. Update customize-and-settings.mdx with cloud nav behavior, update card, and title generation

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

Suggested content:

• Cloud-specific nav behavior: Add a subsection under "Customize" or a new section "Cloud backend differences" explaining:
  • Skills → "Skills and Plugins" (external link to Cloud settings, opens in new tab)
  • Plugins item hidden on Cloud backends
  • MCP Servers unchanged
  • Settings → "Cloud" renamed to "All Cloud Settings"
  • New "Integrations" link (Cloud-only, external link)
  • Switching to a local backend restores the original nav
• Application settings details: Expand the Application row in the Settings table or add a subsection covering:
  • Conversation titles: Users can choose an LLM profile for title generation (default: "Automatic", which uses the active profile). Useful when the agent's model is expensive or unavailable.
  • Update availability: A card showing the current version and whether an update is available. "Check for updates" triggers a fresh check. Shows update commands and a link to GitHub releases.

6. Update backend-setup/cloud.mdx with renamed links — Optional

Type: Minor update to existing page
File: openhands/usage/agent-canvas/backend-setup/cloud.mdx

Suggested content:

• In the "What's different with a Cloud backend" section, add a bullet about the nav differences: Skills/Plugins redirect to Cloud settings, "Cloud" link renamed to "All Cloud Settings", and a new "Integrations" link appears.
• This is a brief mention that cross-references the fuller explanation in customize-and-settings.mdx.

7. Add desktop troubleshooting to troubleshooting.mdx — Optional

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

Suggested content:

• Add a section "Desktop app" covering:
  • macOS quarantine / "damaged" error: xattr -d com.apple.quarantine /Applications/Agent\ Canvas.app
  • Startup log console: Click "Show details" on the loading screen to see backend logs; use "Copy" to capture logs for bug reports
  • macOS Sequoia note: xattr -cr no longer works; use the -d com.apple.quarantine form instead

---

Notes for the implementer

• Key PRs to reference: #1864, #1878, #1911, #1897 (desktop app), #1690 (plugin detail modal), #1830 (skill restart banner), #1833 (MCP health), #1890 (cloud nav), #1898 (update card), #1910 (title generation profile)
• The desktop app is an Electron wrapper around the same web UI — it starts a local agent server and an ingress proxy internally. The bundled runtimes (uv, node) are architecture-specific. The macOS DMG is Apple Silicon only; Intel is build-from-source.
• The plugin detail modal relies on new optional fields from the agent server API (path, skills, files on the plugin response). Older agent-server versions will not surface these fields, and the modal sections gracefully render nothing.
• The MCP connection health check uses the existing POST /api/mcp/test endpoint server-side; the client-side change is persistent display on cards rather than transient modal-only results.
• The title generation profile is persisted client-side as part of application settings and sent as title_llm_profile on POST /api/conversations for local backends only. Cloud backends resolve title generation server-side.
• Follow the style guide in openhands/DOC_STYLE_GUIDE.md: sentence-case headings in nav, present tense, fenced code blocks for commands, absolute internal links (e.g., /openhands/usage/agent-canvas/setup).
• If a new page is added (e.g., for the desktop app), update the docs.json navigation under the Agent Canvas group.
• Run mint broken-links after edits to catch any dead internal links.