OpenHands 1.0: Install the Open Source Devin (2026 Guide)

The end state is simple: a browser tab open to http://localhost:3000, an agent panel on the left, and a chat input that turns natural-language tickets into actual code, run inside a sandboxed Docker container. That’s what you’re building today. The open source Devin people talk about is called OpenHands – version 1.0.0 shipped on 2025-12-16, rebuilt on a new software-agent-sdk.

This guide walks the install backwards from that running browser tab. Start with what you need, then the recommended uv path, then Docker as a fallback. The whole thing takes about fifteen minutes if nothing goes sideways – and a section below covers the three things that usually do.

Architecture first, marketing second

OpenHands (formerly OpenDevin) is MIT-licensed – except the enterprise/ directory. The architecture is what matters here: instead of just generating text, the agent runs commands inside a Docker sandbox, observes the output, and iterates. That loop is formalized in the OpenHands Software Agent SDK paper (arXiv:2511.03690) by Wang et al. As of late 2025, it resolves over 50% of real GitHub issues on SWE-Bench Verified – the strongest open-source benchmark score in that category.

One thing the marketing buries: this is not a local-model project. OpenHands needs a model that handles long context and structured tool calls – smaller local models stall mid-task or loop on errors. Plan to wire it to Claude or GPT-class APIs. Cost adds up faster than you’d expect on a multi-step debugging session.

System requirements

The official floor is 4GB RAM. In practice, 8GB is where it stops crawling once Docker, your editor, and a sandbox container are all alive simultaneously.

The Python constraint: Python ==3.12.*, pinned, not a suggestion. Try 3.11 or 3.13 and you’ll see a missing-wheels error – which sends most people down a useless rabbit hole. The actual problem is the version mismatch. uv 0.11.6 or newer is also required, per the PyPI package metadata.

Install with uv (recommended path)

The team’s official recommendation is uv. It isolates OpenHands from whatever Python version is already on your system – and unlike a plain pip install, it correctly pins Python 3.12 at install time.

# Install OpenHands as a uv tool, pinned to Python 3.12
uv tool install openhands --python 3.12

# Launch the local GUI server
openhands serve

# Mount your current project directory into the sandbox
openhands serve --mount-cwd

# Enable GPU passthrough (requires nvidia-docker)
openhands serve --gpu

First launch pulls the agent-server image automatically – Docker requirements, image pull, GUI startup, all handled. Expect a minute or two on a fresh machine. The flags (--mount-cwd, --gpu) are documented in the official local-setup guide; check there if your Docker setup is non-standard.

If pip is your religion: pip install openhands followed by openhands serve works too. But you still need uv installed on the system. There’s no escaping it.

Docker-only install

No Python on host at all? Run it inside WSL on Windows – not PowerShell.

docker run -it --rm --pull=always 
 -v /var/run/docker.sock:/var/run/docker.sock 
 -v ~/.openhands:/.openhands 
 -p 3000:3000 
 --add-host host.docker.internal:host-gateway 
 --name openhands-app 
 docker.openhands.dev/openhands/openhands:1.7

Check the official local-setup docs for the current image tag – it updates with each release, and running an old tag against a new API key can produce confusing failures.

The -v /var/run/docker.sock:/var/run/docker.sock line looks odd – Docker inside Docker? – but skipping it is the #1 reason new installs “work” but tasks fail silently. The GUI loads. You type a task. Nothing happens. The sandbox container can’t spawn without socket access. Add the volume mount and restart.

Before saving your API key in settings: decide whether you want the agent to ask for approval before every action or run unattended. The default (interactive mode) asks. --always-approve removes friction and removes safeguards. Pick deliberately.

First-time configuration

Open http://localhost:3000. A settings dialog appears on first launch. Pick your provider (Anthropic or OpenAI), pick a model (Claude Sonnet-class or GPT-4o-class – anything weaker and multi-step tasks stall), paste your key. Configuration lives under ~/.openhands/ locally – agent_settings.json, cli_config.json, mcp.json – not in any cloud config.

To verify end-to-end, give it a small but checkable task:

1. Chat input: “Create a file called hello.py that prints the current date in ISO format. Run it and confirm the output.”
2. Watch the agent panel – plan → execute → observe steps run in real time.
3. Terminal check: ls -la ~/.openhands/workspace/ should show hello.py.
4. Version check: openhands --version.

Green checkmark in the panel, file on disk. That’s the install done.

Three errors that eat afternoons

These live at the edges of the docs. Know them before they find you.

1. Files in /mnt/c on WSL. Clone OpenHands or your project into /mnt/c/Users/... and the agent’s file-edit loop becomes noticeably slower – every file read crosses the WSL→Windows filesystem boundary, which costs a syscall penalty each time. Per the official Development.md: keep project files in the WSL filesystem (e.g., ~/workspace/openhands). Move the directory. Don’t try to optimize around it.

2. Pip install “missing wheel” on Python 3.11. The package is pinned to Python ==3.12.*. On 3.11, pip throws an opaque wheel error instead of a clear version message. Fix: use uvx --python 3.12 --from openhands openhands, or install Python 3.12 explicitly first. Don’t chase the wheel error itself.

3. Docker socket not mounted. Covered above – tasks load but never execute. Add -v /var/run/docker.sock:/var/run/docker.sock and restart the container. This one trips up even people who’ve run Docker for years.

Upgrading and uninstalling

One line with uv: uv tool upgrade openhands --python 3.12. For Docker, pull the new tag and re-run. The 1.0.0 release was a major rebuild – it introduced the new software-agent-sdk – so read the release notes before upgrading a setup you care about. Configuration paths can shift between major versions.

Full removal: uv tool uninstall openhands, then delete ~/.openhands/ for config and ~/.openhands/workspace/ for agent-created files. Docker installs: docker rm -f openhands-app and remove the image. The sandbox images pulled at runtime live under ghcr.io/openhands/agent-server – clean those too if you’re reclaiming disk.

FAQ

Can I run OpenHands with a fully local LLM like Llama or Mistral?

Technically yes. In practice, no – the agent loop assumes long-context structured tool calls, and smaller models stall or loop. Use a Claude or GPT-4o-class API.

How is the main OpenHands repo different from the OpenHands CLI repo?

They split into separate repos. The main OpenHands repo is where active feature work happens – GUI, agent improvements, new integrations. The CLI repo is its own project now, with configuration stored under ~/.openhands/. Pick the main project if you want the latest agent capabilities; pick the CLI if you want a stable terminal experience. Just don’t assume they’re the same codebase anymore.

Is headless mode safe to point at a real production repo?

No. Headless mode always runs in always-approve mode – that can’t be changed, and --llm-approve is unavailable in headless. The agent will execute whatever it decides without asking. If you’re running it in CI, point it at a branch with a scoped checkout. Never against your main working tree.

Next: open http://localhost:3000, paste an API key, and ask the agent to write a README for a project you already have. That single round-trip tells you more about whether OpenHands fits your workflow than any benchmark number.