Install OpenHands 1.16.0 (fka OpenDevin) Guide

Most “just Docker run it” OpenHands guides are doing you a disservice. The project formerly known as OpenDevin isn’t one image and one tag anymore – it’s a CLI on PyPI, a GUI launcher that still needs Docker under the hood, an agent-server image with its own version line, and a separate Agent Canvas stack. Chase a random blog’s old docker.all-hands.dev one-liner and you’ll burn an evening on pull errors that aren’t your machine’s fault.

This guide targets OpenHands as it ships now: CLI package 1.16.0 on the official uv path, GUI on port 3000, then the first-boot failures most write-ups skip. Research backdrop lives in the OpenHands paper (arXiv:2407.16741) – agents that write code, drive a shell, and browse – but the job here is getting a clean install.

System requirements before you touch OpenHands

From the official local setup docs:

• OS: macOS + Docker Desktop; Linux (docs mention Ubuntu 22.04 testing); Windows only via WSL2 + Docker Desktop – run install commands inside the Linux distro, not native PowerShell
• CPU/RAM: modern CPU, 4GB RAM minimum for the app; give the box more headroom if you also host a local LLM
• Runtime: Docker up (Desktop or Engine); Python 3.12 for the CLI (PyPI pins ==3.12.*); uv 0.11.6+ for the recommended installer path
• Network: outbound pulls for images plus reachability to your LLM API

Mac: Docker Desktop → Settings → Advanced → enable Allow the default Docker socket to be used. Windows: WSL2 engine on, integration enabled for your Ubuntu distro. Every command below assumes that Linux shell.

Official download sources (skip random mirrors)

• Docs: docs.openhands.dev
• Site: openhands.dev
• CLI: pypi.org/project/openhands – 1.16.0 as of the May 8, 2026 PyPI release
• Repo / Agent Canvas line: github.com/OpenHands/OpenHands – GitHub latest v1.14.0 dated 2026-08-17 (not the same number as the CLI)
• Binary installer script: https://install.openhands.dev/install.sh

Still seeing All-Hands-AI or bare docker.all-hands.dev with no rename note? Treat those tags as stale until you match them to current docs.

Install OpenHands the recommended way (uv + serve)

I stopped fighting one-off docker run flags the day the docs made the CLI launcher the default. It checks Docker, pulls what it needs, starts the GUI.

1. Install uv

Use Astral’s installer for your OS, confirm uv is on PATH, and land on 0.11.6 or newer.

2. Install the CLI (1.16.0 line)

uv tool install openhands --python 3.12

pip install openhands on Python 3.12 works as a fallback. Prefer the binary script if you want to avoid managing a toolchain:

curl -fsSL https://install.openhands.dev/install.sh | sh

macOS may quarantine the binary – approve it under Privacy & Security, then rerun.

3. Launch the GUI server

# default GUI (Docker up, port 3000 free)
openhands serve

# mount current directory into the sandbox
openhands serve --mount-cwd

# GPU via nvidia-docker when you actually need it
openhands serve --gpu

Browser: http://localhost:3000.

The catch is pure Docker still exists for people who refuse the launcher.

Alternative: raw Docker GUI (docs snapshot)

Local-setup (copy live docs when tags drift) looks like this:

docker run -it --rm --pull=always 
 -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server 
 -e AGENT_SERVER_IMAGE_TAG=1.26.0-python 
 -e LOG_ALL_EVENTS=true 
 -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.8

App image :1.8 next to agent-server 1.26.0-python looks broken if you expect one semver. It isn’t a typo in your terminal – don’t “align” the numbers unless the same doc page says so.

First-time configuration (minimum to get an agent moving)

No API key, no agent. First GUI load: provider, model, key (gear icon if you closed the modal). Advanced mode accepts a custom model id and base URL – cloud providers or a local endpoint both fit; weak models still produce weak runs.

Pro tip: CLI-first path is plain openhands once for interactive LLM setup. Files land under ~/.openhands/ (settings, agent config, conversations). Coming from a CLI before 1.0.0? Redo setup – config format changed; old files won’t map quietly.

For repo work, prefer openhands serve --mount-cwd or documented SANDBOX_VOLUMES mounts. Guessing that the sandbox can see random laptop paths is how people lose an hour.

There’s a moment after the spinner dies where the UI looks ready but the agent is still useless until that key saves cleanly. If save fails, jump to permissions below before you blame the model.

Verify the install works

1. openhands -v / openhands --version – CLI version, then exit.
2. docker ps works in the same environment you’ll launch from.
3. openhands serve stays up; http://localhost:3000 loads.
4. Save LLM settings, run a trivial task (“create hello.txt with the text ping”), confirm the sandbox runs a command and the file shows in the workspace view.

Step 4 red? Runtime or socket. Not “the AI.”

Common OpenHands install errors and fixes

Older docker.all-hands.dev pulls throwing registry EOF, or a sandbox spinner that never ends, usually trace back to bad tags, a missing socket mount, or host networking – not a dead project.

Upgrade, migrate, uninstall

Upgrade CLI:

uv tool upgrade openhands --python 3.12

Confirm with openhands -v. Pure Docker deploys: pull the app + agent-server tag pair from the same live doc section, not from memory.

Uninstall / cleanup:

uv tool uninstall openhands

# wipe local state (keys, history - irreversible)
rm -rf ~/.openhands

docker rm -f openhands-app 2>/dev/null || true

# optional once you confirm names via docker images
# docker rmi docker.openhands.dev/openhands/openhands:1.8
# docker image prune

Agent Canvas on the GitHub/OpenHands line is a sibling control-center path for multi-agent backends. Skip it until the classic GUI loop above is boringly reliable.

FAQ

Is OpenDevin still the right search term?

No. Use OpenHands – OpenHands/OpenHands and docs.openhands.dev.

Why do I see 1.16.0, 1.14.0, and openhands:1.8 at the same time?

Different artifacts on purpose. PyPI openhands is the CLI/launcher (1.16.0 on the May 8, 2026 release we checked). GitHub’s v1.14.0 stamp tracks the broader repo/Agent Canvas surface. The GUI image tag and AGENT_SERVER_IMAGE_TAG are yet another pair from local-setup. Pick one recipe and stay inside it; averaging the numbers is how pulls break.

Can I run without Docker?

You can install the terminal CLI without bringing the full GUI stack up. Sandboxed agent runs still expect Docker in normal local setups – maintainers have been blunt that dockerless paths are weaker. Policy blocks Docker on the laptop? Don’t force the local GUI; use a hosted or remote setup your org already allows.

Next: uv tool install openhands --python 3.12 && openhands -v && openhands serve, save one API key, then open a real repo with --mount-cwd.