📦 OpenHands：面向编码 Agent 的自托管开发者控制中心

面向编程智能体与自动化的自托管开发者控制中心。

在本地、远程和云端后端运行 OpenHands、Claude Code、Codex、Gemini 或任何兼容 ACP 的智能体。

OpenHands Agent Canvas 将您的编程智能体转变为自托管、永远在线的工程团队。它是一个开发者控制中心，用于发起对话和自动化日常任务——比如生成报告并发布到 Slack，或自动将 GitHub Issue 分解为任务。

默认情况下，它在您的本地机器上运行，但也可以连接到多个“智能体后端”，例如在 Docker 容器中、虚拟机上或公司基础设施内运行智能体。您也可以选择在 OpenHands 云或 OpenHands Enterprise 基础设施上运行智能体。

Agent Canvas 开箱即用地运行开源的 OpenHands 智能体，但也可以使用任何第三方智能体，如 Claude Code 和 Codex。

如果您有问题或反馈，请提交 GitHub Issue 或加入 Slack 上的 #proj-agent-canvas 频道。

安装

您可以在任何机器上安装 OpenHands 来运行智能体：在您的笔记本电脑上、在像 Mac Mini 这样的专用计算机上，或者在云中的服务器上。

运行 OpenHands 最强大的方式是在云中的服务器上。这使您的智能体即使在笔记本电脑关闭时也能继续运行，并且更容易通过 Slack、GitHub 和 Datadog 等第三方服务触发您的智能体。有关详细信息，尤其是安全加固方面，请参阅自托管指南。

值得注意的是，您可以在多个不同的环境中运行后端，并从同一个 Agent Canvas 前端在它们之间切换。例如，您可以与团队共享一个用于代码审查和依赖更新的智能体服务器，同时让您的个人智能体在您的笔记本电脑上运行。

选项 1：不使用沙箱

警告：这会直接在您安装的机器上运行 agent-server —— 智能体将对您的文件系统拥有完全访问权限！

先决条件：Node.js 22.12.x 或更高版本、uv

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

agent-canvas 命令默认启动完整的本地堆栈。当您想单独运行各部分时，也可以拆分：

agent-canvas --frontend-only # 仅静态前端 + 入口 agent-canvas --backend-only # 仅 agent server + 自动化后端 + 入口

选项 2：使用 Docker 沙箱

先决条件：

• Docker：macOS/Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine/Docker Desktop。
• 一个用于 PROJECTS_PATH 的主机目录，其中包含您希望智能体访问的项目文件夹。在启动容器前创建它。

macOS / Linux：

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.0.0-rc.11

Windows（PowerShell / Windows Terminal）： 请参阅 README.windows.md 以获取等效命令。

智能体将能够访问 PROJECTS_PATH 下的任何项目。

警告：这会直接在您安装的机器上运行 agent-server —— 智能体将对您的文件系统拥有完全访问权限！

先决条件：Node.js 22.12.x 或更高版本、npm、uv（用于通过 uvx 运行 agent server）

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

通过 http://localhost:8000 访问 UI。您可以直接从 UI 添加其他后端。

Agent Canvas 由 OpenHands Agent Server 驱动，这是一个用于在单台机器上运行多个智能体的 REST API。每个 Agent Server 在单个主机/端口上运行；Agent Canvas 可以连接到多个 Agent Server 并轻松在它们之间切换。

您可以在任何地方运行 Agent Server：

• 直接在您的笔记本电脑上（请小心！）
• 在像 Mac Mini 这样的专用机器上
• 在云中的虚拟机上
• 在 OpenHands Cloud（我们的商业产品）内部

Agent Server 通常与 Automation Server 配对，后者允许您设置按计划运行或响应事件运行的智能体。

The self-hosted developer control center for coding agents and automations.

Run OpenHands, Claude Code, Codex, Gemini, or any ACP-compatible agent across local, remote, and cloud backends.

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.

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 the self-hosting guide 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.0.0-rc.11

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

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

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/agent-canvas.git
cd agent-canvas
npm install
npm run dev

Access the UI at http://localhost:8000. You can add additional backends directly from the UI.

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.