jamilxt

Posted on Sep 10

OpenHands Agent Canvas: Self-Hosting an Army of AI Coding Agents

#opensource #devtools #automation #ai

OpenHands Agent Canvas turns your laptop or VPS into a control center for AI coding agents that run whether you are watching or not. It is free, open source, and self-hosted. You install it, connect the agent you already use, and wire up automations that review pull requests, watch repositories, and post to Slack while you do something harder. This guide walks through the real setup, the eight features that make it interesting, and the fine print the landing page leaves out.

What Agent Canvas Actually Is

OpenHands started as an autonomous coding agent and hit 1.0 in December 2025 on a rewritten Software Agent SDK. Agent Canvas is the newer layer on top: a visual workspace where agents become always-on workers instead of one-off chat sessions. The team describes it as going from prompting to process, and the description holds up when you read the docs.

The core idea is a command center. You self-host a backend on your laptop, a VM, or a VPS, and agents run there continuously in the background. Open a GitHub issue and let the agent work it. Point it at a repository and it reacts to events. Schedule it to summarize yesterday's pull requests every weekday at 9 AM.

One important correction to the pitch you may have seen: Agent Canvas does not replace Claude Code or Codex. It connects to them. The whole architecture rides on the Agent Client Protocol (ACP), an open JSON-RPC standard, so you can drive Claude Code, Codex, Gemini CLI, or the OpenHands agent from the same interface while keeping your existing subscriptions. The official page lists all three as supported alongside the OpenHands agent. That is a different, and more honest, selling point: one cockpit for every agent you already pay for, plus a free open agent if you want one.

Setup: Four Steps, Then a Fifth That Matters

Install needs Node.js and uv. The npm path is:

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

If you prefer containers:

mkdir -p ~/projects ~/.openhands

docker run -it --rm \
  -p 8000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

The Docker image serves the UI at http://localhost:8000, and the agent can only touch files under the mounted /projects directory. Note the shift here: earlier OpenHands versions required Docker for everything. Now Docker is optional. The local agent-server runs directly on your machine by default, which is faster to set up and easier to debug, but the container is what gives you a security boundary. The docs say it plainly: the Canvas client provides no isolation, and if the backend runs on your machine, the agent acts with your user permissions.

A four-step wizard handles first-time setup:

Choose your agent. OpenHands by default, or Claude Code, Codex, or Gemini CLI through ACP with your existing subscription.
Check your backend. Local at 127.0.0.1:8000 by default; you can add VMs or OpenHands Cloud later.
Set up your LLM. Bring your own key from Anthropic, OpenAI, Google, or others, or use an OpenHands Cloud API key.
Start from a proven workflow. Templates like the GitHub PR Review Copilot, a repository monitor, and a Slack standup digest come pre-built.

The fifth step is the one that matters: open a workspace folder before your first real conversation. Blast radius discipline starts here, not after something goes wrong.

If you want the agents powered by local models, the docs cover Ollama, LM Studio, vLLM, and SGLang. Be realistic about hardware: the currently recommended open model for agentic coding, Qwen3.6-35B-A3B, wants a GPU with 24 GB of VRAM or an Apple Silicon Mac with 64 GB of unified memory. Smaller models work but degrade the agent's judgment, and weak judgment in an autonomous agent is a security problem, not just a quality problem.

The Eight Features Worth Knowing

1. Plugins and the plugin catalog

Plugins bundle skills, MCP servers, hooks, commands, and agent definitions into installable packages. The Plugins page lets you browse the catalog, inspect contents down to individual files, install, enable, disable, and uninstall. Enabled plugins load automatically into new conversations; you can also attach specific plugins opt-in per conversation. Local plugins discovered from ~/.agents/plugins or ~/.openhands/plugins show as read-only. One caveat: full marketplace-style management is positioned as an Enterprise feature, so solo self-hosters get the catalog but not the org-wide governance.

2. Fork a conversation from any message

Conversation.fork() deep-copies events, agent config, and workspace state into a new conversation. The original stays untouched, which preserves your audit trail. The docs' own use cases are good: debug a bad patch without losing the original run, A/B test by forking and changing one variable, or fork mid-conversation and swap in a different agent or model. Cost metrics start fresh on the fork by default, which makes A/B cost comparisons clean.

3. Automations that export as JSON

This is the feature that makes agent workflows feel like code instead of UI config. Any automation exports as a versioned JSON file:

{
  "version": 1,
  "kind": "automation",
  "spec": {
    "name": "Daily GitHub Summary",
    "trigger": {
      "type": "schedule",
      "schedule": "0 9 * * 1-5",
      "timezone": "America/New_York"
    },
    "enabled": true,
    "prompt": "Summarize the previous day's PRs and post to #engineering.",
    "model": "anthropic/claude-sonnet-4-5"
  }
}

You can hand-author these, diff them, keep them in version control, and import them anywhere. "I built an automation, here is the JSON, run it yourself" is now a real workflow.

4. Debugging failed automations

Automation runs have real statuses: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, SKIPPED. A failed run keeps its last phase visible, and every run's full conversation is saved for review. The recursive trick Owen flagged is real: when an automation fails, you can hand the failed run's saved conversation to a fresh agent session and ask it to investigate the failure. The agent debugging the agent. Whether that is productivity or recursion for its own sake depends on your failure rate, but the plumbing exists and it is demoable.

5. Commit history and per-commit diffs in the UI

Version 1.15 added an overview panel and a unified commits drawer to conversations. You see what the agent actually changed, commit by commit, like reviewing a colleague's PR instead of trusting a chat transcript. For anyone who has accepted an agent's output without inspecting the diff: this is the feature that makes inspection the default.

6. The /goal command and goal completion loops

A plain agent run stops when the agent thinks it is done. The goal loop is stricter: a second judge LLM audits the transcript after each run for hard evidence, file contents, command output, passing tests, that the objective is provably complete. If evidence is missing, the loop re-prompts with the judge's feedback until the goal is genuinely done or an iteration cap hits. The canonical use is test-driven objectives: the goal is not complete because the agent claims success; it is complete when pytest actually passes. Using a separate LLM instance for the judge is the documented best practice.

7. MCP OAuth support

MCP is how agents connect to external services, and OAuth support removes the API-key awkwardness for services like Notion that require it. OpenHands implements OAuth-based MCP servers through FastMCP: on first use of an OAuth-protected server, the connection flow initiates and tokens are handled for you. Less flashy than plugins, but this is the friction that decides whether real integrations actually get wired up.

8. Parallel tool calls

The SDK can execute multiple tool calls from a single LLM response concurrently, controlled by a tool_concurrency_limit on the agent. Reading five files at once, fanning out sub-agent delegations, running independent API calls in parallel. Two honesty notes from the docs: the feature is explicitly marked experimental, and the default is sequential (limit = 1) because concurrency can cause race conditions in tools that share state. The docs suggest starting at 4 and going higher only for I/O-heavy workloads. Powerful, but treat the default as a warning label, not an oversight.

The Automations You Actually Start With

Three pre-built automations ship with the product:

GitHub PR Review Assistant reviews pull requests and posts feedback as comments. This is the recommended first automation, and it runs locally through your GitHub MCP connection.
GitHub Repository Monitor watches for events, @OpenHands mentions, failed CI runs, new issues, and triggers agent responses.
Slack Channel Monitor triggers an agent when a message matches a pattern.

Creating your own is meant to be conversational: you literally ask OpenHands to create an automation, and a guided flow collects the name, schedule, timezone, and task description. Automations come in two main forms: prompt-based (natural language, the most common) and plugin-based, which pull extra capabilities from the OpenHands extensions repository. Some catalog entries go further and ship a script bundle: deterministic code that handles polling, dedup, and fixed API calls, with the agent used only where judgment is actually needed. That is a smart design. Not every cron job needs an LLM deciding what to do.

The Fine Print

A few things the 30-second pitch glosses over:

GitHub event automations have real setup requirements. The docs are blunt that a missing step makes automations appear to work while GitHub events silently never arrive. For organization repos you need the GitHub App installed, an OpenHands team organization, and a claimed GitHub org. Schedule-based automations avoid all of this.
Local LLMs are supported but demanding. The hardware bar for good agent judgment is 24 GB VRAM or 64 GB unified memory. Below that, you are trading capability for cost in an agent that acts autonomously.
Parallel tools are experimental. The default is off. That is deliberate.
Some docs pages still reference the deprecated CLI. The ACP/IDE integration docs point at the OpenHands CLI repo, which the team has marked as unmaintained. The docs are mid-migration; when a page conflicts with the product page, trust the product page.
"Free" means the harness. Agent Canvas and the agent are MIT-licensed and free. Model costs are not. Claude Code through your subscription, API keys, or local GPU electricity are all still on your bill.

Who This Is For

If you already pay for Claude Code or Codex and want them running scheduled, event-driven workflows from one interface, Agent Canvas is genuinely compelling, and it costs nothing extra to try. If you want a fully open stack, the OpenHands agent with your own API keys or local models works without any proprietary dependency. If you are running an unattended agent anywhere, apply the same discipline as any other autonomous system: mount only what it needs, use a container for the boundary, and read the commit drawer before you merge. The tool is ready for that workflow. Your configuration is the part that decides whether it stays safe.

DEV Community