This Open-Source Tool Writes Code, Fixes Bugs, and Edits Files By Itself — OpenHands Setup

When I first read the description for OpenHands, I was skeptical. "AI software development agent" sounds like every overhyped startup pitch from 2024. But then I saw the demo: someone typed "add input validation to the login form" and watched the agent open files, write the code, run the tests, fix the test failures, and commit the changes. All without touching the keyboard again.

I had to try it. So I spun up Docker on my Linux machine, followed the setup, and gave it a real task from my own codebase. Here's the honest story — what worked, what didn't, and exactly how to replicate this yourself.

OpenHands is an open-source AI software development agent built by the All-Hands AI team. It was formerly known as OpenDevin and is one of the top-performing systems on the SWE-bench benchmark — a standardized test where AI agents are given real GitHub issues and evaluated on whether they can actually fix them.

Unlike simple code-completion tools (like Copilot), OpenHands operates like an autonomous developer. It has a persistent working environment: it can browse the web, read documentation, execute terminal commands, edit files, and run tests. It "thinks" step by step, making decisions at each point about what to do next.

You can connect it to any LLM backend — Claude, GPT-4, or even a local model via Ollama. The better your underlying model, the smarter the agent. For serious work, Claude 3.5 Sonnet or GPT-4o give the best results.

Before we install anything, make sure you have these ready:

• Docker — OpenHands runs inside Docker. Install Docker Desktop from docker.com if you haven't already.
• An LLM API Key — You'll need one from Anthropic, OpenAI, or another provider. Alternatively, use a local Ollama endpoint (free).
• A Project Directory — The folder you want the agent to work on. OpenHands mounts this as a workspace inside its container.
• 4+ GB of RAM — The container is lightweight, but your LLM backend needs headroom.

Make sure Docker is running before the next step. You can verify with docker --version in your terminal.

The official way to run OpenHands is a single Docker command. Open your terminal and paste this:

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

docker run -it --rm --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands-state:/.openhands-state \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:0.40

This will pull the image (first run takes a few minutes) and start the OpenHands server. Open http://localhost:3000 in your browser. You'll see the OpenHands interface — clean, minimal, professional.

On the settings screen, enter your LLM provider (Anthropic, OpenAI, etc.) and your API key. Then select your model — I used claude-3-5-sonnet-20241022 for my test.

To give OpenHands access to your actual project files, you mount your project directory into the container. Modify the Docker command to include a volume mount:

-v /path/to/your/project:/workspace

Replace /path/to/your/project with the absolute path to your codebase. On Windows, it looks like C:/Users/yourname/myproject:/workspace.

Now when you open the UI and start a conversation, tell the agent where your project is: "My project is at /workspace. Please look at the README and tell me what it does." It will actually read the file and summarize it. This still amazes me every time.

I gave OpenHands a task from my own project: "There's a bug where the API pagination stops returning results after page 3. The relevant files are in /workspace/src/api. Please find and fix it."

Here's what it did, completely autonomously over about 8 minutes:

1. Read the README to understand the project structure.
2. Listed files in /workspace/src/api.
3. Opened the pagination controller and read the code.
4. Identified an off-by-one error in the page offset calculation.
5. Edited the file to fix the bug.
6. Ran the existing test suite with npm test.
7. Noticed one test failed due to the fix, rewrote the test assertion to match the corrected behavior.
8. Ran tests again — all green. Reported back with a summary of exactly what it changed and why.

I verified the fix manually. It was correct. The entire process took less time than it would have for me to even fully understand the bug context.

OpenHands is genuinely impressive, but it's not magic. Here's what I've learned after using it for several weeks:

• Be specific in your prompts. Vague instructions like "improve performance" lead to unfocused agents. Specific tasks like "reduce the response time of the /api/search endpoint" work much better.
• Always review its changes. Use git diff before accepting anything. The agent can confidently make wrong changes, especially in complex business logic.
• It works best with test coverage. If your project has good tests, the agent can verify its own work. Without tests, it's operating blind.
• Large codebases = more cost. Each step uses API tokens. A complex task can cost $0.50–$3 with frontier models. Local models eliminate this cost but reduce quality.
• It's not for greenfield projects (yet). It excels at targeted fixes and additions to existing code, less so at designing entire systems from scratch.

The bottom line: OpenHands is already production-useful for developers. It handles the tedious, well-scoped tasks extremely well, freeing you to focus on the high-level architecture and product decisions. This is not the future of development — it's the present.