How to Run OpenHands Locally and Fix a Real GitHub Issue
OpenHands (formerly OpenDevin) is an open-source coding agent that runs in a sandbox, browses the web, edits files, and executes shell commands. You give it a task in plain English; it works through it and shows you the diff.
OpenHands is not an autocomplete tool. It behaves like a junior engineer with a terminal — which is useful and also a reason to keep it in isolation. This guide covers local setup and a first real task.
What does OpenHands need to run?
Docker, Python 3.12 if you want the source install, and an LLM API key or a local model server. About 4 GB of RAM for the container, more if you point it at a large repository.
The sandbox is the product. The agent gets a Linux environment, not your laptop’s filesystem. Keep it that way — agents that execute generated shell commands on a host machine are a bad idea regardless of how good the model is.
Step 1: Start it with Docker
The fastest path avoids a Python install entirely:
docker pull docker.all-hands.dev/all-hands-ai/runtime:0.30-nikolaik
export SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.30-nikolaik
docker run -it --rm --pull=always \
-e SANDBOX_RUNTIME_CONTAINER_IMAGE=$SANDBOX_RUNTIME_CONTAINER_IMAGE \
-e LOG_ALL_EVENTS=true \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 3000:3000 --add-host host.docker.internal:host-gateway \
docker.all-hands.dev/all-hands-ai/openhands:0.30
Open http://localhost:3000. Note that mounting the Docker socket gives the container control over your Docker daemon. That is how it spawns sandboxes, and it is also why you should run this on a dev machine or VM, never on a shared production host.
Step 2: Set the model
In settings, choose a provider and paste a key. OpenHands works with hosted models and with local models served through an OpenAI-compatible endpoint.
Model choice changes the outcome more than any other setting. A small, fast model produces agents that loop — repeating a failing command with slight variations. Reasoning-capable models at roughly 32B parameters and above hold multi-step plans together. If you are running locally, budget the VRAM: an 8B model is not going to solve a multi-file refactor reliably no matter how good the prompts are.
Step 3: Point it at a repository
Two options: give it a GitHub repository URL, or start from a local workspace mount.
For a first attempt, use a GitHub URL on a small repository you own with a known issue. OpenHands clones into the sandbox, so your local checkout is untouched.
Step 4: Write the task
Vague tasks produce vague diffs. A usable task looks like this:
Fix the failing test in tests/test_pagination.py::test_last_page.
The test expects page 3 of 100 items with per_page=25 to contain
exactly 0 items, but the endpoint returns 25.
Do not change the test. Fix the pagination logic in app/pagination.py.
Run the full test suite when done.
Four things make that work: the specific failing test, the expected behavior, the constraint (do not change the test), and the verification command. Without the constraint, agents happily rewrite the test to pass.
Step 5: Review the diff, then run tests yourself
OpenHands shows every file edit and every shell command it ran. Read the command log before the diff. A diff that looks clean but came from eleven failed test runs and a pip install of something unexpected is a diff you should not trust.
Then pull the branch and run the test suite on your own machine. Agent-verified passing tests are a claim, not a proof.
What does it cost to run, and where does it fail?
Cost is the model’s token price times the trajectory length. A small issue takes 20 to 60 steps; each step includes the full context. Budget several dollars per task with a frontier model, and cents with a local model that may not finish the task.
Failures cluster in three places: enormous repositories where the agent cannot isolate the relevant files; build systems with slow test suites that time out a step; and tasks requiring domain knowledge that is not in the code or docs. It also cannot review its own work meaningfully — a second model reading the diff catches more than the same model asked to double-check.
Quick Summary
- OpenHands is an open-source (MIT) coding agent that runs in a Docker sandbox with a shell, browser, and file editor.
- The Docker one-liner needs the runtime image tag plus the Docker socket mount; run it on a dev machine or VM only.
- Model choice decides success more than prompt wording; sub-10B local models tend to loop on multi-file work.
- A good task names the failing test, expected behavior, constraints, and verification command.
- Read the command log before the diff, and always rerun tests yourself before merging.
