Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Self-host OpenHands
updated Sep 2026deployed by usprices checked · Jul 2026Install verified on Ubuntu 26.04 · Nov 2026 · how we test
We earn commissions when you shop through the links below. Full disclosure →
A self-hosted control center for AI coding agents: describe a task in natural language and OpenHands writes code, runs commands, and iterates on its own. It ships as Agent Canvas, an npx-installable web UI that runs its own agent or third-party agents (Claude Code, Codex, and other Agent-Client-Protocol-compatible agents), and you bring your own LLM API key (Anthropic, OpenAI, or a self-hosted OpenAI-compatible endpoint).
Pick OpenHands when you want a browser control centre for coding agents on your own VM: Agent Canvas is MIT-licensed, installed with `npx @openhands/agent-canvas`, and runs the OpenHands agent or ACP agents (Claude Code, Codex, Gemini CLI) against models you pay for yourself — direct Anthropic, OpenAI or Google keys, an OpenHands LLM key, or a local OpenAI-compatible server such as Ollama. The moving parts are Node.js, `uv` for the Python agent-server runtime and an API key you generate; upstream says "2 vCPU / 4 GB RAM is plenty for a single user". If you want a multi-agent platform with identity, audit trails and durable workflows rather than one developer's agent, AgentArea is the fit.
Paid link — we earn a commission if you shop through it.
Install
Run these commands on your server:
# OpenHands Agent Canvas — official npx installer + systemd (docs/SELF_HOSTING.md). Node.js 24 + uv:sudo apt-get update && sudo apt-get install -y curl gitcurl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejscurl -LsSf https://astral.sh/uv/install.sh | sh # agent-server runtime, installs to ~/.local/binexport LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32) && echo "$LOCAL_BACKEND_API_KEY" # save this value# keep the key out of the 0644 unit file: a root-only env file that systemd reads at startsudo install -m 600 -o root -g root /dev/null /etc/agent-canvas.envecho "LOCAL_BACKEND_API_KEY=$LOCAL_BACKEND_API_KEY" | sudo tee /etc/agent-canvas.env >/dev/null# the upstream systemd unit, with your user and PATH so the service finds uvsudo tee /etc/systemd/system/agent-canvas.service >/dev/null <<EOF[Unit]Description=Agent CanvasAfter=network.target[Service]User=$USEREnvironment=PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/binEnvironmentFile=/etc/agent-canvas.envExecStart=/usr/bin/npx --yes @openhands/agent-canvas --publicRestart=on-failureRestartSec=5[Install]WantedBy=multi-user.targetEOFsudo systemctl daemon-reload && sudo systemctl enable --now agent-canvas# the first start downloads the agent server and frontend — about 3 minutes before :8000 answers# native Node process, not a container — so no idle-RAM reading here (our harness measures Docker only)# the ingress binds http://127.0.0.1:8000 only — keep it firewalled; reach it over an SSH tunnel# or front :8000 with nginx + Let's Encrypt, then paste LOCAL_BACKEND_API_KEY when prompted
OpenHands reorganised itself in 2026 and its self-hosting guide is blunt about what the agent can reach:
non-negotiableThe agent server can read and write the filesystem, execute commands and reach the network, and "Anyone who can talk to the agent server can do the same." The npm/npx path runs it directly on the host — the README warns "the agent will have full access to your filesystem!" — so the guide's firewall step (inbound 22 restricted to your IP, 80 open for certificates, 443 restricted to your IP or VPN if you can, "Everything else — drop") and LOCAL_BACKEND_API_KEY are all that stands between a stranger and your VM.
non-negotiableGenerate the key with openssl rand -base64 32 and export LOCAL_BACKEND_API_KEY=<key>; with --public it is "not baked into the frontend", every /api/* call must carry a matching X-Session-API-Key header, and users must enter it before the UI works. All services bind to 127.0.0.1 (ingress on :8000), so remote access is either an SSH tunnel or the guide's optional nginx + certbot front end on 80/443.
non-negotiableDocker is a documented option, not the default: the README's Option 2 runs ghcr.io/openhands/agent-canvas:1.20.0 on port 8000 with ~/.openhands and a PROJECTS_PATH mounted, which sandboxes the agent instead of handing it the host. The older "OpenHands GUI" image (docker.openhands.dev/openhands/openhands, port 3000, docker.sock mount) is what the docs index now calls "the deprecated Docker-based browser application from the former OpenHands monorepo", even though its own setup page still documents it without a notice — know which of the two you are following.
non-negotiableNode versions disagree upstream as of September 2026: the README says Node.js 22.12.x or later and the self-hosting guide says 22.x, but the published @openhands/agent-canvas 1.20.0 declares engines.node >=24. Our snippet installs Node 22 from NodeSource; if npx refuses to run, install Node 24. The repository also moved from All-Hands-AI/OpenHands to OpenHands/OpenHands — GitHub redirects the old URL.
non-negotiableThere is no bundled model: access is a direct provider API key, an OpenHands LLM key, an ACP agent's own subscription, or a local OpenAI-compatible server, and every option except local is metered by that provider on top of the VPS. The 4 GB floor is upstream's figure — "2 vCPU / 4 GB RAM is plenty for a single user" in the self-hosting guide, and "a minimum of 4GB RAM is recommended" in the docs.