🙌 OpenHands: AI-Driven Development
docs: Bring README.md over from Agent Canvas (#14844)
Robert Brennan820c96baea25
diff --git a/README.md b/README.mdindex 7e32cfd971..a33318765b 100644--- a/README.md+++ b/README.md@@ -1,153 +1,148 @@<a name="readme-top"></a>-<div align="center">- <img src="https://raw.githubusercontent.com/OpenHands/docs/main/openhands/static/img/logo.png" alt="Logo" width="200">- <h1 align="center" style="border-bottom: none">OpenHands: AI-Driven Development</h1>+ <img src="https://assets.openhands.dev/logo-whitebackground.png" alt="OpenHands logo" width="340">+ <p align="center">+ <strong>The self-hosted developer control center for coding agents and automations.</strong>+ </p>+ <p align="center">+ Run OpenHands, Claude Code, Codex, Gemini, or any ACP-compatible agent across local, remote, and cloud backends.+ </p></div>--<div align="center">- <a href="https://github.com/OpenHands/OpenHands/blob/main/LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-20B2AA?style=for-the-badge" alt="MIT License"></a>- <a href="https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=811504672#gid=811504672"><img src="https://img.shields.io/badge/SWEBench-77.6-00cc00?logoColor=FFE165&style=for-the-badge" alt="Benchmark Score"></a>- <br/>- <a href="https://docs.openhands.dev/sdk"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Check out the documentation"></a>- <a href="https://arxiv.org/abs/2511.03690"><img src="https://img.shields.io/badge/Paper-000?logoColor=FFE165&logo=arxiv&style=for-the-badge" alt="Tech Report"></a>--- <!-- Keep these links. Translations will automatically update with the README. -->- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=de">Deutsch</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=es">Español</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=fr">français</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=ja">日本語</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=ko">한국어</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=pt">Português</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=ru">Русский</a> |- <a href="https://www.readme-i18n.com/OpenHands/OpenHands?lang=zh">中文</a>+ <a href="https://github.com/OpenHands/incubator-program"><img src="https://img.shields.io/badge/status-beta-blue?style=for-the-badge" alt="Project status beta"></a>+ <a href="https://github.com/OpenHands/agent-canvas/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/OpenHands/agent-canvas/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>+ <a href="https://www.npmjs.com/package/@openhands/agent-canvas"><img src="https://img.shields.io/npm/v/%40openhands%2Fagent-canvas?style=for-the-badge&logo=npm" alt="npm version"></a>+ <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/backends"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Documentation"></a>+ <a href="https://go.openhands.dev/slack"><img src="https://img.shields.io/badge/Slack-Join%20the%20community-611f69?logo=slack&logoColor=white&style=for-the-badge" alt="Join us on Slack"></a></div>-+<div align="center">+ <a href="#quickstart">Quickstart</a> |+ <a href="./docs/README.md">Docs</a> |+ <a href="./docs/SELF_HOSTING.md">Self-Hosting</a> |+ <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents">ACP Agents</a> |+ <a href="https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations">Automations</a> |+ <a href="https://go.openhands.dev/slack">Slack</a>+</div>+<p align="center">+ <img src="https://assets.openhands.dev/screenshot/automation-preview.png" alt="Agent Canvas automation preview" width="100%">+</p><hr>-🙌 Welcome to OpenHands, a [community](COMMUNITY.md) focused on AI-driven development. We’d love for you to [join us on Slack](https://dub.sh/openhands).+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.-There are a few ways to work with OpenHands:+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.-### OpenHands Software Agent SDK-The SDK is a composable Python library that contains all of our agentic tech. It's the engine that powers everything else below.+Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use any third-party agent like Claude Code and Codex.-Define agents in code, then run them locally, or scale to 1000s of agents in the cloud.+| | |+|---|---|+| [**Self-host your way**](https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm) | Run agents locally, in Docker, on VMs, or anywhere you can run an agent server backend |+| [**Switch between different backends**](https://docs.openhands.dev/openhands/usage/agent-canvas/backends) | Switch between local, remote, and cloud agents without losing focus |+| [**Create automations**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-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**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations) | Connect your automations with third-party services like Slack, GitHub, Notion, and more to automate workflows |+| [**Bring your own model**](https://docs.openhands.dev/openhands/usage/settings/llm-settings#llm-profiles) | Use with any LLM |+| [**Use with any agent**](https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents) | Use with OpenHands, Claude Code, Codex, Gemini, or any agent with Agent-Client Protocol (ACP). |-[Check out the docs](https://docs.openhands.dev/sdk) or [view the source](https://github.com/OpenHands/software-agent-sdk/)-### OpenHands CLI-The CLI is the easiest way to start using OpenHands. The experience will be familiar to anyone who has worked-with e.g. Claude Code or Codex. You can power it with Claude, GPT, or any other LLM.+If you have questions or feedback, please open a GitHub issue or join the [#proj-agent-canvas channel in Slack](https://openhands.dev/joinslack).-[Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/cli-mode) or [view the source](https://github.com/OpenHands/OpenHands-CLI)+> [!NOTE]+> The code in this repo is moving! See [Agent Canvas transition FAQ](https://github.com/OpenHands/OpenHands/issues/14841)+>+> The source code for Agent Canvas lives in [OpenHands/agent-canvas](https://github.com/OpenHands/agent-canvas) for now.-### OpenHands Local GUI-Use the Local GUI for running agents on your laptop. It comes with a REST API and a single-page React application.-The experience will be familiar to anyone who has used Devin or Jules.+## Quickstart-[Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/local-setup) or view the source in this repo.+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.-### OpenHands Cloud-This is a deployment of OpenHands GUI, running on hosted infrastructure.+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](docs/SELF_HOSTING.md) for details, especially with respect to security hardening.-You can try it for free using the Minimax model by [signing in with your GitHub or GitLab account](https://app.all-hands.dev).+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.-OpenHands Cloud comes with source-available features and integrations:-- Integrations with Slack, Jira, and Linear-- Multi-user support-- RBAC and permissions-- Collaboration features (e.g., conversation sharing)+### Option 1: Without a Sandbox-### OpenHands Enterprise-Large enterprises can work with us to self-host OpenHands Cloud in their own VPC, via Kubernetes.-OpenHands Enterprise can also work with the CLI and SDK above.+> [!WARNING]+> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!-OpenHands Enterprise is source-available--you can see all the source code here in the enterprise/ directory,-but you'll need to purchase a license if you want to run it for more than one month.+**Prerequisites**: Node.js 22.12.x or later, `uv`-Enterprise contracts also come with extended support and access to our research team.+```sh+npm install -g @openhands/agent-canvas+agent-canvas+```-Learn more at [openhands.dev/enterprise](https://openhands.dev/enterprise)+The `agent-canvas` command starts the full local stack by default. You can also split it when you want to run pieces separately:-### Everything Else+```sh+agent-canvas --frontend-only # static frontend + ingress only+agent-canvas --backend-only # agent server + automation backend + ingress only+```-Check out our [Product Roadmap](https://github.com/orgs/openhands/projects/1), and feel free to-[open up an issue](https://github.com/OpenHands/OpenHands/issues) if there's something you'd like to see!+### Option 2: With a Docker Sandbox-You might also be interested in our [evaluation infrastructure](https://github.com/OpenHands/benchmarks), our [chrome extension](https://github.com/OpenHands/openhands-chrome-extension/), or our [Theory-of-Mind module](https://github.com/OpenHands/ToM-SWE).+**Prerequisites**:-All our work is available under the MIT license, except for the `enterprise/` directory in this repository (see the [enterprise license](enterprise/LICENSE) for details).-The core `openhands` and `agent-server` Docker images are fully MIT-licensed as well.+- 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.-If you need help with anything, or just want to chat, [come find us on Slack](https://dub.sh/openhands).+**macOS / Linux:**-<hr>+```sh+export PROJECTS_PATH="$HOME/projects" # directory containing your project folders+mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"-### Thank You to Our Contributors+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+```-<div align="center">+**Windows (PowerShell / Windows Terminal):** See [README.windows.md](https://github.com/OpenHands/agent-canvas/blob/main/README.windows.md) for the equivalent commands.-[](https://github.com/OpenHands/OpenHands/graphs/contributors)+The agent will be able to access any project under `PROJECTS_PATH`.-</div>+### Option 3: From Source-<hr>+> [!WARNING]+> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!-### Trusted by Engineers at+**Prerequisites**: Node.js 22.12.x or later, `npm`, `uv` (for running the agent server via `uvx`)-<div align="center">- <br/><br/>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/tiktok.svg">- <img src="https://assets.openhands.dev/logos/external/black/tiktok.svg" alt="TikTok" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/vmware.svg">- <img src="https://assets.openhands.dev/logos/external/black/vmware.svg" alt="VMware" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/roche.svg">- <img src="https://assets.openhands.dev/logos/external/black/roche.svg" alt="Roche" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/amazon.svg">- <img src="https://assets.openhands.dev/logos/external/black/amazon.svg" alt="Amazon" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/c3-ai.svg">- <img src="https://assets.openhands.dev/logos/external/black/c3-ai.svg" alt="C3 AI" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/netflix.svg">- <img src="https://assets.openhands.dev/logos/external/black/netflix.svg" alt="Netflix" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/mastercard.svg">- <img src="https://assets.openhands.dev/logos/external/black/mastercard.svg" alt="Mastercard" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/red-hat.svg">- <img src="https://assets.openhands.dev/logos/external/black/red-hat.svg" alt="Red Hat" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/mongodb.svg">- <img src="https://assets.openhands.dev/logos/external/black/mongodb.svg" alt="MongoDB" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/apple.svg">- <img src="https://assets.openhands.dev/logos/external/black/apple.svg" alt="Apple" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/nvidia.svg">- <img src="https://assets.openhands.dev/logos/external/black/nvidia.svg" alt="NVIDIA" height="17" hspace="5">- </picture>- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://assets.openhands.dev/logos/external/white/google.svg">- <img src="https://assets.openhands.dev/logos/external/black/google.svg" alt="Google" height="17" hspace="5">- </picture>-</div>+```sh+git clone https://github.com/OpenHands/agent-canvas.git+cd agent-canvas+npm install+npm run dev+```-</div>+---++Access the UI at [http://localhost:8000](http://localhost:8000). You can add additional backends directly from the UI.++# Architecture++Agent Canvas is powered by the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/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](https://github.com/OpenHands/automation), which lets you set up agents that run on a schedule or in response to events.++<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />++## More documentation++- [Documentation index](./docs/README.md)+- [Architecture overview](./docs/architecture.md)+- [Development guide](./docs/DEVELOPMENT.md)+- [Self-hosting guide](./docs/SELF_HOSTING.md)