OpenHands Docker Install: 5-Minute Setup Guide (2026)

Wondering how to get an OpenHands Docker install running without breaking anything? The quick version is just below, and the long version — exact commands, volume mounts, LLM setup and the security flags you should not skip — takes about five minutes to follow. Everything here comes straight from the official OpenHands documentation and GitHub repository as of 9 September 2026, so you are not working from stale copy-paste commands.

OpenHands Docker Install: What You Need Before You Start

First, what you are actually installing. OpenHands describes itself as “the self-hosted developer control center for coding agents and automations” — the browser interface is called Agent Canvas, it is MIT-licensed, and the project sits at over 206,000 stars on GitHub. The latest tagged release at the time of writing is v1.16.0, shipped on 27 August 2026, which added LLM provider selection, a Linux desktop installer and an explicit allow-list for skills (per the official release notes on GitHub).

Prerequisites are short:

• Docker installed and running. Docker Desktop on Mac/Windows, or the docker engine on Linux.
• An LLM API key from whichever provider you plan to use — OpenHands is bring-your-own-model via its LiteLLM integration, so most major providers work.
• A projects folder you are happy for the agent to read and write. Do not mount your entire home directory; give it a workspace.

Why Docker rather than the npm route? The official docs are refreshingly blunt: “The agent server can execute arbitrary shell commands inside the container.” That single sentence is the whole security argument. A coding agent that can run shell commands should be running them inside a disposable sandbox, exactly the same logic I walked through in my guide to self-hosted environments for coding agents.

The OpenHands Docker Install Command, Step by Step

Here is the exact sequence from the official Docker backend documentation (docs.openhands.dev, fetched 9 September 2026). On macOS or Linux:

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

Then open http://localhost:8000/canvas in your browser. That is genuinely the whole install. On Windows, the same command exists in PowerShell form in the docs, with $env:USERPROFILE paths instead of ~.

What each piece does, so you are not pasting blind:

Two optional environment variables worth knowing from the docs: LOCAL_BACKEND_API_KEY (server API key, auto-generated if you omit it) and OH_SECRET_KEY (protects stored credentials). And if you want the agent itself to build and run containers, the docs say to add --privileged for Docker-in-Docker — with the explicit warning that this requires caution. My advice: leave it off until a real task forces the issue.

Connecting a Model Once the Container Is Running

Once the canvas loads at localhost:8000/canvas, the first-time setup asks you to choose your agent and connect a backend. The LLM settings page is where you paste your provider API key — the docs describe “LLM profiles for switching models”, which is genuinely useful: you can keep a cheap model profile for routine tasks and a frontier model profile for the hard stuff, and switch between them per conversation.

Three configurations that make sense in practice:

• Hosted frontier model. Best output quality, costs per token. This is the default choice if you are using the agent for client work.
• Local model. If you already run models locally, OpenHands will talk to a local endpoint — the same pattern I covered for running Hermes Agent in Docker, where the container and the model both live on your box.
• Mixed profiles. Cheap model for automations, strong model for interactive sessions. The v1.16.0 LLM provider selection feature makes this switch a dropdown rather than a config-file edit.

Beyond one-off conversations, the README highlights automations and workflows that integrate with Slack, GitHub and Linear — which is where a self-hosted agent starts paying for itself. An agent that triages issues overnight in a sandbox you control is a very different proposition from a chat window. If you are comparing self-hosted options generally, my OpenClaw on Linux install guide covers the closest open-source alternative workflow, and it is worth reading both before you commit — the setup effort is similar but the ecosystems differ.

One honest limitation to flag: the official README and docs I fetched this week do not publish benchmark scores for the current release, so I am not going to quote any. What you can verify yourself in ten minutes is whether it handles your repo — which is the only benchmark that matters. If you want that evaluated properly against your actual SEO and content workflows, that is literally what the free strategy session is for: book a free SEO strategy session and bring your use case.

The bottom line on OpenHands Docker install

The OpenHands Docker install is about as low-friction as self-hosted agent tooling gets in September 2026: one docker run command from the official docs, one browser tab, one API key, and you have an MIT-licensed coding agent control centre running in a sandbox with your settings persisted to ~/.openhands. The things to respect are the security posture — sandboxed by design because the agent runs arbitrary shell commands, --privileged only with caution — and the discipline of mounting a dedicated projects folder rather than your whole disk. Set it up properly once and it becomes boring infrastructure, which is exactly what you want your agents to be.

FAQ: openhands docker install

Is OpenHands free to use?

The software itself is free and open source under the MIT licence, per the official GitHub repository. You still pay for whatever LLM you connect to it — API usage on your chosen provider is billed by that provider, and running a local model costs you hardware rather than tokens.

Do I need Docker to run OpenHands?

No, but it is the recommended route. The README also documents a global npm install (npm install -g @openhands/agent-canvas) with no sandbox, and a from-source option. Docker is recommended for safety because the agent server can execute arbitrary shell commands inside the container.

What port does the OpenHands Docker install use?

Port 8000 by default. The documented command maps -p 8000:8000 and you open http://localhost:8000/canvas in your browser. You can change it with the PORT environment variable.

Which LLMs work with OpenHands?

Per the official docs, OpenHands supports a wide range of LLM providers through its LiteLLM integration, with LLM profiles for switching models. It also works with OpenHands’ own agent, Claude Code, Codex, Gemini, or any agent that speaks the Agent-Client Protocol (ACP).

How do I update an OpenHands Docker install?

Because the documented command uses the :latest tag with --rm, stopping the container and re-running the same docker run command after a docker pull ghcr.io/openhands/agent-canvas:latest gets you the newest release. Your settings and history persist in the mounted ~/.openhands folder.

Can the OpenHands agent run its own containers?

Only if you enable Docker-in-Docker by adding the --privileged flag, which the official docs say requires caution. Leave it off unless your workflow genuinely needs the agent to build and run containers.

Related reading

• How to install OpenClaw on Linux
• Self-hosted environments for coding agents
• Running Hermes Agent in Docker

Last updated September 2026. This is the living guide to openhands docker install — it gets updated as the tools change.