OpenHands Agent Canvas turns your coding agents into a self-hosted, always-on engineering team. It's a developer control center for starting conversations and automating everyday tasks — like generating reports that publish to Slack or automatically decomposing GitHub issues into tasks.
It runs locally on your machine by default, but can connect to multiple “agent backends”, e.g. running agents in Docker containers, on VMs, or within your company infrastructure. You can optionally choose to run agents on OpenHands Cloud or OpenHands Enterprise infrastructure.
Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use third-party agents such as Claude Code, Codex, Gemini CLI, Pi, and OpenCode.
| |
|---|
| Self-host your way | Run agents locally, in Docker, on VMs, or anywhere you can run an agent server backend |
| Switch between different backends | Switch between local, remote, and cloud agents without losing focus |
| Create automations | Create automations and workflows that integrate with Slack, GitHub, Linear, and more. Run on a schedule or in response to webhook events |
| Integrate with the tools you use | Connect your automations with third-party services like Slack, GitHub, Notion, and more to automate workflows |
| Bring your own model | Use with any LLM |
| Use with any agent | Use with OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, or any agent with Agent-Client Protocol (ACP). |
If you have questions or feedback, please open a GitHub issue or join the #proj-agent-canvas channel in Slack.
Quickstart
You can install OpenHands to run agents on any machine: on your laptop, on a dedicated computer like a Mac Mini,
or on a server in the cloud.
The most powerful way to run OpenHands is on a server in the cloud. This allows your agents to continue running
even when your laptop is shut, and makes it easier to trigger your agents through third-party services
like Slack, GitHub, and Datadog. See SELF_HOSTING.md for details, especially with respect to security hardening.
Notably, you can run the backend in multiple different environments, and switch between
them from the same Agent Canvas frontend. E.g. you can share an Agent Server with your team for agents doing
code review and dependency updates, then have your personal agents running on your laptop.
Option 1: Without a Sandbox
[!WARNING]
This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!
Prerequisites: Node.js 24 or later, uv
npm install -g @openhands/agent-canvas
agent-canvas
The agent-canvas command starts the full local stack by default. You can also split it when you want to run pieces separately:
agent-canvas --frontend-only # static frontend + ingress only
agent-canvas --backend-only # agent server + automation backend + ingress only
Option 2: With a Docker Sandbox
Install Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux.
Windows users can follow the PowerShell quickstart.
The steps below are for macOS and Linux. A named Docker volume stores settings,
secrets, and conversations; projects are mounted at /projects.
1. Prepare a workspace
export PROJECTS_PATH="$HOME/projects" # directory containing your project folders
mkdir -p "$PROJECTS_PATH"
On Linux Docker Engine, uid 10001 inside the container must be able to read
and write the workspace and its existing files. Grant that user access using
appropriate ownership or ACLs for your system. For a dedicated workspace you are
comfortable sharing with all local users, the following is another option:
find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} +
find "$PROJECTS_PATH" -type f -exec chmod a+rw {} +
These commands grant all host users access to the workspace. Keep it separate
from ~/.openhands and other sensitive data. Docker Desktop on macOS/Windows
handles bind-mount permissions, so those commands are normally unnecessary.
2. Start Agent Canvas
docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v openhands-state:/home/openhands/.openhands \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.40.0 # x-release-please-version
Open http://localhost:8000/canvas. Reuse
openhands-state to retain state across container removals. A fresh volume does
not contain existing ~/.openhands data; inspect or back it up with
docker volume inspect openhands-state.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
