OpenHands Agent Canvas: a self-hosted control center for coding agents

What Agent Canvas is for, and who ends up running it

OpenHands Agent Canvas is a self-hosted front end for coding agents. The README calls it "the self-hosted developer control center for coding agents and automations", and the description is literal: you get a browser UI where you start conversations with an agent, and a scheduling layer where the same agents run tasks without you watching. The agents themselves are not the product here. Canvas ships the open source OpenHands agent out of the box and can also drive Claude Code, Codex, Gemini, or anything that speaks the Agent-Client Protocol.

The audience is narrower than "developers who want AI help". Canvas assumes you are willing to operate a service. The README states that the most capable setup is a server in the cloud, because agents keep running when your laptop is shut and because Slack, GitHub and Datadog can then trigger them. That is an infrastructure decision, not an editor plugin. If you only want an agent inside your terminal, Canvas adds a backend, a port and a state directory you now have to look after.

The second audience is teams that already have opinions about where code executes. Canvas separates the front end from the agent backend, so a shared server can handle code review and dependency updates while your personal agents run on your own machine, and you switch between them from the same UI. That split is the actual reason to pick this over a single-agent CLI.

How the front end, the agent server and the backends fit together

The architecture visible in the repository is a React Router application (the package.json lists @react-router/node and @react-router/serve) built with Vite, talking to an agent server over HTTP. The .env.sample file makes the seam explicit. VITE_BACKEND_HOST is the host and port used by the Vite dev proxy, and VITE_BACKEND_BASE_URL is the base URL used by browser-side direct requests. Both default to 127.0.0.1:8000. When those two point at different places, the proxy and the browser are talking to different servers, which is a real configuration to watch for.

Backends are the second axis. The documentation describes local, Docker, VM and company-infrastructure execution, plus optional OpenHands Cloud or Enterprise. The same .env.sample notes that to drive a containerized ACP agent server you point VITE_BACKEND_BASE_URL at the published port, and gives localhost:8010 as the example, with examples/acp-docker/ and docs/ACP_AGENTS.md as the references. So the front end is deliberately backend-agnostic: the agent server is the thing that actually holds the workspace and runs commands.

State is split too. VITE_WORKING_DIR sets the base directory for per-conversation working directories, and each conversation's working_dir is <VITE_WORKING_DIR>/<id_hex>. If it is unset, it defaults to <OH_CANVAS_SAFE_STATE_DIR>/workspaces, which the sample comment describes as the sibling of the agent server's <state_dir>/conversations/ persistence directory, sharing the same <id_hex> per conversation. That pairing is worth understanding before you move a state directory, because the two halves are expected to line up.

Installing OpenHands Agent Canvas with npm, Docker or from source

There are three documented paths. The npm path is the shortest, and the README states the prerequisites as Node.js 22.12.x or later and uv. Note the mismatch: the package.json engines field asks for node >=24, so on a Node 22 runtime npm may warn or refuse. The README also warns that this mode runs the agent server directly on the machine you install on, with full access to your filesystem.

npm install -g @openhands/agent-canvas
agent-canvas

Running agent-canvas starts the full local stack. The README also gives two split modes: agent-canvas --frontend-only starts the static frontend and ingress only, and agent-canvas --backend-only starts the agent server, the automation backend and ingress only. Use the split modes when you want the two halves on different hosts.

The Docker path is the one to prefer on a laptop, because the agent is confined to a container. You need Docker Desktop on macOS or Windows, or Docker Engine or Docker Desktop on Linux, and you must create a host directory for PROJECTS_PATH before starting the container. The README's macOS and Linux commands are:

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 8000:8000 \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.16.0

The agent can reach any project under PROJECTS_PATH, so keep that directory to the repositories you actually want it to touch. Windows users get equivalent commands in README.windows.md rather than in the main README. The source path is a clone, npm install, npm run dev; the README lists Node.js 22.12.x or later, npm and uv as prerequisites, and repeats the filesystem warning.

Once it is up, the README says the UI is at http://localhost:8000 for the npm and source launchers, and at http://localhost:8000/canvas for the Docker image. Additional backends are added from the UI.

Automations, ACP agents and what the UI is actually orchestrating

The feature that distinguishes Canvas from a chat window is automations. The README describes creating automations and workflows that integrate with Slack, GitHub, Linear and others, running either on a schedule or in response to webhook events, and gives two examples: generating reports that publish to Slack, and decomposing GitHub issues into tasks. The repository layout backs this up with a config/ directory, a helm/ directory for cluster deployment, and a docs/SELF_HOSTING.md that the README points to specifically for security hardening.

Agent support is handled through the Agent-Client Protocol. The README lists OpenHands, Claude Code, Codex, Gemini and "any agent with Agent-Client Protocol (ACP)", and the docs link to an ACP agents page plus examples/acp-docker/ for the containerized case. Model choice is separate again: the README says you can bring your own model and points at LLM profiles in the settings documentation, so the agent and the model are two independent selections.

The .env.sample adds one detail worth knowing before you expose this to a team: VITE_SESSION_API_KEY, which the sample says should be set to the same value as the backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled. Auth is therefore something the agent server enforces and the front end has to be told about, not something Canvas turns on for you.

Where Agent Canvas is the wrong tool

The no-sandbox install is the sharpest limitation, and the README flags it twice with a warning block: it runs the agent server directly on the machine you are installing on, and the agent will have full access to your filesystem. That is not a configuration footnote. An agent that can read and write anywhere on your machine, driven by a model you may not control, is a different risk class from an agent in a container. If your reason for self-hosting is that code must not leave your perimeter, the no-sandbox path does not deliver that on its own.

The second limit is operational. Canvas is a service with a front end, an agent server, an automation backend and an ingress, plus a state directory and a working-directory tree that must stay paired. Running it on a laptop is supported, but the README's own argument for a server is that agents keep working when the laptop is closed. That argument cuts both ways: a server you do not patch is an always-on agent with credentials.

The third is scope. If your workflow is one developer, one repository, one terminal session, the backend abstraction earns nothing. You are paying for multi-backend switching and scheduled automations that you will not use. The README does not document rollback or downgrade steps for the container image, so pinning a version tag is the only version control the documentation gives you.

OpenHands Agent Canvas versus a single-agent CLI such as Claude Code

The obvious comparison is Claude Code, and the difference is not model quality. Claude Code is one agent, one vendor's models, running in your terminal or editor. Canvas is a control plane that can run Claude Code as one of its agents, alongside OpenHands, Codex, Gemini and any ACP-compatible agent. So the choice is between a tool and a place to run tools.

A second comparison is a plain agent server with no UI. The .env.sample shows Canvas pointing at 127.0.0.1:8000 by default and at localhost:8010 for a containerized ACP agent server, which means the agent server is a separate component you could drive directly. What Canvas adds on top is the conversation UI, the backend switcher, the automations and the scheduling. If none of those matter, the agent server alone is less to operate.

The third axis is where execution happens. A local CLI runs where you run it. Canvas lets one front end reach a shared team server and a personal laptop backend at the same time, which is genuinely useful for review and dependency-update workloads that should not depend on anyone's machine being awake. That is the trade: you accept a service to operate in exchange for agents that outlive your session.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-27, which is recent. Releases arrive often: v1.14.0 on 2026-08-17, v1.15.0 on 2026-08-21 and v1.16.0 on 2026-08-27, roughly weekly. The package.json version is 1.18.0, ahead of the newest release listed here, so the npm package and the release tags are not always in lockstep. If you pin ghcr.io/openhands/agent-canvas:1.16.0 as the README does, you are pinned to a tag that will fall behind quickly, and the README does not document a downgrade path for that image.

Licensing is where the material gets thin. The package.json declares "license": "MIT" for @openhands/agent-canvas, and the repository has a top-level LICENSE file, but the repository metadata provided here lists the license as unknown. Those two signals do not agree, and the LICENSE file itself is not shown. Treat the npm package's MIT declaration as the claim to check rather than a settled fact, especially before redistributing the front end.

The practical upgrade cost sits in the state directories. Because a conversation's working_dir is <VITE_WORKING_DIR>/<id_hex> and defaults to <OH_CANVAS_SAFE_STATE_DIR>/workspaces, which the sample describes as the sibling of the agent server's <state_dir>/conversations/ with the same <id_hex>, moving or recreating one of those directories without the other is the kind of change that breaks conversation history. Back both up together before an upgrade.

Editorial conclusion

Adopt Agent Canvas if you want one self-hosted front end for several coding agents and several execution backends, and you are willing to run the Docker path or harden a server yourself. Skip it if you want a single CLI agent on your laptop with no extra service to operate, or if you cannot give the agent a sandbox and cannot accept that it will have full access to your filesystem. Before rolling it out, verify three things: which backend the no-sandbox mode will touch, whether SESSION_API_KEY or OH_SESSION_API_KEYS_0 is set on your agent server, and whether your Node runtime satisfies the engines field, which asks for Node 24 or later even though the quickstart text says 22.12.x.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes