OpenHands Agent Canvas

What it is

OpenHands Agent Canvas is a browser app for running coding agents. Its README calls it the self-hosted developer control center for coding agents and automations. From one page you start conversations, read files, open a terminal, set models, switch backends and run automations. The agent itself runs on a backend you choose: your machine, a Docker container, a VM, Modal or OpenHands Cloud. It drives the open source OpenHands agent, or Claude Code, Codex, Gemini CLI, Pi and OpenCode through the Agent Client Protocol.

1. You open Agent Canvas in a browser
2. It connects to a backend that runs the agent server
3. The agent works in a folder, container or sandbox
4. Files, terminal and history show in the same page
5. Automations start runs on a schedule or an event

Who it suits

Developers who already use a coding agent and want one place to run it, watch it and schedule it. The README pictures a self-hosted, always-on engineering team. It says one agent server can be shared for code review and dependency updates while your personal agents run on a laptop. Treat the agent as untrusted.

Skip it if you only want a chat window. The pages treat every agent as able to run shell commands and change files, so you need a folder, a container or a machine you are willing to give it.

Where to use it

The docs name several places to run the backend, and one Canvas can switch between them.

• The desktop app preview for macOS, Windows and Linux
• A terminal on macOS, Linux or Windows, through npm or npx
• A Docker container, for the whole stack or one container per conversation
• A VM or always-on machine, reached by SSH tunnel, ngrok or a reverse proxy
• Reaching it from a phone or tablet, through Tailscale or ngrok, while Agent Canvas runs on your computer
• OpenHands Cloud, Modal and Kubernetes backends, which have pages of their own

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with OpenHands’ steps for each route. The quickest is a global npm install. The desktop preview needs no npm and no open terminal.

1. Install Node.js 24 or later and uv.
2. Run the install line, then start the stack.
3. Open http://localhost:8000 in your browser.
4. Go through the setup wizard: choose an agent, check the backend, add a model and pick a starter automation.
5. Choose Open Workspace, then start a conversation.

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

To try it once without a global install:

npx @openhands/agent-canvas

For a sandbox, run the whole stack in Docker instead. The image serves the app at http://localhost:8000/canvas.

mkdir -p ~/projects
docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

How to use it

Start a conversation from the home screen. Choose Open Workspace first if the agent should work in one folder. The backend switcher opens Manage Backends, and settings, models, MCP servers and automations all follow the backend you select.

A meter in the message box shows how full the model’s window is, and you can compact the conversation from it.

Example

You want pull requests reviewed while you work. In the setup wizard you pick the GitHub PR Review Copilot template. The docs say it uses your GitHub MCP connection to poll for new pull requests and runs the review conversations locally, with no cloud infrastructure. Agent Canvas opens a conversation with the prompt filled in, and you finish the details with the agent.

Once you create the automation, it appears in the Automate view. You can switch it off, run it now to test it, or export it as a JSON file for version control.

For newcomers and experts

If you are new. Four pieces matter. The browser app is where you chat. The backend runs the agent. The workspace is the folder it can reach. The agent and model decide who answers and which provider receives your conversation. Start on the default local backend with one small project folder. If nothing loads, the Troubleshooting page starts with node --version, npm --version, uv --version and agent-canvas --help.

For experts. Settings, LLM configuration, MCP servers and automations are all scoped to the active backend. Two keys do different jobs. LOCAL_BACKEND_API_KEY lets the browser talk to a backend, and a model key lets the backend talk to a provider. A model key does not get you into a backend.

The repository holds the Canvas frontend and the local-stack launcher. The Python agent server, the TypeScript client and the automation service live in sibling OpenHands repositories, and config/defaults.json records the versions the npm and Docker installs pin. For one container per conversation, set the runtime before you start:

export OH_CONVERSATION_RUNTIME=docker
export OH_CONVERSATION_IMAGE=ghcr.io/openhands/agent-server:latest-python
agent-canvas

Setting OH_CONVERSATION_RUNTIME_SELECTABLE=1 lets each conversation choose between the host and a container, and Settings > Runtime holds the Docker memory and CPU limits. Any stdio ACP server works as an outside agent: choose Custom in Settings > Agent, enter its launch command and save the variables it reads as global secrets. The package also builds library entrypoints with npm run build:lib, for embedding Canvas components in another app.

Good to know

Agent Canvas lets an agent run commands and change files, so most of the care is about where it runs.

• Name: the repository is called OpenHands, and its README is about Agent Canvas. The docs say openhands serve starts the older GUI server and does not run if you installed only agent-canvas
• Access: run straight on your machine, the agent acts with your user account’s permissions. Docker limits it to the folders you mount, and the docs warn that --privileged weakens that
• Keys: the Docker quickstart puts the session key in the page, which the docs pair with a port published on 127.0.0.1 only. A public deployment needs LOCAL_BACKEND_API_KEY, and the docs say never to expose Agent Canvas without authentication
• Your prompts: they go to the model provider you set, or to the provider behind the outside agent you pick
• Downloads: each outside agent’s default command on the ACP page is an npx -y line. The page says neither Pi nor OpenCode is pre-installed in the Agent Server image, so the first conversation downloads the CLI through npx. The local stack runs its agent server through uv
• Usage data: the Docker page lists AGENT_CANVAS_DISABLE_TELEMETRY for product telemetry. The pages read do not say what it sends
• Desktop preview: the docs call it an early preview, and the macOS app is not yet signed or notarized
• Windows: one container per conversation needs WSL 2
• Docs: the docs site and the repository list different Codex commands for the same preset
• Removal: uninstalling leaves settings and history in ~/.openhands or the openhands-data volume
• License: MIT, with the copyright line OpenHands contributors. Mindket lists only the setup notes, with no part of the software