OpenHands Agent Canvas: How to Install It on Windows and Mac

By Shah Rukh, software developer · October 2, 2026 · 7 min read

OpenHands Agent Canvas is an open-source control centre for AI coding agents. It runs on your own computer, opens in your browser, and lets you start coding conversations and set up automations. This guide covers what it is, what you need, how to install it on Windows and Mac, and the precautions to take first.

Read this first. The software is free, but the AI model behind it is not included. You bring your own model, which usually means a paid API key or an existing subscription to an agent such as Claude Code or Codex. Also, two of the four install options run the agent directly on your computer, and the project warns that the agent then has full access to your filesystem. Beginners should use the Docker option.

What OpenHands Agent Canvas is

A coding agent is an AI program that reads a project, edits files and runs commands for you. The OpenHands repository now holds Agent Canvas, which the project describes as “the self-hosted developer control center for coding agents and automations”. Self-hosted means you run it yourself instead of using someone else’s website.

It comes with the open-source OpenHands agent. The project says it can also drive Claude Code, Codex, Gemini, or any agent that speaks ACP (Agent-Client Protocol, a common way for apps to talk to agents). The README marks the project status as beta.

The project says automations can connect to services such as Slack, GitHub, Linear and Notion. One Canvas can connect to several backends and switch between them.

What you need

• For the Docker option: Docker Desktop on Windows or Mac. Docker runs software inside a sealed box called a container.
• For the npm option: Node.js 24 or later, and uv (a Python tool the launcher uses to run the Agent Server).
• A projects folder holding the code you want the agent to work on.
• An AI model. The project says it works “with any LLM” (large language model). The repository lists no prices, so the cost depends on the provider you choose. Agents such as Claude Code, Codex and Gemini can sign in with a subscription login or an API key, according to the project’s ACP document.

The code is under the MIT licence, so it is free to use and modify. OpenHands also sells OpenHands Cloud and OpenHands Enterprise, which are optional. The repository gives minimum hardware only for a server install: it says 2 vCPU and 4 GB RAM “is plenty for a single user”.

Precautions before you install

1. Prefer the Docker sandbox. With Docker, the agent can only reach the folders you share with it. Without it, the agent can read and change anything your user account can.
2. Back up your projects. Commit your work to Git or copy the folder before letting an agent edit it. Share a folder that holds only the projects you want touched.
3. Keep it on your own machine. The quickstart publishes port 8000 on 127.0.0.1 only, which means other devices on your network cannot reach it. Do not change this unless you follow the project’s self-hosting guide.
4. Know where secrets live. Settings are saved in a .openhands folder in your home directory. API keys are stored in the app under Settings → Secrets. The self-hosting guide also notes that the browser’s local storage holds the session key of every backend you register, so do not use a shared browser profile.
5. Your code goes to the AI provider. Whatever the agent reads is sent to the model provider you chose. Check that provider’s terms before using private or client code.
6. Pin what you run. The quickstart uses a fixed image tag, 1.24.0. Copy commands from the official README, not from random sites.
7. Review what the agent did. You are responsible for code the agent writes, including any licence issues in it.

How to install OpenHands on Windows

The project’s Windows document covers the Docker option only. It does not document running the npm option on native Windows.

1. Install Docker Desktop for Windows and start it.
2. Open PowerShell or Windows Terminal.
3. Run these commands. They download the image, create a projects folder and a .openhands folder, and start the container.

docker pull ghcr.io/openhands/agent-canvas:1.24.0

$env:PROJECTS_PATH = Join-Path $HOME "projects"
New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null

docker run -it --rm `
  -p 127.0.0.1:8000:8000 `
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true `
  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
  -v "$($env:PROJECTS_PATH):/projects" `
  ghcr.io/openhands/agent-canvas:1.24.0

Then open http://localhost:8000/canvas in your browser. The agent can reach any project inside your projects folder.

There is also a mode that gives every conversation its own container. On Windows the project says this must run inside WSL 2 (Windows’ built-in Linux), because “the native Windows host is not supported by this runtime”.

How to install OpenHands on Mac

Mac has two documented routes. The same commands work on Linux.

Route 1: Docker sandbox (recommended). Install Docker Desktop, open Terminal, and run:

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

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "$PROJECTS_PATH:/projects" \
  ghcr.io/openhands/agent-canvas:1.24.0

Open http://localhost:8000/canvas.

Route 2: npm, without a sandbox. You need Node.js 24 or later and uv. The self-hosting guide says to install both with brew on macOS. Then run:

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

Open http://localhost:8000 (no /canvas for this route). Remember the warning: this runs the agent straight on your Mac with full file access.

To give each conversation its own Docker container, keep Docker Desktop running and start it like this instead:

OH_CONVERSATION_RUNTIME=docker agent-canvas

The project notes that this isolates conversations only. Canvas itself and the automation service still run on your Mac.

First use

1. Open the address for your install route in a browser.
2. Follow the onboarding screens to choose an agent. The default is the OpenHands agent; Claude Code, Codex and Gemini are also offered.
3. Add your model details. API keys go under Settings → Secrets, and you can change the agent later under Settings → Agent.
4. Start a new conversation, pick a project from your projects folder, and give the agent a small, low-risk task first.

The repository documents the settings screens but not a full click-by-click tour, so the exact wording on screen may differ.

Useful settings and options

If you ever expose the tool beyond your own computer, the project’s guide suggests creating the key with openssl rand -base64 32 and locking down the firewall before the first start. Our password generator can also make a long random value in your browser.

Updating and uninstalling

The project does not document update or uninstall steps. For Docker, the version is the tag at the end of the image name, so check the README for the current tag. The --rm flag in the quickstart removes the container when you stop it, while your settings stay in the .openhands folder.

Common problems

This guide is based on the project’s repository as it was on October 2, 2026. Commands, version numbers and features can change, so check the official README before you install. ToolsCloset is not connected to the project.

More AI tips

Related tools