How to Install OpenDevin (OpenHands): Complete Setup Guide

Before You Start

Installing OpenDevin (now OpenHands) requires three things:

1. Docker — OpenHands runs in a sandboxed container
2. An LLM API key — OpenAI, Anthropic, Google, or a local model via Ollama
3. A machine with 8GB+ RAM recommended (4GB works for small tasks)

The setup takes about 10 minutes on a fast connection.

Prerequisites

Install Docker

macOS: Download Docker Desktop from docker.com. Start it after installation.

Ubuntu/Debian:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in, or run:
newgrp docker

Windows: Install Docker Desktop. Enable WSL2 backend in Docker settings.

Verify Docker is running:

docker --version
# Docker version 25.x.x, build xxxxxxx
docker run hello-world
# Hello from Docker!

Get an LLM API Key

You need at least one:

GPT-4o and Claude Sonnet produce the best results for complex coding tasks.

Installation: Docker Web UI (Recommended)

The web UI is the easiest way to use OpenHands. One Docker command starts everything:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.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.5

After the containers start (takes 1–2 minutes the first time), open your browser at:

http://localhost:3000

First-Time Configuration

On the first visit, you’ll see the settings screen:

1. LLM Provider — Select OpenAI, Anthropic, Google, or Custom
2. Model — Enter your model name (e.g., gpt-4o, claude-sonnet-4-6-20250514)
3. API Key — Paste your key
4. Click Save

Your settings are stored in ~/.openhands/ and persist across restarts.

Installation: CLI

For headless/server use, install the CLI:

pip install openhands

Or via Docker (no Python install needed):

docker run -it \
    --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
    -e SANDBOX_USER_ID=$(id -u) \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/root/.openhands \
    --add-host host.docker.internal:host-gateway \
    --name openhands-cli \
    python:3.12-slim \
    bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Run a task from the command line:

openhands run "Write a Python function that parses JSON and handles errors gracefully"

Or start the GUI server from the CLI:

openhands serve           # start the web UI
openhands serve --mount-cwd  # mount your current directory
openhands serve --gpu     # enable GPU (requires nvidia-docker)

Configuring an OpenHands Project

To give OpenHands access to your code, mount your project directory:

export PROJECT_DIR=/path/to/your/project

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -v $PROJECT_DIR:/workspace \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  docker.openhands.dev/openhands/openhands:1.5

Inside OpenHands, your project will be available at /workspace. You can tell the agent: “The code is in /workspace. Fix the failing tests.”

Running Your First Task

With the web UI open:

1. Type your task in the chat input
2. Press Enter
3. Watch the agent work in real time

Good first tasks to try:

Write a Python script that reads a CSV file and outputs basic statistics
(mean, median, min, max) for each numeric column.

Create a simple REST API with Flask that has CRUD endpoints for a todo list.
Include tests using pytest.

You’ll see the agent:

• Plan the approach
• Create files
• Run code
• Fix any errors it encounters
• Report when done

Using Local Models with Ollama

For privacy or zero API cost, use Ollama with a local model:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a capable model (requires ~8GB RAM)
ollama pull qwen2.5-coder:7b

# Start Ollama
ollama serve

In OpenHands settings:

• Provider: Ollama
• Model: ollama/qwen2.5-coder:7b
• Base URL: http://host.docker.internal:11434

Local models work well for simple tasks but lag behind GPT-4o/Claude on complex multi-file changes.

Troubleshooting

docker: permission denied

sudo usermod -aG docker $USER
newgrp docker

Port 3000 already in use

Change the port mapping:

-p 3001:3000

Then open http://localhost:3001.

Agent seems stuck or loops

Click Stop in the UI. Try rephrasing the task more specifically. Add constraints like “do not modify files outside /workspace/src”.

Cannot connect to Docker daemon

Make sure Docker Desktop is running (macOS/Windows). On Linux, check:

sudo systemctl status docker
sudo systemctl start docker

Frequently Asked Questions

Can I run OpenHands without Docker?

Docker is strongly recommended as it provides the sandboxed environment the agent needs. Running without Docker is possible but unsupported and risks the agent modifying your host filesystem.

How much does it cost per task?

With GPT-4o at ~$5/million tokens: simple tasks (write a function) use ~$0.02–0.05. Medium tasks (add a feature to an existing codebase) use ~$0.10–0.50. Complex tasks (refactor a module, fix a set of failing tests) can use $0.50–2.00. Use claude-haiku-4-5 or a local model to reduce cost significantly.

Where are my files after OpenHands runs?

If you mounted a project directory with -v, files are saved there on your host. Without a mount, files are inside the agent’s container and lost when the container stops. Always mount your workspace for persistent work.

Can multiple people use the same OpenHands instance?

Not easily — the default setup is single-user. For multi-user deployment, look at the enterprise version or deploy behind an auth proxy. Each user should have their own instance.

How do I update OpenHands?

docker pull docker.openhands.dev/openhands/openhands:latest

Then re-run the Docker command. Your settings in ~/.openhands/ are preserved.

Next Steps

• What is OpenDevin — Understand what OpenHands can do before diving deeper
• What is AutoGPT — Compare with another autonomous agent framework
• CrewAI Multi-Agent Workflows — Build your own multi-agent system