Over the past year, the most useful direction in AI coding hasn't been chatbots. It's been agents that get work done.
Give one an issue. It reads the repo, finds the bug, edits files, runs tests, opens a PR. When that full loop works, you're looking at something close to a real software-engineering agent.
Devin is closed source. AutoGPT is more of an experiment. OpenHands is one of the few open-source projects that combines strong attention, real engineering, and the ability to actually open pull requests.
The main GitHub repo currently sits at 84,555 stars. The project was originally called OpenDevin, later renamed OpenHands. The repo isn't pure Python — it's a TypeScript + Python codebase: the web frontend and interaction layer are mainly TypeScript, while the agent core, runtime, and controller live in Python.
Source: OpenHands on GitHub
What problem it solves
Regular code completion answers "how do I write this snippet." An agent handles the full task:
- Read the issue and repo context
- Plan the change
- Search code
- Edit files
- Run shell commands
- Run tests and linters
- Inspect the diff
- Produce a commit or PR
The hard part isn't generating code once.
The hard part is that every step can fail. Tests don't pass. Network requests time out. The agent edits the wrong file. Can it observe the result and decide what to do next?
What OpenHands does is turn the terminal, filesystem, and browser into tools the agent can call. It doesn't just generate code — it executes and verifies.
This is the difference from Cursor Agent and Copilot. Those two mostly orbit the editor. OpenHands aims higher: hand the model a complete, isolated, observable development environment.
Compared to Devin, it's open source.
Compared to AutoGPT, it's much more engineered: a real Runtime, Controller, event bus, SDK, and Docker deployment path.
How to use it
The simplest way is to run it locally:
docker run -d \
-p 3000:3000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.openhands:/root/.openhands \
--name openhands \
ghcr.io/openhands/openhands:latest
Then open http://localhost:3000.
The host runs the web UI, API, and agent control. By default, the code that actually executes commands lives in a separate Docker sandbox.
For automation, there's a Python SDK. The snippet below is the canonical SDK call:
from openhands import OpenHandsAgent
agent = OpenHandsAgent(
llm_model="claude-3-5-sonnet",
workspace="./demo-project",
runtime="docker"
)
task = "修复 src/main.py 里的除零 bug,跑通 tests/ 下全部用例"
result = agent.run(task, max_steps=20)
print("状态:", result.status)
print("改动文件:", result.modified_files)
print("测试输出:", result.test_output)
Three things are happening here:
workspacepoints at the repo you want to operate on.runtime="docker"specifies the execution environment.max_steps=20caps the agent's actions, so it can't loop forever.
The SDK's value goes beyond chatting about code. Batch jobs, CI helpers, internal task queues — anything can plug an agent in.
Model defaults route through Anthropic or OpenAI cloud APIs. Skip the cloud and you can run Ollama or vLLM locally.
Watch the version drift. Model names and SDK APIs change as the project evolves. Before deploying, check the current README, examples, and the installed package's interface — don't blindly copy model names from older articles.
How it works (architecture)
OpenHands splits cleanly into three layers.
Runtime: the agent's hands and feet
Runtime is the actual execution environment.
Code lives mainly in openhands/runtime/. It defaults to Docker isolation and gives the agent three primitives:
- Run shell commands
- Read, write, and edit files
- Control a browser
These three cover most development tasks. Install dependencies, modify code, start a service, inspect a failing page — all compose from them.
Runtime also extends across languages, supporting Python, Node.js, Go, and others. What actually works depends on the runtime type and plugin configuration.
Isolation is the most important design choice at this layer. The model sees a constrained workspace. The host should never be exposed directly to the agent.
Agent: deciding what to do next
The agent controller manages task state, planning, memory, and tool calls.
Key code lives in openhands/controller/agent/.
It doesn't take a prompt and immediately spit out an answer. It maintains a chain of actions:
- Observe the current repo and task state.
- Pick a tool.
- Pass parameters and execute.
- Read the output or error.
- Update the plan and move to the next step.
The typical agent loop looks like ReAct: reasoning and acting alternate. Decide before each action, read the feedback after.
This is the main difference between an agent and a script generator. A script generator just produces text. An agent consumes the real results tools return.
OpenHands also supports a custom Action Space. Developers can register new tools — define parameters, return values, and execution behavior — then hand them to the agent.
Add a "query internal API docs" tool, or a "pull production error logs" action. Once tool boundaries are clear, the agent can be trusted with real systems.
LLM: reasoning only
The third layer is the LLM.
It understands the issue, analyzes diffs, decides which tool to call. But command execution, file writes, and browser control don't happen on the model server — they happen in Runtime.
This separation matters.
If you cram shell, editor, and browser into a single prompt, permission boundaries blur. OpenHands makes them controlled tools. The model can only pick from registered actions; Runtime executes them.
Event bus: making the process observable
Every agent action and result flows as an event. The frontend receives updates over WebSocket.
You can watch:
- Which file the agent is reading
- Which command it ran
- Whether the command failed
- Which files were modified
- What the test output was
- Whether it's currently planning, coding, or verifying
Observability isn't just for demos. It helps you tell whether the agent is actually fixing the problem or stuck in a loop.
What it's good at — and where it falls short
OpenHands' strengths are concrete.
First, fully open source.
Licensed under MIT — commercial use, modify, self-host. Small teams that don't want to be locked into Cursor or Copilot can build it into their internal agent infrastructure.
Second, sandbox isolation is solid.
Commands, file edits, and browser actions all live inside Runtime. The model can't casually touch the host.
Third, the Action Space is extensible.
Internal build systems, code search services, database query tools — anything can plug in through a controlled interface.
Fourth, it has benchmark backing.
OpenHands has consistently sat in the top tier of open-source projects on SWE-bench Verified. For most of 2024, it led the open-source agent field. Specific scores shift with model, commit, and benchmark config — don't mix results from different dates.
The problems are real.
Local deployment is hungry. Running the full service, model, and sandbox together is non-trivial on CPU, memory, and disk. Plan for at least 8GB of RAM as a safe baseline.
Cloud APIs are still the default path. Ollama and vLLM are supported, but smaller models degrade on long-repo comprehension, tool selection, and failure recovery.
Chinese-model support is catching up. Official configs usually prioritize Anthropic and OpenAI. In Chinese network environments, services like DeepSeek and Tongyi Qianwen tend to be more stable.
Complex multi-file refactors often loop. Wrong files get edited, tests depend on external services, commands keep timing out. max_steps limits the damage, but it can't recover from a broken plan.
I tried it
I built a small test with a deliberately broken Python project. The goal was simple: fix a divide-by-zero bug and pass everything under tests/.
The flow:
- Started OpenHands with Docker.
- Connected Claude 3.5 Sonnet.
- Mounted the repo as the workspace.
- Sent the task: locate the divide-by-zero, fix it, run the tests.
The agent searched src/main.py and pinpointed the division-by-zero branch.
It didn't commit immediately. After editing, it ran pytest, confirmed the tests passed, then reviewed the diff.
I set the step limit to 20. It didn't come close.
Mid-run, it tried to install requests. The sandbox had no outbound network, so the install failed. The agent read the error, didn't retry, and switched to Python's standard-library urllib. Tests passed, and it produced a local commit.
Then I swapped in DeepSeek-V3 for the same task.
Three observations:
- It completes the task — not just code snippets.
- It's noticeably slower — roughly 40% longer for the same task.
- Simple fixes don't fail. Complex refactors are less stable than Claude or GPT-4o.
None of this is a rigorous benchmark. It's the same container, same task, same step cap. It shows the integration path works; it doesn't rank models.
Common pitfalls for users in China
Slow Docker pulls are the first trap.
The ghcr.io image is large, and shaky networks stall easily. Pull a fixed version in advance, configure Docker Hub mirror acceleration, and pin the OpenHands image to a specific tag.
Don't live on a rolling latest. Upgrades can change Runtime behavior, API parameters, and tool results.
The second trap is model API access.
Anthropic and OpenAI services can be slow and unstable in parts of the Chinese internet. In testing, DeepSeek or Tongyi Qianwen were more reliable.
Don't fill in model names from memory. Check the current version's model config page and code. Some older models are deprecated; some services need specific parameters.
The third trap is permissions.
To use the Docker Runtime, the common launch mounts the host's Docker socket into the container. Convenient, but a lot of privilege.
Don't copy a dev config into production. Restrict container privileges, switch to a remote Runtime, and give internal services short-lived credentials.
The fourth trap is workspace persistence.
The default sandbox isn't a permanent workspace. After a container rebuild or service restart, temporary files may be gone.
When you need to keep code, mount a persistent volume. When you need commits, PRs, and task records, connect external Git hosting or object storage.
Who should use it
OpenHands fits three groups.
Small teams. You want an internal AI coding assistant without being tied to Cursor or Copilot. The catch: someone has to maintain Docker, models, and internal tools.
Agent engineers. You want to read Runtime, Controller, tool protocols, and event-flow source code. OpenHands is closer to a production system than most demo projects.
Benchmark researchers. You want to run SWE-bench-style tasks or test different models on repo-level fixes. Its Runtime, Action Space, and event log are all usable for experiments.
Three groups it's not for.
Users who don't want to write any config. If you just want a few lines of completion, Cursor or Copilot are easier.
Anyone requiring full offline operation. Local inference needs GPU, model adaptation, and plenty of memory. Tool-call stability on domestic hardware still needs tuning.
People handling sensitive code without configuring isolation. Sandbox, volume, network policy, and credential management all need explicit attention. Secure defaults don't replace a real deployment review.
If the only question is "can AI edit a repo," OpenHands has already proven the answer is yes.
What actually decides the outcome is three things: whether the model plans well, whether the Runtime is controllable enough, and whether tool results help the agent self-correct.
It's not ready for unsupervised runs on critical workloads. But for anyone building an engineering agent that's modifiable, observable, and integrable with internal tools, OpenHands remains one of the most worthwhile open-source projects to crack open.