OpenHands · jpelletier1 · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/docs.json b/docs.json
@@ -40,16 +40,41 @@
             ]
           },
           {
-            "group": "Onboarding OpenHands",
+            "group": "Onboarding Agent Canvas",
             "pages": [
-              "openhands/usage/customization/repository",
-              "openhands/usage/customization/hooks"
+              "openhands/usage/agent-canvas/overview",
+              "openhands/usage/agent-canvas/setup",
+              "openhands/usage/agent-canvas/first-time-setup",
+              {
+                "group": "Setup a Pre-built Automation",
+                "pages": [
+                  "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": "Connect and Manage 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/self-hosting",
+              "openhands/usage/agent-canvas/development",
+              "openhands/usage/agent-canvas/troubleshooting"
             ]
           },
           {
             "group": "Product Guides",
             "pages": [
               "openhands/usage/key-features",
+              "openhands/usage/customization/hooks",
               "overview/model-context-protocol",
               {
                 "group": "Skills",
@@ -74,6 +99,7 @@
                   "openhands/usage/automations/managing-automations"
                 ]
               },
+              "openhands/usage/customization/repository",
               {
                 "group": "Settings",
                 "pages": [

diff --git a/openhands/static/img/agent-canvas-setup-step-1.png b/openhands/static/img/agent-canvas-setup-step-1.png
diff --git a/openhands/static/img/agent-canvas-setup-step-2.png b/openhands/static/img/agent-canvas-setup-step-2.png
diff --git a/openhands/static/img/agent-canvas-setup-step-3.png b/openhands/static/img/agent-canvas-setup-step-3.png
diff --git a/openhands/static/img/agent-canvas-setup-step-4.png b/openhands/static/img/agent-canvas-setup-step-4.png
diff --git a/openhands/usage/agent-canvas/backend-setup/cloud.mdx b/openhands/usage/agent-canvas/backend-setup/cloud.mdx
@@ -0,0 +1,6 @@
+---
+title: Setup an OpenHands Cloud Backend
+description: Connect Agent Canvas to an OpenHands Cloud backend.
+---
+
+Coming soon.
diff --git a/openhands/usage/agent-canvas/backend-setup/docker.mdx b/openhands/usage/agent-canvas/backend-setup/docker.mdx
@@ -0,0 +1,6 @@
+---
+title: Setup a Docker Backend
+description: Run an OpenHands agent server in Docker and connect Agent Canvas to it.
+---
+
+Coming soon.
diff --git a/openhands/usage/agent-canvas/backend-setup/local.mdx b/openhands/usage/agent-canvas/backend-setup/local.mdx
@@ -0,0 +1,6 @@
+---
+title: Setup a Local Backend
+description: Run an OpenHands agent server locally and connect Agent Canvas to it.
+---
+
+Coming soon.
diff --git a/openhands/usage/agent-canvas/backend-setup/vm.mdx b/openhands/usage/agent-canvas/backend-setup/vm.mdx
@@ -0,0 +1,6 @@
+---
+title: Setup a VM Backend
+description: Run an OpenHands agent server on a VM and connect Agent Canvas to it.
+---
+
+Coming soon.
diff --git a/openhands/usage/agent-canvas/backends.mdx b/openhands/usage/agent-canvas/backends.mdx
@@ -0,0 +1,64 @@
+---
+title: Connect and Manage Backends
+description: Use Agent Canvas with local, remote, or cloud-backed OpenHands backends.
+---
+
+Agent Canvas always works against an **active backend**. Conversations, backend-synced settings, and some feature availability depend on which backend is currently selected.
+
+## Default Local Backend
+
+On first launch, Agent Canvas seeds a default local backend that points to the stack started by the `agent-canvas` command.
+
+That default backend is a good fit when you want to:
+
+- Run OpenHands entirely on your current machine
+- Test configuration changes quickly
+- Use the bundled automation backend locally
+
+## Managing Additional Backends
+
+Use the backend switcher in the UI to open `Manage Backends`, then add or edit backend entries.
+
+Each backend entry stores:
+
+- A display name
+- A host or base URL
+- An API key when the backend requires one
+
+Agent Canvas also tracks whether a backend is local or cloud so it can adjust the available flows.
+
+## Local vs. Cloud Backends
+
+| Backend Type | Typical Use |
+|--------------|-------------|
+| **Local** | A machine you control directly, such as your laptop, a VM, or a team-managed host |
+| **Cloud** | A compatible backend running an agent-server or OpenHands Cloud |
+
+## What Changes When You Switch Backends
+
+Switching the active backend changes more than just where conversations run.
+
+- `Settings` read and write against the active backend
+- LLM availability depends on what that backend exposes
+- `Customize > MCP Servers` acts on the active backend's MCP configuration
+- Automations depend on whether the active backend has the automation service available
+
+<Note>
+  If a backend is unreachable, Agent Canvas can still open the backend management flow so you can fix the host, API key, or selection without leaving the app.
+</Note>
+
+## Recommended Setup Pattern
+
+A common setup is to keep one local backend for experimentation and add one or more remote backends for longer-running or more powerful workloads.
+
+Examples:
+
+- A laptop backend for quick local tasks
+- A dedicated VM backend for always-on work
+- A cloud backend for hosted conversations
+
+## Related Guides
+
+- [Setup](/openhands/usage/agent-canvas/setup)
+- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)
+- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting)
diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx
@@ -0,0 +1,59 @@
+---
+title: Customize and Settings
+description: Configure skills, MCP servers, and backend-synced settings in Agent Canvas.
+---
+
+Agent Canvas separates **Customize** from **Settings**.
+
+- `Customize` is where you extend what the agent can use.
+- `Settings` is where you configure backend-synced behavior for the active backend.
+
+## Customize
+
+Open the top-level `Customize` area to manage:
+
+- [Skills](/overview/skills)
+- [MCP Servers](/openhands/usage/settings/mcp-settings)
+
+Use the section navigation inside `Customize` to switch between those pages.
+
+<Note>
+  MCP configuration lives under `Customize > MCP Servers`, not under `Settings`.
+</Note>
+
+## Settings
+
+The `Settings` area currently includes the following sections:
+
+| Section | Purpose |
+|---------|---------|
+| `Agent` | Agent behavior and agent-specific capabilities |
+| `LLM` | Provider, model, API key, and profile configuration |
+| `Condenser` | Context compression and summarization behavior |
+| `Verification` | Approval and verification-related behavior |
+| `Application` | UI-level preferences and app behavior |
+| `Secrets` | Stored secrets used by the active backend |
+
+On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles.
+
+## Backend-Synced Behavior
+
+Each settings section is synced with the **active backend**. That means:
+
+- Changing backends changes which settings you are editing
+- A setting saved for one backend does not automatically apply to every other backend
+- The available options can differ depending on backend capabilities
+
+## Practical Example
+
+You might use this split like this:
+
+- Add a GitHub review skill in `Customize > Skills`
+- Add a Slack or fetch MCP server in `Customize > MCP Servers`
+- Save your preferred model in `Settings > LLM`
+- Store tokens in `Settings > Secrets`
+
+## Related Guides
+
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations)
diff --git a/openhands/usage/agent-canvas/development.mdx b/openhands/usage/agent-canvas/development.mdx
@@ -0,0 +1,104 @@
+---
+title: Contribute / Development
+description: Clone Agent Canvas, run it from source, and use the developer workflows.
+---
+
+This page is for contributors and advanced users who want to run Agent Canvas from a local checkout. If you only want to use Agent Canvas, follow the [Setup](/openhands/usage/agent-canvas/setup) guide instead.
+
+## Clone the Repository
+
+```bash
+git clone https://github.com/OpenHands/agent-canvas.git
+cd agent-canvas
+npm install
+```
+
+## Recommended Local Workflow
+
+The standard development flow runs the full local stack with live frontend updates:
+
+```bash
+npm run dev
+```
+
+That workflow uses `uvx` to start the agent server and automation backend, then fronts them with the Vite dev server and ingress proxy.
+
+That workflow starts:
+
+- the Agent Canvas frontend
+- the OpenHands agent server
+- the automation backend
+- the ingress proxy that ties them together
+
+## Other Useful Development Modes
+
+| Command | When to Use It |
+|---------|----------------|
+| `npm run dev` | Full local development stack |
+| `npm run dev:static` | Serve a static frontend build instead of the Vite dev server |
+| `npm run dev:minimal` | Run only the agent server and Vite, without automation or ingress |
+| `npm run dev:extra-backend` | Start an additional local backend that shares the main dev stack's persistence |
+| `npm run dev:frontend` | Point the frontend at a separately managed backend |
+| `npm run dev:mock` | Work on the UI without a live backend |
+
+`npm run dev:minimal` serves the frontend directly on `http://localhost:3001`.
+
+`npm run dev:frontend` expects a separately managed backend at `127.0.0.1:8000` unless you override the frontend proxy settings.
+
+## Verification Commands
+
+Use the repo's built-in checks before sending a change upstream:
+
+```bash
+npm run test
+npm run build
+```
+
+## Development Environment Variables
+
+You can place frontend overrides in a local `.env` file based on `.env.sample`.
+
+These variables are mainly useful when you are running Agent Canvas from a local checkout.
+
+### Launcher Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PORT` | Ingress port for the bundled development stack |
+| `OH_AUTOMATION_GIT_REF` | Git ref used for the automation backend |
+| `OH_CANVAS_SAFE_BACKEND_PORT` | Backend port for the isolated local agent server |
+| `OH_CANVAS_SAFE_VSCODE_PORT` | VS Code sidecar port for the isolated local agent server |
+| `OH_CANVAS_SAFE_STATE_DIR` | Base directory for isolated local state |
+
+### Frontend Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_BACKEND_BASE_URL` | Base URL used by browser-side requests |
+| `VITE_BACKEND_HOST` | Backend target for the Vite dev proxy |
+| `VITE_SESSION_API_KEY` | Session API key to send when the backend requires one |
+| `VITE_WORKING_DIR` | Workspace path used for new conversations; defaults to the current checkout |
+| `VITE_WORKER_URLS` | Optional worker URLs for Browser integrations |
+| `VITE_ENABLE_BROWSER_TOOLS` | Disable browser tools for new conversations when set to `false` |
+| `VITE_LOAD_PUBLIC_SKILLS` | Enable loading public skills when set to `true` |
+| `VITE_FRONTEND_PORT` | Frontend dev server port |
+| `VITE_USE_TLS` | Use HTTPS or WSS for the dev proxy |
+| `VITE_INSECURE_SKIP_VERIFY` | Skip TLS verification for proxied backend requests |
+| `VITE_MOCK_API` | Enable mock API responses |
+
+## Advanced Source Overrides
+
+The development stack also supports source and version overrides for the agent server:
+
+- `OH_AGENT_SERVER_LOCAL_PATH`
+- `OH_AGENT_SERVER_GIT_REF`
+- `OH_AGENT_SERVER_VERSION`
+
+When more than one is set, the effective precedence is local source path, then git ref, then pinned version.
+
+These are useful when you are developing Agent Canvas alongside a local `software-agent-sdk` checkout.
+
+## Learn More
+
+- [Agent Canvas Repository](https://github.com/OpenHands/agent-canvas)
+- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting)
diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx
@@ -0,0 +1,69 @@
+---
+title: First Time Setup
+description: Configure Agent Canvas after installation — choose your agent, connect a backend, add an LLM, and launch your first automation.
+---
+
+When you open Agent Canvas for the first time, a four-step setup wizard walks you through the core configuration. Each step can be skipped and revisited later from `Settings`.
+
+## Step 1: Choose Your Agent
+
+![Agent Canvas first-time setup — Choose your agent screen showing OpenHands, Claude Code, Codex, and Gemini CLI options](/openhands/static/img/agent-canvas-setup-step-1.png)
+
+Agent Canvas uses the **Agent-Client Protocol (ACP)** to communicate with agents, which means you're not locked into a single provider.
+
+- **OpenHands** (selected by default) — the general-purpose OpenHands agent, best for coding and exploration.
+- **Claude Code** — Anthropic's Claude Code agent.
+- **Codex** — OpenAI's Codex agent.
+- **Gemini CLI** — Google's Gemini CLI agent.
+
+Choosing a third-party agent lets you interact with it through the Agent Canvas interface and bring your existing subscriptions from those providers.
+
+You can change your agent at any time from `Settings`.
+
+## Step 2: Check Your Backend
+
+![Agent Canvas first-time setup — Check your backend screen showing a connected local backend at 127.0.0.1:8000](/openhands/static/img/agent-canvas-setup-step-2.png)
+
+Agent Canvas routes all conversations through an **agent server backend**. By default, it connects to your local machine (`http://127.0.0.1:8000`), which is ideal for working on local projects.
+
+The setup screen shows your current backend connection status. If the server is running, you'll see a **"You're connected!"** confirmation.
+
+Each backend entry stores:
+
+- A display name (e.g. `Local`)
+- A host URL
+- An optional API key
+
+<Note>
+  To add remote or cloud backends, or to manage multiple backend connections, see [Connect and Manage Backends](/openhands/usage/agent-canvas/backends).
+</Note>
+
+## Step 3: Set Up Your LLM
+
+![Agent Canvas first-time setup — Set up your LLM screen showing provider and model selection with an API key field](/openhands/static/img/agent-canvas-setup-step-3.png)
+
+Agent Canvas supports **bring-your-own LLM key**. Select your LLM provider and model, then paste in your API key.
+
+Available options:
+
+- **Direct provider keys** — use your own API key from Anthropic, OpenAI, Google, or any other supported provider.
+- **OpenHands Cloud** — use an [OpenHands Cloud](https://app.all-hands.dev) API key to access verified models without managing provider accounts directly. Find your API key in the `API Keys` tab of OpenHands Cloud.
+
+The setup screen defaults to `OpenHands` as the provider and pre-selects a recommended model. Switch the `LLM Provider` dropdown to choose a different provider.
+
+## Step 4: Start From a Proven Workflow
+
+![Agent Canvas first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest](/openhands/static/img/agent-canvas-setup-step-4.png)
+
+Agent Canvas is designed as an **automation-centric developer control center**. The final setup step invites you to kick things off with a pre-built workflow template rather than starting from a blank conversation.
+
+Each template bundles an agent prompt, an implementation sketch, and the MCP connections needed to run it. Pick one to open a pre-filled conversation and finish the details with the agent.
+
+A recommended starting point is the **[GitHub PR Review Copilot](/openhands/usage/agent-canvas/prebuilt/github-pr-review)**. This automation uses your GitHub MCP connection to poll for new pull requests and run agent review conversations locally — no cloud infrastructure required.
+
+Other available templates include:
+
+- **GitHub Repository Monitor** — watch a repository for `@OpenHands` mentions and respond automatically.
+- **Slack Standup Digest** — summarize yesterday's Slack activity into an async standup note.
+
+You can browse all pre-built automations from the `Automate` view at any time. See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) for the full list.