OpenHands/README.md

agent-canvas

Warning

This project is in sandbox phase. It may be vibecoded, untested, or out of date. OpenHands takes no responsibility for the code or its support. Learn more.

Agent Canvas is a web frontend for managing agents. You can:

• ⌨️ prompt them manually
• 🕐 run them on a schedule
• ⚡ trigger them automatically—e.g. from Slack or GitHub.

Agents can run anywhere:

• 🧑‍💻 on your laptop
• 🖥️ on a remote virtual machine
• ☁️ in our hosted cloud
• 🏢 or inside your company’s infrastructure

You can work with any agent (e.g. Claude Code, Codex) or connect directly to an LLM (e.g. Anthropic, OpenAI, Gemini, Mistral, Minimax, Kimi).

If you have questions or feedback, please open a GitHub issue or join the #proj-agent-canvas channel in Slack

Quickstart

With Docker (recommended)

Prerequisites:

• Node.js 22.12.x or later
• npm
• Docker

Set $PROJECT_PATH to the directory on your machine where your projects live (e.g. /path/to/your/projects). The agent server will mount this directory so the agent can read and edit your code.

By default the container is kept isolated from your host home — only ~/.openhands, ~/.claude, ~/.codex, and ~/.ssh are mounted individually (and only if they exist). If you want the Add Workspace dialog to browse your real host filesystem, set OH_MOUNT_HOST_HOME=1 before npm run dev:docker to bind-mount your entire host home onto /home/openhands in the container. The Add Workspace modal also shows this hint inline when it detects the mount is off. Watch the video on how to run this on Mac or Windows.

export PROJECT_PATH=/path/to/your/projects
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev:docker

Windows PowerShell exception: if npm run dev:docker starts the backend but localhost:8000 shows Bad Gateway and the logs include a Vite error like 'C:\Program' is not recognized, start the same stack directly with Node instead. Replace the path below with your projects folder, and do not include any prompt characters or a trailing > in the value.

$env:PROJECT_PATH = "/path/to/your/projects"
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
node --env-file-if-exists=.env .\scripts\dev-docker.mjs

Access the UI at http://localhost:8000

Without Docker

Warning

This runs the agent-server directly on the machine you're installing on--the agent will have full access to your filesystem!

Running without docker is great if you're running Agent Canvas on a VM. See SELF_HOSTING.md for details, especially with respect to security hardening. Notably, you can run the backend on multiple different VMs and switch between them from the same Agent Canvas frontend!

Prerequisites:

• Node.js 22.12.x or later
• npm
• uv (for running the agent server via uvx)

git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev:dangerously-dockerless

Access the UI at http://localhost:8000

If you're not actively developing on agent-canvas and just want to run it locally, use the static build instead (faster loads, no hot reload):

npm run dev:static

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!)
• Inside a Docker container
• On a dedicated machine like a Mac Mini
• On a virtual machine in the cloud
• Inside a Kubernetes Pod
• 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.

npm Package

Agent Canvas is also available as an npm package for embedding in your own applications:

Warning

Agent Canvas has not published a stable release yet. Until the first stable version is available, the npm latest dist-tag may point to alpha, beta, or release-candidate builds, so npm install @openhands/agent-canvas can install a prerelease. Pin an exact version if you need predictable behavior. This temporary behavior is tracked in #395; retag latest to the first stable release when it ships.

npm install @openhands/agent-canvas

Usage

Import the full package or specific components:

// Full package
import { AgentServerUIProviders } from '@openhands/agent-canvas';

// Individual component packages
import { BrowserPanel } from '@openhands/agent-canvas/browser';
import { ChatPanel } from '@openhands/agent-canvas/conversation';
import { FileExplorer } from '@openhands/agent-canvas/files';
import { TerminalPanel } from '@openhands/agent-canvas/terminal';

Available Subpath Exports

Subpath	Description
@openhands/agent-canvas	Main entry with providers and core components
@openhands/agent-canvas/browser	Browser/preview panel components
@openhands/agent-canvas/conversation	Chat interface and message components
@openhands/agent-canvas/files	File explorer and editor components
@openhands/agent-canvas/settings	Settings screens and forms
@openhands/agent-canvas/sidebar	Sidebar navigation components
@openhands/agent-canvas/terminal	Terminal emulator component
@openhands/agent-canvas/i18n	Internationalization resources

More documentation

For contributor and developer workflows, including frontend-only mode, mock mode, environment variables, and build/test commands, see DEVELOPMENT.md.