OpenHands 1.0 Deploy Guide: Install, Fix, Verify

OpenHands has 68,000+ GitHub stars and 8,500+ forks (as of early 2026), but here’s the detail almost no tutorial mentions: in October 2025 the entire GitHub organization was renamed from All-Hands-AI to OpenHands. Every old install command you’ll find on Medium, YouTube, and Stack Overflow still points to image paths that now redirect inconsistently. If you’ve tried installing OpenHands recently and watched it fail with a cryptic networking error, that’s probably why.

OpenHands 1.0.0 dropped on 2025-12-16. This guide covers the install path the maintainers actually recommend – via uv, not the legacy Docker one-liner – then unpacks the three errors that eat the most hours.

System requirements (and what the docs don’t spell out)

Per the official setup page, a system with a modern processor and a minimum of 4GB RAM is the floor, not the comfortable spot.

One catch that trips up Docker-first installs: the default MCP servers require uv to stay installed even after you’ve launched via Docker. Per the official setup docs, “you’ll still need uv installed for the default MCP servers to work properly.” People install via Docker, remove uv to clean up, then wonder why search and other MCP tools silently break.

Install OpenHands with uv (the new recommended path)

The OpenHands team moved away from the old docker run one-liner as the primary path. The new way uses uv, Astral’s Python package manager, because it bootstraps the right Python version without manual setup.

# 1. Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
# Windows (PowerShell):
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Make sure Docker Desktop / daemon is running
docker ps # should not error

# 3. Launch the GUI server
uvx --python 3.12 openhands serve

# Optional: mount your current project
uvx --python 3.12 openhands serve --mount-cwd

That single uvx command takes care of Docker requirements checking, image pulling, and launching the GUI server – all in sequence. On first run it pulls the agent-server image, so don’t kill the process if it sits at “Pulling” for a few minutes (the image is large).

Once the logs settle, open http://localhost:3000. The web UI will ask you to configure an LLM provider. Paste in any LiteLLM-compatible API key – Anthropic, OpenAI, or a local Ollama endpoint all work.

There’s a subtle distinction worth sitting with: “installing OpenHands” and “having a working OpenHands” are two different things. The install takes 2 minutes. But the system is actually three moving parts – the main app container, the agent-server sandbox, and your LLM provider – and they can fail independently. The verification step below checks all three at once.

If you prefer the raw Docker path

The fallback Docker command, using the post-rename image registry:

docker run -it --rm --pull=always 
 -e AGENT_SERVER_IMAGE_REPOSITORY=docker.openhands.dev/openhands/runtime 
 -e AGENT_SERVER_IMAGE_TAG=1.2-nikolaik 
 -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.2

Note the registry: docker.openhands.dev/openhands/, not docker.all-hands.dev/all-hands-ai/. The old paths still resolve in some places, but new tags are only published to the new registry.

First-time configuration and verification

1. Open http://localhost:3000 and click through the welcome flow.
2. Go to Settings → LLM. Pick a provider and paste your API key.
3. (Optional but smart) Add a Tavily API key under Search API Key (Tavily) if you want web search inside the agent.
4. Click New Conversation and send: “Print the contents of the current working directory and write the count to a file called test.txt”
5. If it spawns a sandbox, runs ls, and writes the file – your install is healthy.

Skip the demo prompt every tutorial uses (“build me a website”). It’s too open-ended for a sanity check. A 2-action verification prompt like the one above tells you immediately whether the sandbox, file editor, and terminal tools all work – which is what you actually need to verify.

The three errors that eat the most time

These aren’t theoretical. They’re pulled from open GitHub issues and the official troubleshooting page.

1. “Sandbox failed to start within 120s”

Users running on a VPS and on Linux desktops both hit a 120-second timeout on the agent-server container – reported across issues #12229, #12500, and #13578. The root cause: when deploying OpenHands as a LAN-accessible server using Docker runtime, agent-server containers fail to start because they can’t resolve host.docker.internal, causing conversations to stay stuck at WAITING_FOR_SANDBOX.

The fix on Linux servers: add --add-host host.docker.internal:host-gateway to your docker run (already in the template above). For Docker Compose, set extra_hosts in the compose file. If you’re on a VPS where the agent-server container is on a different bridge network than the main app, setting OH_SANDBOX_USE_HOST_NETWORK=true has resolved this for several users in the GitHub issues thread – though this flag isn’t formally documented in the official setup page as of 2026.

2. PermissionError on ~/.openhands

If your first docker run was prefixed with sudo, the troubleshooting page is direct: check if ~/.openhands is owned by root. If so: change ownership with sudo chown user:user ~/.openhands, update permissions with sudo chmod 777, or delete it if you don’t need previous data.

3. Old tutorials, dead image paths

Copy-paste a command from a 2024 blog post and get image-pull failures? It’s the rename. After the GitHub organization rename from All-Hands-AI to OpenHands on Oct 20, 2025, Docker image references moved from ghcr.io/all-hands-ai/ to ghcr.io/openhands/ – and git remotes for any local clones need the same update.

uv vs Docker: which install path actually wins?

Both methods end up running the same containers. The difference is maintenance ergonomics.

Use uv on your laptop, use raw Docker (or Compose) anywhere else. The uv path is faster to upgrade, but Docker Compose is the only sane way to run OpenHands behind a reverse proxy with persistent storage.

Upgrade and uninstall

uv tool upgrade openhands

For Docker, change the tag (e.g. from :1.0 to :1.2) and re-run. The --pull=always flag handles fetching the new layers.

To uninstall completely:

# Remove the tool
uv tool uninstall openhands

# Stop and remove any leftover containers
docker rm -f openhands-app 2>/dev/null
docker images | grep openhands | awk '{print $3}' | xargs -r docker rmi -f

# Wipe state (conversations, settings, MCP cache)
rm -rf ~/.openhands

That last rm -rf matters. Leaving ~/.openhands behind is the most common reason a “clean reinstall” still shows your old conversations and settings.

Under the hood: what actually changed in 1.0

OpenHands 1.0 isn’t a rewrite of older versions – it’s a re-architecture. Version 1.0.0 uses the new software-agent-sdk, with the underlying tool-calling model and execution architecture documented in Wang et al., “The OpenHands Software Agent SDK” (arXiv:2511.03690, 2025).

Any tutorial dated before December 2025 that talks about “OpenHands microagents” or the old agent loop is describing a different system. The configuration knobs changed. The Docker image names changed. The Python entry point changed. If something from an old guide isn’t working, that’s the first thing to check – not your environment.

FAQ

Is OpenHands actually free?

The local install is fully free under MIT. OpenHands Cloud’s Pro tier is $20/month and covers runtime compute – you still bring your own LLM API key either way.

Can I run it without sending code to any cloud?

Yes. Set the LLM Base URL in Settings to a local Ollama or vLLM endpoint, and set the API key to any non-empty string. The agent, sandbox, and workspace stay entirely on your machine – nothing reaches Anthropic or OpenAI unless you explicitly configure those providers. The MIT license means you can audit exactly what the code does before running it.

Why does my agent stall on the first prompt?

Nine times out of ten: the sandbox timeout. The main container reached your LLM fine, but can’t reach the agent-server on its dynamic port. Check the logs for “Sandbox server not running” or the 120-second timeout message. If either shows up, --add-host host.docker.internal:host-gateway is almost certainly missing from your run command – or, for Compose deployments, missing from extra_hosts on the relevant service.

Next step: after your verification prompt passes, clone a small real repo into ~/openhands-work, launch with uvx --python 3.12 openhands serve --mount-cwd from that directory, and give the agent a scoped task like “add a test for the function in utils.py and run pytest.” That’s the smallest end-to-end loop where OpenHands stops looking like a chat UI and starts looking like an actual coworker.