OpenHands

Purpose

OpenHands is a self-hosted developer control center for coding agents and automation. Its Agent Canvas can turn coding agents into a self-hosted, persistent engineering team.

Main capabilities

• Can run OpenHands, and can also use third-party agents such as Claude Code, Codex, Gemini CLI, Pi, OpenCode, or any ACP-compatible agent.
• Supports switching between local, remote, and cloud backends: agents can run in Docker containers, virtual machines, or company infrastructure.
• Can optionally use OpenHands Cloud or OpenHands Enterprise infrastructure to run agents.
• Used to start conversations and automate everyday tasks, such as generating reports and posting them to Slack, or automatically breaking down GitHub issues into tasks.
• Supports triggering agents through third-party services such as Slack, GitHub, and Datadog.
• Can connect multiple Agent Servers in the same Agent Canvas frontend and switch between them. For example, a team shares one Agent Server for code review and dependency updates, while personal agents run locally.
• Can be paired with Automation Server to run agents on a schedule or in response to events.
• Agent Canvas is based on OpenHands Agent Server (a REST API for running multiple agents on a single machine), and each Agent Server runs on a single host/port.

How to use

Four installation/run methods are provided:

Option 1: No sandbox Run agent-server directly on the machine where it is installed, and the agent will have full file system access. Prerequisites: Node.js 24 or later, uv. Default command agent-canvas starts the full local stack, and the parts can also be run separately.

Option 2: Use Docker sandbox Prerequisites: Docker (Docker Desktop on macOS/Windows, Docker Engine/Docker Desktop on Linux); a host directory for PROJECTS_PATH, which contains the project folders the agent needs to access, and must be created before starting the container. The agent can access any project under PROJECTS_PATH. For the Windows equivalent command, see README.windows.md.

Option 3: Use multiple Docker sandboxes Each new conversation runs in its own Docker container, with its own Agent Server and tools, suitable for running multiple agents concurrently. Canvas and the outer Agent Server run on the 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. Visit http://localhost:8000 and start a new conversation. Existing local conversations will not be converted. Each container mounts its conversation's workspace and persistent state, so workspace files and conversation history remain after the container is replaced. Conversations that use the same host workspace still share these files; to avoid edit conflicts, choose different directories or worktrees. This setting isolates conversation execution, and does not move the entire Canvas or the automation service into the sandbox. For Windows, see README.windows.md.

Option 4: Run from source Prerequisites: Node.js 24 or later, npm, uv (used to run the agent server via uvx). For the npm/source launcher, visit the UI's http://localhost:8000；对于 Docker image, visit http://localhost:8000/canvas。可直接在 UI to add other backends.

Networking and security notes

The local (npx / npm run dev) listener binds only to the loopback address (127.0.0.1), so the automatically injected session key cannot be accessed from other machines on the network. To listen on all interfaces, pass --host 0.0.0.0 (or set OH_BIND_HOST); in that case no session key is injected, and the UI uses the same API key entry interface as --public.

The Docker listener listens on all container interfaces for port publishing, but by default does not inject the session key into the HTML. The quick start above explicitly enabled injection while publishing only the host port to 127.0.0.1. 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 via docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"' get the generated value. For internet-facing installations, follow the self-hosting guide (SELF_HOSTING.md), especially the security hardening section.

When to use

• Run the agent on your local laptop, a dedicated machine (such as a Mac Mini), or a cloud server.
• Running on a cloud server provides the strongest capabilities: even if the laptop is shut down, the agent can continue running, and it is easier to trigger the agent through third-party services such as Slack, GitHub, and Datadog.
• Teams share an Agent Server for code review and dependency updates; personal agents run locally.
• Run multiple agents concurrently (multi-Docker sandbox mode).

Limitations and boundaries

• In no-sandbox mode (Option 1), the agent has full file system access.
• Multi-Docker sandbox mode only isolates conversation execution, and does not move the entire Canvas or the automation service into the sandbox.
• Conversations that use the same host workspace share files; you need to choose different directories or worktrees to avoid edit conflicts.
• The local launcher by default listens only on the loopback address; when changed to listen on all interfaces, the session key is no longer injected.
• The Agent Server API is implemented by the SDK and consumed by Agent Canvas through a TypeScript client; the automation service decides when to run work and dispatches conversations to the Agent Server/SDK.

More documentation

The repository provides a documentation index, architecture overview, development guide, and self-hosting guide. If you have questions or feedback, you can submit an issue on GitHub or join the #proj-agent-canvas channel on Slack.