Skip to content
Get packs

Guide · Open source

How to use OpenHands: install Agent Canvas and run coding agents

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenHands (the project now presents itself as Agent Canvas) is a self-hosted control center for AI coding agents. It lets you start conversations with agents and set up automations, such as generating reports that publish to Slack or breaking GitHub issues into tasks. This guide walks through the install options in the README, how to choose between them, and what you can do once it is running.

OpenHandsOpenHands/OpenHands · ★ 92.5k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Node.js 24 or later and uv. Add Docker if you want a sandboxed option.
  2. 2Pick an install option. Use the npm install for a quick local start, or a Docker option if you want isolation.
  3. 3Install the package. Run npm install -g @openhands/agent-canvas.
  4. 4Start Agent Canvas. Run agent-canvas to start the full local stack.
  5. 5Open the interface and start a conversation. Open the local address the command prints, or http://localhost:8000 for Docker setups, and start a new conversation.
  6. 6Connect a model and tools. Choose your LLM through the settings and add third-party agents or integrations as needed.

What OpenHands (Agent Canvas) does

OpenHands Agent Canvas is a developer control center. You use it to start conversations with agents and to automate everyday tasks. It runs locally on your machine by default.

It can also connect to multiple agent backends, such as agents running in Docker containers, on VMs, or inside your company infrastructure. You can optionally run agents on OpenHands Cloud or OpenHands Enterprise infrastructure.

  • Run the open source OpenHands agent out of the box.
  • Use third-party agents such as Claude Code, Codex, Gemini CLI, Pi, and OpenCode, or any agent that supports the Agent-Client Protocol (ACP).
  • Bring your own LLM through LLM profiles.

Install OpenHands with npm (no sandbox)

The quickest route is the npm package. Check the prerequisites first: Node.js 24 or later and uv. Note that this option runs the agent-server directly on your machine, so the agent has full access to your filesystem.

  • Prerequisites: Node.js 24 or later, uv.
  • The README lists this as Option 1: Without a Sandbox.
npm install -g @openhands/agent-canvas agent-canvas

Run with a Docker sandbox for safer access

If you want the agent to work inside a container, use the Docker sandbox option. You need Docker (Docker Desktop on macOS or Windows, or Docker Engine or Docker Desktop on Linux) and a host directory for PROJECTS_PATH that holds the project folders the agent may access. Create that directory before starting the container.

The README gives separate commands for macOS and Linux. For Windows, it points to README.windows.md.

  • Set PROJECTS_PATH to the folder that contains your projects.
  • The agent can access any project under PROJECTS_PATH.
  • Open the web interface on port 8000 once the container is running.
export PROJECTS_PATH="$HOME/projects" mkdir -p "$PROJECTS_PATH" "$HOME/.openhands" docker run -it --rm \ -p 127.0.0.1:8000:8000 \ -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \ -v "$HOME/.openhands:/home/openhands/.openhands" \ -v "${PROJECTS_PATH}:/projects" \ ghcr.io/openhands/agent-canvas:1.34.0

Run each conversation in its own Docker container

For several agents running at once, set OH_CONVERSATION_RUNTIME=docker. Each new conversation then gets its own container with its own Agent Server and tools. Canvas and the outer Agent Server still run on your host and route requests to the containers.

Existing local conversations are not converted. Conversations that use the same host workspace share its files, so use separate directories or worktrees to avoid conflicting edits. The README notes this setting isolates conversation execution only; it does not move all of Canvas or the automation service into a sandbox.

  • Prerequisites: Node.js 24 or later, uv, and a running Docker Desktop or Docker Engine, with permission to run docker commands.
  • Open http://localhost:8000 and start a new conversation.
npm install -g @openhands/agent-canvas OH_CONVERSATION_RUNTIME=docker agent-canvas

Use split mode and shared backends

You can run the pieces separately. The frontend-only mode serves the static frontend and ingress. The backend-only mode runs the agent server, automation backend, and ingress.

The README suggests running a shared Agent Server for a team, for tasks like code review and dependency updates, while personal agents run on your laptop. Backends are selected from the same frontend.

  • Use --frontend-only for the static frontend and ingress only.
  • Use --backend-only for the agent server, automation backend, and ingress.
  • Read the docs pages on backends and self-hosting for security hardening.
agent-canvas --frontend-only agent-canvas --backend-only

Set up automations with Slack, GitHub or Linear

Automations are workflows that run on a schedule or in response to webhook events. The README lists integrations with Slack, GitHub, Linear, Notion, and other services. Examples include reports that publish to Slack and breaking GitHub issues into tasks.

Full setup steps for automations are in the project documentation, which the README links under Automations.

  • Schedule an automation or trigger it from a webhook event.
  • Connect it to Slack, GitHub, Linear, or Notion.
  • Ask with questions in the #proj-agent-canvas Slack channel or a GitHub issue.

What people use it for

  • Run a coding agent on a server so work continues when your laptop is off.
  • Share an agent server with a team for code review and dependency updates.
  • Post scheduled reports to Slack.
  • Break GitHub issues into tasks with an automation.
  • Run several agents concurrently, each in its own Docker container.

Frequently asked questions

Is OpenHands free?

OpenHands is released under the MIT licence, and the repository is open source. The README does not list pricing for OpenHands Cloud or Enterprise, so check those services directly.

What do I need to install OpenHands?

You need Node.js 24 or later and uv for the npm install. Docker is optional and only needed for the sandboxed options.

Is OpenHands safe to run on my laptop?

The npm option without a sandbox runs the agent-server directly on your machine, and the agent has full access to your filesystem. For stronger isolation, use the Docker sandbox or per-conversation Docker containers, which the README describes.

Can I use my own LLM with OpenHands?

Yes. The README says you can bring your own model and use it with any LLM, and it links to LLM settings and LLM profiles in the documentation.

How is OpenHands different from Claude Code or Aider?

OpenHands Agent Canvas is a control center that can run its own agent and third-party agents such as Claude Code, Codex, and Gemini CLI. Claude Code is a single agent tool, while Aider and Cline are also coding agents you can compare on features. Pick based on whether you need a shared control center and automations.

Why does my Docker sandbox not show existing conversations?

The README says existing local conversations are not converted when you enable per-conversation Docker containers. Start a new conversation to use the container runtime.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenHands suits developers and teams who want self-hosted coding agents, shared agent servers, and automations wired into Slack, GitHub, or Linear, and who are comfortable with Node.js, Docker, and the command line. If you need strong isolation by default or a fully hosted service with no setup, choose a different tool or the hosted cloud option.

Install options & downloads