OpenHands · rbren · 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,155 @@
+---
+title: Setup a Docker Backend
+description: Build a custom Agent Canvas image and connect Agent Canvas to it.
+---
+
+This guide walks through building a **custom Agent Canvas image** that layers extra tooling (for example, the JDK) on top of the official base image, running it locally with Docker, and registering it as a backend in Agent Canvas.
+
+Use this approach when the default backend's toolchain is missing something your agent needs, such as a specific language runtime, build tool, or CLI.
+
+## Prerequisites
+
+- Docker installed and running
+- An LLM API key (Anthropic, OpenAI, etc.)
+- Agent Canvas installed and running locally — see [Setup](/openhands/usage/agent-canvas/setup)
+
+## 1. Build a Custom Image
+
+Agent Canvas publishes an all-in-one base image at `ghcr.io/openhands/agent-canvas`. It bundles the agent server, automation backend, and frontend. Extend it with a small `Dockerfile` that installs whatever your agent needs.
+
+The example below adds the JDK and a few common utilities. Save it as `Dockerfile`:
+
+```dockerfile icon="docker"
+FROM ghcr.io/openhands/agent-canvas:latest
+
+USER root
+
+# Install Java (JDK) and common build/diagnostic utilities.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      default-jdk \
+      maven \
+      unzip \
+      vim \
+      less \
+ && rm -rf /var/lib/apt/lists/*
+
+# Switch back to the unprivileged user that the base image runs as.
+USER openhands
+```
+
+<Note>
+  The base image already ships with Python, Node.js, `git`, `jq`, `tmux`, build tools, and a VS Code Web + VNC stack. Only add what you actually need on top.
+</Note>
+
+<Tip>
+  For fully reproducible builds, pin to a specific version tag like `1.0.0-beta.5` instead of `latest`.
+</Tip>
+
+Build the image with a tag you can reference later:
+
+```bash
+docker build -t agent-server-java:latest .
+```
+
+<Tip>
+  The `ghcr.io/openhands/agent-canvas` image supports both amd64 and arm64. Docker automatically pulls the correct architecture. If you need to force a platform, pass `--platform linux/amd64` to `docker build`.
+</Tip>
+
+## 2. Run the Custom Image
+
+Start the image, expose the agent server's HTTP port, and protect it with a session API key. The agent server reads `SESSION_API_KEY` from the environment and requires the same value on the `X-Session-API-Key` header for every request.
+
+Use the same name for the container as you'll use for the Agent Canvas backend — it makes it easy to tell which container backs which backend later.
+
+```bash
+# Pick any sufficiently random value; you'll paste it into Agent Canvas later.
+export SESSION_API_KEY="$(openssl rand -hex 32)"
+
+docker run -d \
+  --name agent-server-java \
+  -p 8001:8000 \
+  -e SESSION_API_KEY="$SESSION_API_KEY" \
+  agent-server-java:latest
+```
+
+Verify the server is reachable:
+
+```bash
+curl -H "X-Session-API-Key: $SESSION_API_KEY" http://localhost:8001/health
+```
+
+<Warning>
+  The agent server can execute arbitrary shell commands inside the container. Treat `SESSION_API_KEY` like a production credential and **do not expose port 8001 to the public internet** without a TLS-terminating reverse proxy in front of it.
+</Warning>
+
+To follow logs or stop the container:
+
+```bash
+docker logs -f agent-server-java
+docker stop agent-server-java
+```
+
+## 3. Add the Backend in Agent Canvas
+
+With the container running, point Agent Canvas at it:
+
+1. Open Agent Canvas.
+2. Click the backend switcher in the top bar and choose **Manage Backends**.
+3. Click **Add Backend** and fill in:
+   - **Name** — `agent-server-java` (matching the container name)
+   - **Host / Base URL** — `http://localhost:8001`
+   - **API Key** — the `SESSION_API_KEY` value from step 2
+   - **Type** — `Local`
+4. Save the backend and select it as the **active backend**.
+
+Agent Canvas will run a health check against the URL. Once it passes, the backend is ready to handle conversations using the tools you baked into the image.
+
+<Note>
+  See [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) for what changes when you switch the active backend (settings, LLM availability, MCP servers, automations).
+</Note>
+
+## Running Multiple Custom Backends
+
+You can build as many custom images as you need and run each one as its own backend in Agent Canvas. A common pattern is one image per language or repo toolchain — for example a `agent-server-java` for JVM work, a `agent-server-rust` for Cargo projects, and a `agent-server-data` image with the Python data stack pre-installed.
+
+Give each container its own name, its own host port, and its own `SESSION_API_KEY`, then add a matching backend entry in Agent Canvas for each one:
+
+```bash
+# JVM toolchain on port 8001
+docker run -d --name agent-server-java \
+  -p 8001:8000 -e SESSION_API_KEY="$JAVA_KEY" \
+  agent-server-java:latest
+
+# Rust toolchain on port 8002
+docker run -d --name agent-server-rust \
+  -p 8002:8000 -e SESSION_API_KEY="$RUST_KEY" \
+  agent-server-rust:latest
+
+# Python data stack on port 8003
+docker run -d --name agent-server-data \
+  -p 8003:8000 -e SESSION_API_KEY="$DATA_KEY" \
+  agent-server-data:latest
+```
+
+In **Manage Backends**, add one entry per container using the matching name, URL, and API key. You can then switch between them from the backend selector depending on what kind of task you're working on.
+
+## Updating the Image
+
+When you want to add more tooling or pick up a newer Agent Canvas release:
+
+```bash
+docker pull ghcr.io/openhands/agent-canvas:latest
+docker build -t agent-server-java:latest .
+docker stop agent-server-java && docker rm agent-server-java
+# then re-run the `docker run` from step 2
+```
+
+The existing backend entry in Agent Canvas keeps working as long as the host, port, and `SESSION_API_KEY` stay the same.
+
+## Related Guides
+
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [Setup a Local Backend](/openhands/usage/agent-canvas/backend-setup/local)
+- [Setup a VM Backend](/openhands/usage/agent-canvas/backend-setup/vm)
+- [Agent Server Overview](/sdk/guides/agent-server/overview)
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,75 @@
+---
+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.
+
+## What is a "Backend"?
+A **backend** is any environment where the OpenHands agent can execute work. 
+
+Each backend includes:
+- An **[OpenHands Agent Server](/sdk/guides/agent-server/overview#what-is-a-remote-agent-server)** that servers as a lightweight HTTP API server for remote agent execution. 
+- A **workspace** where files are made available to the agent, and where the agent runs.
+
+With the backend concept, users can setup a backend for each code repository (thus having a unique backend and execution environment for each repo). 
+
+Users can also connect Agent Canvas to [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) as a backend, enabling conversations and [automations](/openhands/usage/automations/overview) to use OpenHands Cloud on-demand sandboxes for agent execution.
+
+## 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)