aihomelabprivacy

Run OpenHands Agent Canvas on Your Own Hardware

🤖 Researched and drafted automatically from the official docs, and reviewed before publishing. Commands are taken from the source projects — but always sanity-check before running anything on your own hardware.

OpenHands Agent Canvas is a self-hosted developer control center for running coding agents on your own hardware. Instead of paying per-use cloud compute, you deploy it once on a server you control—a Mac Mini, a Linux box, or any machine with Docker—and get an always-on agent that can automate code review, decompose GitHub issues, generate reports to Slack, and more. This guide walks you through deploying it with Docker isolation on your LAN.

Prerequisites

  1. A machine on your LAN with Docker installed (Docker Desktop on macOS, Docker Engine on Linux).
  2. Node.js 24 or later (for the Canvas frontend if running from npm; Docker image handles this).
  3. A directory on the host to hold project folders the agent can access.
  4. A strong API key or session key for authentication (Canvas generates one automatically).

This approach runs the full Agent Canvas stack in a single container with isolated workspace access.

  1. Create a project directory on your host:
mkdir -p $HOME/projects $HOME/.openhands

Place any project folders you want the agent to work with under $HOME/projects.

  1. Start the container:
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 "$HOME/projects:/projects" \
  ghcr.io/openhands/agent-canvas:1.26.0

The container binds to 127.0.0.1:8000 only—accessible from your LAN machines but not the public internet.

  1. Open your browser to http://localhost:8000/canvas (or the machine’s LAN IP if accessing from another device on your network).

  2. The agent will have read/write access to everything under /projects inside the container.

Option 2: Multiple Docker Sandboxes (For Concurrent Agents)

Each conversation runs in its own isolated container, useful if you want to run multiple agents in parallel without interference.

  1. Install the Canvas CLI globally:
npm install -g @openhands/agent-canvas
  1. Start Canvas with Docker conversation runtime:
OH_CONVERSATION_RUNTIME=docker agent-canvas
  1. Open http://localhost:8000 and create new conversations. Each one spawns its own container with its own workspace.

Option 3: From Source (Development / Advanced)

For running the latest code or contributing changes:

  1. Clone the repository:
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
  1. Install dependencies:
npm install
  1. Start the dev server:
npm run dev

This runs the full stack locally (not sandboxed), so the agent has direct filesystem access. Use only on a trusted machine.

  1. Access the UI at http://localhost:8000.

Network Security

  • Keep it on the LAN or behind a VPN. The quickstart commands bind to 127.0.0.1 by default, making Canvas inaccessible from the public internet. If you need remote access, use a VPN tunnel (WireGuard, Tailscale) rather than exposing the port directly.
  • If you do publish Docker to a LAN interface, omit AGENT_CANVAS_ALLOW_LAN_SESSION_KEY and set LOCAL_BACKEND_API_KEY to a strong value, or retrieve the auto-generated key from the container state.
  • For internet-facing deployments, read the self-hosting docs for hardening guidance.

Connecting Additional Backends

Agent Canvas can manage agents running on multiple machines. From the UI, you can add remote Agent Servers running on VMs, other machines on your LAN, or cloud instances. This lets you keep a personal agent on your laptop while sharing a team agent on a dedicated server.

Configuring Your LLM

By default, Canvas uses the OpenHands agent. You can swap in Claude Code, Gemini, or any agent supporting the Agent-Client Protocol (ACP). Set your LLM API keys in the Canvas settings—the UI prompts you on first run. Store keys in environment variables or use Canvas’s built-in secrets manager to avoid hardcoding them.

Is It Worth It?

Yes, if you run agents regularly. A $200–400 Mac Mini or a $100–150 used mini-PC will pay for itself in a few months versus cloud per-minute billing. You get always-on automation (scheduled reports, GitHub event triggers), full data privacy (everything stays on your hardware), and no cold-start latency. The trade-off: you own the uptime and maintenance. Docker isolation handles most safety concerns, but keep the machine and its network access secured. For a homelab or small team, this is the right call.

Related guides

← All guides