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
- A machine on your LAN with Docker installed (Docker Desktop on macOS, Docker Engine on Linux).
- Node.js 24 or later (for the Canvas frontend if running from npm; Docker image handles this).
- A directory on the host to hold project folders the agent can access.
- A strong API key or session key for authentication (Canvas generates one automatically).
Option 1: Docker Single Sandbox (Recommended for Most Setups)
This approach runs the full Agent Canvas stack in a single container with isolated workspace access.
- 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.
- 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.
-
Open your browser to
http://localhost:8000/canvas(or the machine’s LAN IP if accessing from another device on your network). -
The agent will have read/write access to everything under
/projectsinside 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.
- Install the Canvas CLI globally:
npm install -g @openhands/agent-canvas
- Start Canvas with Docker conversation runtime:
OH_CONVERSATION_RUNTIME=docker agent-canvas
- Open
http://localhost:8000and 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:
- Clone the repository:
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
- Install dependencies:
npm install
- 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.
- 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.1by 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_KEYand setLOCAL_BACKEND_API_KEYto 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.
Gear used in this build
* Affiliate links — I earn a small commission at no cost to you.It's gear I use and would genuinely recommend. As an Amazon Associate I earn from qualifying purchases. See the full disclosure.
Related video
New self-hosted AI & homelab shorts, daily.
Subscribe on YouTubeRelated guides
Run Local AI on Old NVIDIA/AMD GPUs with Ollama
Dust off that graphics card and run Llama, Gemma, Qwen locally with Ollama. Pick a model that fits your VRAM, skip the hype.
Run AI Models on PS5 with llama.cpp GGUF
Turn your PlayStation 5 into a local AI inference engine using llama.cpp's native GGUF support. Run Llama, Qwen, and other quantized models directly on console hardware for private, offline inference.
Run MiniMax H3 in ComfyUI: Local Audio & 2K Video
Generate audio and 2K video together on your own hardware using MiniMax H3 in ComfyUI. No API costs, full control, offline workflows.