OpenHands Install Guide 2026: Run the 83k-Star Coding Agent on Your Own Machine

📘 Tutorials 2026-08-12 3 min read

OpenHands promises a fully autonomous coding agent, but the install docs assume you already know Docker, sandboxing and model config. Here is the step-by-step path from zero to a working agent.

💡 What You Will Learn

OpenHands promises a fully autonomous coding agent, but the install docs assume you already know Docker, sandboxing and model config. Here is the step-by-step path from zero to a working agent.

📜 Table of Contents

What OpenHands Actually Is
Prerequisites
Step 1: Install Docker
Step 2: Run OpenHands
Step 3: Configure a Model
Step 4: Give It a Real Task
Troubleshooting
FAQ

What OpenHands Actually Is

OpenHands (83,725 stars on GitHub, fetched 2026-08-12) is an AI software development agent that writes code, executes it in a sandbox and iterates until the job is done. The core loop: the agent receives a task, plans, edits files, runs commands, reads the output and tries again. That loop is why it needs Docker - the sandbox is where the code actually runs.

Prerequisites

A machine with Docker installed (Linux, macOS or Windows with WSL2).
At least 8 GB RAM; 16 GB is comfortable.
An LLM API key (OpenAI, Anthropic, DeepSeek or any OpenAI-compatible endpoint - OpenHands supports many providers).

Step 1: Install Docker

On Linux: curl -fsSL https://get.docker.com | sh, then add your user to the docker group and re-login. On Windows, install Docker Desktop and make sure WSL2 backend is enabled. Verify with docker --version and docker run hello-world.

Step 2: Run OpenHands

docker pull docker.all-hands.dev/all-hands-ai/openhands:0.37

Then start it with your API key:

export LLM_API_KEY="sk-your-key"
docker run -it --rm --pull=always \n  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.37-nikolaik \n  -e LLM_API_KEY=$LLM_API_KEY \n  -v /var/run/docker.sock:/var/run/docker.sock \n  -v ~/.openhands-state:/.openhands-state \n  -p 3000:3000 \n  --add-host host.docker.internal:host-gateway \n  --name openhands-app \n  docker.all-hands.dev/all-hands-ai/openhands:0.37

Open http://localhost:3000 and you should see the OpenHands UI.

Step 3: Configure a Model

In the UI settings, pick your provider and model. Two practical defaults for 2026: - DeepSeek (cheap, strong coding) - the API is OpenAI-compatible. - Anthropic Claude - strongest reasoning if budget allows.

For local models, point OpenHands at an Ollama instance running on the same machine: set the model to ollama/llama3.1:8b style and the base URL to http://host.docker.internal:11434/v1.

Step 4: Give It a Real Task

Start with something contained: 'Create a Python script that fetches the top 5 stories from Hacker News and saves them as markdown.' Watch how it plans, writes, runs and fixes. If it hits an error, it should read the error and correct itself - that self-correction loop is the whole point.

Troubleshooting

Sandbox fails to start: re-pull the runtime image; the tag must match your OpenHands version.
No model connection: check the base URL. Local Ollama needs host.docker.internal inside the container, not localhost.
Slow first task: the runtime image downloads on first use; subsequent runs are fast.