docs: add Onboarding Agent Canvas section

docs.json

@@ -20,7 +20,7 @@
   "navigation": {
     "tabs": [
       {
-        "tab": "Documentation",
+        "tab": "Home",
         "pages": [
           {
             "group": "Get Started",
@@ -40,16 +40,23 @@
             ]
           },
           {
-            "group": "Onboarding OpenHands",
+            "group": "Use Cases",
             "pages": [
-              "openhands/usage/customization/repository",
-              "openhands/usage/customization/hooks"
+              "openhands/usage/use-cases/overview",
+              "openhands/usage/use-cases/vulnerability-remediation",
+              "openhands/usage/use-cases/code-review",
+              "openhands/usage/use-cases/qa-changes",
+              "openhands/usage/use-cases/incident-triage",
+              "openhands/usage/use-cases/cobol-modernization",
+              "openhands/usage/use-cases/dependency-upgrades",
+              "openhands/usage/use-cases/spark-migrations"
             ]
           },
           {
             "group": "Product Guides",
             "pages": [
               "openhands/usage/key-features",
+              "openhands/usage/customization/hooks",
               "overview/model-context-protocol",
               {
                 "group": "Skills",
@@ -74,6 +81,7 @@
                   "openhands/usage/automations/managing-automations"
                 ]
               },
+              "openhands/usage/customization/repository",
               {
                 "group": "Settings",
                 "pages": [
@@ -190,21 +198,34 @@
         ]
       },
       {
-        "tab": "Use Cases",
+        "tab": "Agent Canvas",
         "pages": [
-          "openhands/usage/use-cases/overview",
+          "openhands/usage/agent-canvas/overview",
+          "openhands/usage/agent-canvas/setup",
+          "openhands/usage/agent-canvas/first-time-setup",
           {
-            "group": "Use Cases",
+            "group": "Pre-built Automations",
             "pages": [
-              "openhands/usage/use-cases/vulnerability-remediation",
-              "openhands/usage/use-cases/code-review",
-              "openhands/usage/use-cases/qa-changes",
-              "openhands/usage/use-cases/incident-triage",
-              "openhands/usage/use-cases/cobol-modernization",
-              "openhands/usage/use-cases/dependency-upgrades",
-              "openhands/usage/use-cases/spark-migrations"
+              "openhands/usage/agent-canvas/prebuilt-automations",
+              "openhands/usage/agent-canvas/prebuilt/github-pr-review",
+              "openhands/usage/agent-canvas/prebuilt/github-repo-monitor",
+              "openhands/usage/agent-canvas/prebuilt/slack-channel-monitor"
             ]
-          }
+          },
+          {
+            "group": "Backends",
+            "pages": [
+              "openhands/usage/agent-canvas/backends",
+              "openhands/usage/agent-canvas/backend-setup/local",
+              "openhands/usage/agent-canvas/backend-setup/vm",
+              "openhands/usage/agent-canvas/backend-setup/docker",
+              "openhands/usage/agent-canvas/backend-setup/cloud"
+            ]
+          },
+          "openhands/usage/agent-canvas/customize-and-settings",
+          "openhands/usage/agent-canvas/acp-agents",
+          "openhands/usage/agent-canvas/development",
+          "openhands/usage/agent-canvas/troubleshooting"
         ]
       },
       {
@@ -524,6 +545,10 @@
     ]
   },
   "redirects": [
+    {
+      "source": "/openhands/usage/agent-canvas/self-hosting",
+      "destination": "/openhands/usage/agent-canvas/backend-setup/vm"
+    },
     {
       "source": "/modules/:slug*",
       "destination": "/:slug*"

openhands/usage/agent-canvas/acp-agents.mdx

@@ -0,0 +1,94 @@
+---
+title: ACP Agents
+description: Drive Agent Canvas conversations with an external coding agent — Claude Code, Codex, or Gemini CLI — over the Agent Client Protocol.
+---
+
+Agent Canvas can drive your conversations with the built-in **OpenHands** agent or with an external **ACP agent** — Claude Code, Codex, or Gemini CLI. This guide explains what ACP agents are, how to onboard one, and how to switch agents or models later.
+
+## What is an ACP agent?
+
+The [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/overview) is a standard for talking to coding agents over JSON-RPC on stdio. Instead of Agent Canvas calling an LLM directly, the Agent Server spawns the agent's own CLI as a subprocess and relays each turn to it. The external agent manages its own LLM, tools, and execution; Agent Canvas sends messages and renders what comes back.
+
+```mermaid
+flowchart LR
+    canvas["Agent Canvas<br/>(this UI)"]
+    server["Agent Server"]
+    acp["ACP subprocess<br/>(e.g. claude-agent-acp)"]
+    llm["LLM provider<br/>(Anthropic / OpenAI / Google)"]
+    canvas -- "PATCH /api/settings<br/>(agent_kind, acp_*)" --> server
+    canvas -- "conversation turns" --> server
+    server -- "spawn + JSON-RPC over stdio" --> acp
+    acp -- "API calls" --> llm
+```
+
+The Agent Server owns the subprocess and the credentials; Agent Canvas only records *which* agent to run and surfaces a form for the secrets it needs. The agent choice is stored per backend, so switching backends can switch agents.
+
+## Supported providers
+
+| Provider | Default command |
+|---|---|
+| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` |
+| **Codex** | `npx -y @zed-industries/codex-acp` |
+| **Gemini CLI** | `npx -y @google/gemini-cli --acp` |
+
+The provider list is sourced from the OpenHands SDK registry (`openhands.sdk.settings.acp_providers`, mirrored into `@openhands/typescript-client`) and enriched with Canvas UI metadata. Adding or changing a provider happens upstream in the SDK.
+
+## Authentication
+
+<Info>
+  ACP agents authenticate **two ways: a subscription login, or an API key** — and the onboarding fields are optional. If you're already signed in to the provider's CLI on the machine the agent runs on, it reuses that login automatically, so locally you often don't need a key at all. **The login takes priority over an API key:** while you're signed in, a key set in the environment isn't used — so the onboarding key fields do nothing and can be left blank.
+</Info>
+
+A "subscription login" is the credential the provider's own CLI stores when you sign in once — a file in your home directory, or, for Claude Code on macOS, the system **Keychain**. When the Agent Server runs **on that same machine** (a local or self-hosted backend), the provider CLI finds that login automatically — no API key required. On a clean cloud sandbox there's no stored login, so an API key is needed instead.
+
+| Provider | Subscription login (auto-detected) | API key |
+|---|---|---|
+| **Claude Code** | A Claude Code login (Pro/Max), from Claude Code's own credential store: the **macOS Keychain**, or `~/.claude/.credentials.json` on Linux | `ANTHROPIC_API_KEY` |
+| **Codex** | A ChatGPT login (`codex login`) cached at `~/.codex/auth.json` | `OPENAI_API_KEY` |
+| **Gemini CLI** | Your Google login (`gemini`/`gemini --acp`) cached at `~/.gemini/oauth_creds.json` | `GEMINI_API_KEY` |
+
+All three collect an *optional* API key (plus base URL) in onboarding. As noted above, a subscription / OAuth login takes priority over an API key — when the provider's CLI is signed in, a key set in the environment is not used:
+
+- **Codex** — `codex login status` keeps reporting the ChatGPT login even with `OPENAI_API_KEY` set.
+- **Gemini CLI** — uses the OAuth auth type chosen at `gemini` login; `GEMINI_API_KEY` is only consulted if you switch the auth type. The free Google login is the common no-key path locally — sign in once and it just works.
+- **Claude Code** — with both present, `claude auth status` reports it is authenticated via the subscription (`claude.ai`), not the key. The login is auto-detected from the macOS Keychain (or `~/.claude/.credentials.json` on Linux); `CLAUDE_CONFIG_DIR` is **not** required for it — it only relocates Claude Code's config directory (settings/history, not the token) and signals the SDK to strip a conflicting `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`.
+
+The one exception is the **base URL** (`*_BASE_URL`): a custom value points the CLI at a different endpoint (a proxy or gateway) and *does* take effect even under a login — for Gemini it rides the ACP `gateway` param. It's an advanced override, not needed for normal use.
+
+## Onboarding an ACP agent
+
+First-time users get a four-step onboarding modal. To onboard an ACP agent:
+
+1. **Choose agent** — pick Claude Code, Codex, or Gemini CLI instead of OpenHands. The choice is saved immediately to your backend's settings.
+2. **Check backend** — confirms Agent Canvas can reach the Agent Server.
+3. **Set up credentials** — enter the provider's API key (and, optionally, a custom base URL for a proxy or gateway). All three providers collect these here, and every field is optional.
+4. **Say hello** — creates your first conversation and closes the modal.
+
+<Note>
+  Every credential field is optional and the step is skippable. Leave a field blank to reuse a key already set on the backend, or to authenticate the agent through a subscription / OAuth login instead.
+</Note>
+
+### How credentials reach the agent
+
+Each credential you enter is saved as a **global secret** whose name is exactly the environment variable the Agent Server exports into the ACP subprocess (e.g. `ANTHROPIC_API_KEY`). Saving in onboarding is identical to adding the secret under **Settings → Secrets**, where you can edit or remove it anytime. Keeping the secret name equal to the env var is what makes a saved key actually reach the provider CLI.
+
+## Switching agent or model later
+
+Open **Settings → Agent** at any time:
+
+- **Agent** — switch between **OpenHands** and **ACP**.
+- **Preset** — pick a built-in provider (Claude Code, Codex, Gemini CLI) or **Custom** to point at any other ACP server.
+- **Command** — the command line used to spawn the subprocess. Selecting a preset fills this in; editing it to match another preset re-detects that provider. API keys are *not* entered here — they live in the Secrets panel.
+- **Model** — choose a suggested model for the provider or enter a custom model override. Built-in providers save a concrete model rather than leaving it blank.
+
+Saving writes an `agent_settings_diff` (`agent_kind`, `acp_server`, `acp_command`, `acp_model`) to `PATCH /api/settings`. A running conversation keeps the agent it started with; the new choice applies to conversations you start afterward.
+
+## Custom ACP servers
+
+Any stdio ACP server works: choose **Custom** in Settings → Agent and enter its launch command. Custom servers have no curated model list, so enter the model ID the server expects (if any) as a custom model. Pass credentials by adding the env vars the server reads as global secrets under **Settings → Secrets**.
+
+## Related Guides
+
+- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)
+- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles)
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)

openhands/usage/agent-canvas/backend-setup/cloud.mdx

@@ -0,0 +1,43 @@
+---
+title: Cloud Backend
+description: Connect Agent Canvas to OpenHands Cloud for on-demand sandboxed execution.
+---
+
+You can connect Agent Canvas to [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) as a backend. Conversations and automations then run in OpenHands Cloud's on-demand sandboxes instead of on your local machine.
+
+## When to Use It
+
+A Cloud backend is a good fit when you want to:
+
+- Run agents without tying up local resources
+- Use OpenHands Cloud's managed sandboxes and integrations
+- Keep your local machine for development while offloading agent work
+
+## Prerequisites
+
+- An [OpenHands Cloud](https://app.all-hands.dev) account
+- Agent Canvas installed — see [Setup](/openhands/usage/agent-canvas/setup)
+
+## Add a Cloud Backend
+
+1. Open Agent Canvas and click the backend switcher in the top bar.
+2. Choose **Manage Backends** → **Add Backend**.
+3. Click **Login with OpenHands Cloud** and sign in with your account.
+
+Once connected, select it as the active backend. Conversations will now run in OpenHands Cloud.
+
+### OpenHands Enterprise
+
+If your organization runs OpenHands Enterprise, click **Advanced** in the Add Backend flow and enter your enterprise host URL before signing in.
+
+## What's Different with a Cloud Backend
+
+- **Sandboxed execution** — each conversation runs in an isolated cloud sandbox rather than on your host filesystem.
+- **Cloud integrations** — GitHub, GitLab, Bitbucket, Slack, and other integrations configured in OpenHands Cloud are available.
+- **Settings are per-backend** — LLM configuration, secrets, and MCP servers saved against the Cloud backend are independent from your local backend settings.
+
+## Related Guides
+
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud)
+- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local)

openhands/usage/agent-canvas/backend-setup/docker.mdx

@@ -0,0 +1,63 @@
+---
+title: Docker Backend
+description: Run Agent Canvas in a Docker container as a sandboxed backend.
+---
+
+The official Docker image packages the full Agent Canvas stack — agent server, automation backend, and frontend — in a single container. The agent runs inside the container rather than directly on your host, giving you a sandboxed environment out of the box.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed and running
+- Agent Canvas installed locally (if connecting from another instance) — see [Setup](/openhands/usage/agent-canvas/setup)
+
+## Run the Official Image
+
+Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access:
+
+```bash
+docker run -it --rm \
+  -p 8000:8000 \
+  -v ~/.openhands:/home/openhands/.openhands \
+  -v ~/projects:/projects \
+  ghcr.io/openhands/agent-canvas:latest
+```
+
+Agent Canvas is now running at `http://localhost:8000`. The agent can access any project under the mounted `/projects` path.
+
+### Environment Variables
+
+Configuration is passed via `-e` flags on `docker run`:
+
+| Variable | Purpose |
+|----------|---------|
+| `PORT` | Ingress port inside the container (default `8000`). Map it with `-p <host>:<PORT>`. |
+| `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. |
+| `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. |
+
+<Warning>
+  The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set `LOCAL_BACKEND_API_KEY` to a strong secret.
+</Warning>
+
+## Connect from the Frontend
+
+Start the frontend separately and point it at the container:
+
+```bash
+agent-canvas --frontend-only
+```
+
+Then add the Docker backend:
+
+1. Click the backend switcher → **Manage Backends** → **Add Backend**.
+2. Fill in:
+   - **Name** — e.g. `docker-backend`
+   - **Host / Base URL** — `http://localhost:8000`
+   - **API Key** — the `LOCAL_BACKEND_API_KEY` value (check container logs if auto-generated)
+3. Save and select it as the active backend.
+
+## Related Guides
+
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local)
+- [VM Backend](/openhands/usage/agent-canvas/backend-setup/vm)
+- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm)

openhands/usage/agent-canvas/backend-setup/local.mdx

@@ -0,0 +1,53 @@
+---
+title: Local Backend
+description: Run one or more local backends and connect to them from the Agent Canvas UI.
+---
+
+Use `--backend-only` to start a local backend. Each backend runs an agent server and automation backend behind an ingress proxy on its own port.
+
+## Start a Backend
+
+```bash
+agent-canvas --backend-only
+```
+
+This starts the agent server and automation backend on `127.0.0.1:8000`. No frontend is served.
+
+## Running Multiple Backends
+
+You can run several backends at the same time on different ports — for example, one per project or toolchain:
+
+```bash
+agent-canvas --backend-only --port 8001
+agent-canvas --backend-only --port 8002
+agent-canvas --backend-only --port 8003
+```
+
+Each instance gets its own agent server, automation backend, and ingress proxy.
+
+## Connect the Frontend
+
+Start the frontend separately:
+
+```bash
+agent-canvas --frontend-only
+```
+
+Then add your backends through **Manage Backends**:
+
+1. Click the backend switcher → **Manage Backends** → **Add Backend**.
+2. Fill in the **Host / Base URL** (e.g. `http://localhost:8001`) and **API Key**.
+3. Repeat for each backend you started.
+
+Switch between them from the backend selector depending on what you're working on.
+
+<Tip>
+  If you just want a quick single-machine setup, running `agent-canvas` without any flags starts the full stack (frontend + backend) on one port. The split approach above is useful when you want multiple backends or want to keep the frontend and backends on separate processes.
+</Tip>
+
+## Related Guides
+
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [VM Backend](/openhands/usage/agent-canvas/backend-setup/vm) — headless backend on a remote machine
+- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) — backend on a remote machine
+- [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) — run in a container