# OpenHands **Repository Path**: trusted-list/OpenHands ## Basic Information - **Project Name**: OpenHands - **Description**: 🙌 OpenHands: AI-Driven Development - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: https://openhands.dev - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-03-13 - **Last Updated**: 2026-11-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
OpenHands logo

Agent Canvas

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

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

CI status npm version Documentation Join us on Slack
Quickstart | Docs | Self-Hosting | ACP Agents | Automations | Slack

Agent Canvas automation preview

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 third-party agents such as Claude Code, Codex, Gemini CLI, Pi, and OpenCode. | | | | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [**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, Pi, OpenCode, 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](https://openhands.dev/joinslack). ## 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](docs/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](https://nodejs.org/) 24 or later, `uv` ```sh 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: ```sh agent-canvas --frontend-only # static frontend + ingress only agent-canvas --backend-only # agent server + automation backend + ingress only ``` ### Option 2: With a Docker Sandbox Install Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux. Windows users can follow the [PowerShell quickstart](./README.windows.md). The steps below are for macOS and Linux. A named Docker volume stores settings, secrets, and conversations; projects are mounted at `/projects`. **1. Prepare a workspace** ```sh export PROJECTS_PATH="$HOME/projects" # directory containing your project folders mkdir -p "$PROJECTS_PATH" ``` On **Linux Docker Engine**, uid 10001 inside the container must be able to read and write the workspace and its existing files. Grant that user access using appropriate ownership or ACLs for your system. For a dedicated workspace you are comfortable sharing with all local users, the following is another option: ```sh find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} + find "$PROJECTS_PATH" -type f -exec chmod a+rw {} + ``` These commands grant all host users access to the workspace. Keep it separate from `~/.openhands` and other sensitive data. Docker Desktop on macOS/Windows handles bind-mount permissions, so those commands are normally unnecessary. **2. Start Agent Canvas** ```sh docker run -it --rm \ -p 127.0.0.1:8000:8000 \ -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \ -v openhands-state:/home/openhands/.openhands \ -v "${PROJECTS_PATH}:/projects" \ ghcr.io/openhands/agent-canvas:1.37.0 # x-release-please-version ``` Open [http://localhost:8000/canvas](http://localhost:8000/canvas). Reuse `openhands-state` to retain state across container removals. A fresh volume does not contain existing `~/.openhands` data; inspect or back it up with `docker volume inspect openhands-state`.
Linux permission troubleshooting and existing state If startup reports `Permission denied`, check access to the path named in the error. On SELinux hosts, check whether the bind mount needs a `:z` or `:Z` label. If you bind-mount existing `~/.openhands` state instead of the named volume, uid 10001 needs access to its directories, existing key files and automation database. Grant access using ownership or ACLs while keeping keys private. Making state directories writable by all users can let another local user replace the session key; do not use recursive world-writable permissions there. Keep the default container user. An override can make the browser configuration directory inaccessible. If you override the user, configure a writable `XDG_CONFIG_HOME` and ensure state and workspace mounts are accessible.
> [!NOTE] > The entrypoint stops the container with exit code 1 when the Agent Server stops answering > its `/alive` check for about 30 seconds, so a crash or hang fails visibly instead of leaving > a container that returns 502 for every request. > Automatic recovery needs a restart policy: use `--restart unless-stopped` instead of > `--rm`, or `restart: unless-stopped` in Docker Compose. The agent will be able to access any project under `PROJECTS_PATH`. ### Option 3: With Multiple Docker Sandboxes Run each new conversation in its own Docker container, with its own Agent Server and tools. This is useful for running several agents concurrently. Canvas and the outer Agent Server run on your host and route conversation requests to the containers. **Prerequisites**: Node.js 24 or later, `uv`, and a running Docker Desktop (macOS) or Docker Engine/Desktop (Linux). The user starting Canvas must be able to run `docker` commands. **macOS / Linux:** ```sh npm install -g @openhands/agent-canvas OH_CONVERSATION_RUNTIME=docker agent-canvas ``` Open [http://localhost:8000](http://localhost:8000) and start a new conversation. Existing local conversations are not converted. Each container mounts its conversation's workspace and persisted state, so workspace files and conversation history survive container replacement. Conversations using the same host workspace still share those files; choose separate directories or worktrees to avoid conflicting edits. This setting isolates conversation execution; it does not move the entire Canvas or automation service into a sandbox. For Windows, see [README.windows.md](./README.windows.md#option-3-with-multiple-docker-sandboxes-wsl-2). ### Option 4: 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](https://nodejs.org/) 24 or later, npm 11.12.1 (the repository pin), `uv` (for running the agent server via `uvx`) Check `npm --version` before resolving dependencies. The seven-day release-age filter (`npm install --min-release-age=7`) requires npm >=11.10; older versions do not enforce it. Use `npm ci` to replay the committed lockfile. This npm requirement is for contributor dependency resolution, not for installing the published Canvas package. ```sh git clone https://github.com/OpenHands/OpenHands.git cd OpenHands npm ci npm run dev ``` --- Access the UI at [http://localhost:8000](http://localhost:8000) for the npm/source launchers, or [http://localhost:8000/canvas](http://localhost:8000/canvas) for the Docker image. You can add additional backends directly from the UI. Local (`npx` / `npm run dev`) listeners bind **loopback only** (`127.0.0.1`) so the auto-injected session key is not reachable from other machines on the network. To listen on all interfaces, pass `--host 0.0.0.0` (or set `OH_BIND_HOST`); the session key is then **not** injected and the UI uses the same API-key entry screen as `--public`. Docker listens on all container interfaces so port publishing works, but does not inject its session key into HTML by default. The quickstart above explicitly enables injection while publishing the host port on `127.0.0.1` only. If you publish Docker on a LAN or public interface, omit `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY` and enter the API key in the UI. Set `LOCAL_BACKEND_API_KEY` to a strong value, or retrieve the generated value with `docker exec sh -c 'cat "$STATE_DIR/api-key.txt"'`. For internet-facing installs, follow [self-hosting](./docs/SELF_HOSTING.md). # 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. image ### Repository boundaries Agent Canvas is part of a multi-repository OpenHands system. Changes should go to the repository that owns the behavior: | Repository | Responsibility | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) | Agent Canvas frontend, user-facing control center, backend selection, and local-stack orchestration. | | [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) | Python SDK, Agent Server, agents, tools, conversations, workspaces, events, and the canonical server API. | | [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) | Browser-compatible TypeScript client for the Agent Server API. | | [`OpenHands/automation`](https://github.com/OpenHands/automation) | Automation definitions, scheduling, webhooks, run history, and dispatching. | The Agent Server API is implemented by the SDK and consumed through the TypeScript client by Agent Canvas. The automation service decides when work runs and dispatches conversations to the Agent Server/SDK, which decides what runs. See [`AGENTS.md`](./AGENTS.md) for contributor-specific boundaries and the required custom code-review guide. ## More documentation - [Documentation index](./docs/README.md) - [Architecture overview](./docs/architecture.md) - [Development guide](./docs/DEVELOPMENT.md), including [embedding Canvas components in a host app](./docs/DEVELOPMENT.md#css-isolation-and-host-app-customization) (load `@openhands/agent-canvas/styles.css` once next to the component imports) - [Self-hosting guide](./docs/SELF_HOSTING.md)