Overview

Edits files, runs tests and browses documentation inside an isolated container, so a failed run cannot damage the host. Competitive on SWE-bench style benchmarks, but budget carefully before pointing it at a real repository — long autonomous runs consume a great deal of tokens and still need review before anything is merged.

What can you do with OpenHands?

Run the whole stack locally — npm install -g @openhands/agent-canvas installs the launcher, and the agent-canvas command starts the full local stack by default at localhost:8000, with --frontend-only and --backend-only to run the pieces separately.
Sandbox the agent in Docker — Running ghcr.io/openhands/agent-canvas with -v ${PROJECTS_PATH}:/projects gives the agent access to any project under PROJECTS_PATH, while the npm and from-source launchers carry the README's warning that the agent server has full access to your filesystem.
Switch between agent backends — Agent Canvas talks to OpenHands Agent Servers over REST, one per host/port, so a shared server doing code review and dependency updates and a laptop-local agent sit in the same frontend and are added from the UI.
Use agents other than OpenHands — Claude Code, Codex, Gemini or any Agent-Client Protocol (ACP) agent runs in the same canvas, and the LLM behind them is yours to choose.
Automate recurring engineering chores — Paired with the Automation Server, agents run on a schedule or on webhook events — decomposing GitHub issues into tasks, or publishing generated reports to Slack — with integrations for Slack, GitHub, Linear and Notion.

Documentation

Reproduced from the OpenHands/OpenHands README, published under MIT. Read the original ↗

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 any third-party agent like Claude Code and Codex.


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, 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 22.12.x 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

Prerequisites:

Docker: Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux.
A host directory for PROJECTS_PATH containing the project folders you want the agent to access. Create it before starting the container.

macOS / Linux:

export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
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.13.0 # x-release-please-version

Windows (PowerShell / Windows Terminal): See README.windows.md for the equivalent commands.

The agent will be able to access any project under PROJECTS_PATH.

Option 3: From Source

[!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 22.12.x or later, npm, uv (for running the agent server via uvx)

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

Access the UI at http://localhost:8000 for the npm/source launchers, or http://localhost:8000/canvas for the Docker image. You can add additional backends directly from the UI.

Architecture

Agent Canvas is powered by the OpenHands Agent Server, a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.

You can run an Agent Server anywhere:

Directly on your laptop (be careful!)
On a dedicated machine like a Mac Mini
On a virtual machine in the cloud
Inside OpenHands Cloud (our commercial offering)

The Agent Server is often paired with an Automation Server, which lets you set up agents that run on a schedule or in response to events.