OpenHands: The Autonomous Coding Agent You Can Self-Host

"Give it a GitHub issue, get back a pull request." That is the pitch. With a frontier model behind it, OpenHands delivers. With a 7B local model, it is a tech demo. The model you plug in decides everything — including whether your proprietary source ever leaves your machine.

Coding copilots — tab completion, in-editor chat — are table stakes in 2026. The interesting frontier is different: agents that take a goal, explore a codebase, run commands, fix errors, and open a PR without you approving every step. That is the leap from "the AI suggests the next line" to "the AI closes the ticket."

Closed products (Devin, and the cloud tiers of the big labs) do this, but your code, your repo, and your secrets pass through their infrastructure. For regulated or security-sensitive work, that is a non-starter. You are handing your source code — the thing your business is built on — to a SaaS, and hoping their security is as good as they say.

OpenHands is the open-source answer. Formerly OpenDevin, it is the most-starred autonomous coding agent on GitHub — 76K+ stars as of mid-2026, MIT-licensed (except the enterprise directory), and fully self-hostable. You point it at your own model — local or cloud — and it works inside a sandbox you control.

An autonomous agent exploring a codebase and opening a pull request

This is a deep, opinionated look at what OpenHands actually is, how the agent loop works, what tasks it fits, how to self-host it with a local model, a real issue walkthrough, troubleshooting, what it costs, where your code goes, and — the part this blog cares about — the security boundary that keeps your source on your hardware.

1. The Autonomous Coding Dilemma

Let me frame the shift precisely, because "coding agent" has become a vague term. There are three tiers:

1. Completion (Tabby, Continue, GitHub Copilot): predicts the next token. You write the structure; it fills gaps.
2. Chat (in-editor assistants): you describe, it suggests a snippet. You copy-paste and adapt.
3. Autonomous agent (OpenHands, Devin, Aider in agent mode): you give a goal, it explores the repo, edits across files, runs tests, iterates on failures, and opens a PR.

Tiers 1 and 2 keep you in the loop at every step. Tier 3 removes you from the loop until the end — you review the PR, not every keystroke. That is the productivity delta people are excited about, and it is also where the risk lives.

The closed option (Devin) is genuinely capable but your code transmits their servers. For a startup building a moat out of proprietary code, that is a category of risk no SOC-2 badge fully dissolves. The open option — run the agent on your own hardware, pointed at your own model — keeps the code where it belongs.

OpenHands is the most mature open option in tier 3. That is why it is in this series: it is the "AI program" that pairs naturally with the local models and runtimes this blog covers.

2. What OpenHands Actually Is

OpenHands is an autonomous software-engineering agent platform. You give it a task in plain English — "fix the failing test in auth.py," "add pagination to the users endpoint," "migrate this module from Flask to FastAPI" — and it:

Plans the work — breaks the goal into steps it can execute and verify.
Writes and edits code across multiple files, using the same edit tools a human would.
Runs shell commands in a sandboxed environment to build, test, and lint.
Browses the web when it needs context (docs, API references).
Iterates on errors — reads a failed test output and tries again, sometimes many times.
Opens a pull request, end to end, often with a sensible description.

That last part is the differentiator. Tab completion suggests the next token. Chat tools suggest a snippet. OpenHands executes — it is built to work asynchronously and come back with a finished PR. The agent loop: plan, edit, run, observe, repeat

The agent loop: plan, edit, run, observe, repeat

Model-agnostic by design. OpenHands uses a LiteLLM-based provider layer, so it works with Claude, GPT, Gemini, and any local model via Ollama or llama.cpp — you bring your own key or point it at your own hardware. This is the architectural fact that makes self-hosting meaningful: the agent is a thin, open scaffold; the intelligence is whatever model you plug in.

Four surfaces: a Python SDK, a CLI, a local GUI, and OpenHands Cloud. There is also a source-available enterprise edition. Backed by an $18.8M Series A (Madrona, Nov 2025) — which tells you the project is funded enough to be maintained, not a weekend repo that vanishes in a month. For a tool you might wire into your team's workflow, that funding signal matters more than people credit.

3. The Agent Loop, Explained

Most people picture an agent as "AI that writes code." The useful mental model is a tight loop, repeated until the task is done or it gives up:

1. Thought. The model reads the current state — the issue, the files it has opened, the last command's output — and decides the next action.
2. Action. It issues one of a small set of tools: read a file, edit a file, run a shell command, search the codebase, open a PR.
3. Observation. The result of that action (file contents, test output, an error) comes back.
4. Repeat. The model incorporates the observation and thinks again.

This loop is why an agent outperforms a chatbot on the same model. A chatbot answers once and stops. The loop lets the model see the consequence of its action — "I ran the test, it failed on line 42, so my edit was wrong" — and correct course. That ability to observe-and-retry is most of the value. The model is not smarter inside the agent; it is just allowed to fail and recover, which is how humans code too.

Two consequences for you as an operator:

Context management is the hidden constraint. Every loop iteration consumes tokens — the files it has read, the command outputs it has seen. A sprawling repo with giant log dumps will blow the context window and the agent will "forget" what it was doing. Scoping the task tightly (§7) keeps the loop focused.
The loop is only as good as the tools it can call. OpenHands' tool set (file edit, shell, browse, git) is deliberately close to a human dev's. That is why it generalizes — it is not a bespoke DSL, it is "what a person at a terminal can do." Lean into that: give it a repo a person could navigate, not a tangle only the original author understands.

4. What Tasks It Fits (and What It Doesn't)

This is the section that saves you from disappointment. OpenHands is not magic, and the gap between "great run" and "wasted two hours" is almost always task selection.

Good fits — high success rate:

Bug fixes with a clear reproduction. "The --verbose flag prints nothing when piped." There is a testable claim; the loop can verify.
Mechanical refactors. "Rename UserManager to AccountService across the codebase." Boring, cross-file, verifiable by the compiler. Agents love this.
Adding well-scoped features with existing patterns. "Add a /health endpoint mirroring the /status one." It can copy the pattern.
Test writing. "Write unit tests for payment.py." The loop can run them and see green.
Dependency bumps with a known migration path. "Upgrade from Flask 2 to 3, fix the breaking changes." Verifiable by tests.

Poor fits — low success, high risk:

Architectural redesigns. "Re-architect this monolith into events." Too many judgment calls; the loop will half-do it and you will spend longer reviewing than doing.
Fixes requiring deep domain knowledge. "Make the trading engine handle leap seconds." If a senior engineer would need a spec, the agent needs one too.
Anything touching secrets or infra. Never let it near credentials, prod databases, or deploy scripts. Scoped tokens and a tight sandbox are mandatory (§11).
Vague asks. "Improve performance." Improve what, by what measure? The loop will thrash.

The honest rule: if you would happily hand the ticket to a competent junior who can run the test suite, OpenHands can probably do it. If you would hesitate to hand it to a junior, do not hand it to the agent either.

5. Installation (the CLI Fast Path)

The quickest way to try it uses uv, which avoids polluting your global Python:

# One-line launch, no install needed
uvx --python 3.12 --from openhands-ai openhands

Optional alias
alias oh="uvx --python 3.12 --from openhands-ai openhands"

Important: Python 3.12 specifically. 3.14 is not supported yet, and 3.11 will fail with cryptic errors. I learned this the annoying way — a 3.13 box threw an import error that took twenty minutes to trace to a version mismatch. Pin 3.12.

For the full GUI + sandbox experience, the Docker Compose route is recommended (it mounts your workspace and gives the agent a Docker/Kubernetes sandbox to run commands safely):

services:
  openhands:
    image: docker.all-hands.dev/all-hands-ai/openhands:1.8.0
    environment:
      - SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:1.8.0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "3000:3000"

A minimal local config points the agent at your Ollama instance:

[core]
[llm]
model = "openai/gemma4:e4b"
base_url = "http://host.docker.internal:11434/v1"
ollama_base_url = "http://host.docker.internal:11434"
api_key = "local-llm"

The host.docker.internal reference is the same Docker-networking gotcha from the Open WebUI post: inside the container, Ollama is not at localhost. Get this wrong and the agent silently fails to call the model, which looks identical to "the model is dumb" — it is not, your networking is.

6. Hands-On: A Real Issue Walkthrough

Theory is cheap. Here is an actual run so the experience is concrete. I gave it a real GitHub issue from a small open-source CLI: "the --verbose flag prints nothing when piped."

What it did, observed:

1. Planned: "Locate argument parsing. Check if output is gated on a TTY check. Patch the print call. Add a test. Run the suite."
2. Explored: opened cli.py, found if sys.stdout.isatty(): print(...) wrapping the verbose block.
3. Edited: removed the isatty() guard around the verbose print.
4. Tested: ran pytest; one existing test asserted "verbose is silent when piped" — it failed, correctly.
5. Iterated: updated that test to assert "verbose prints when piped," added a new test for the piped path.
6. Opened a PR with a description: "Remove TTY gate on --verbose so output is consistent in pipes. Adds 2 tests."

Time: about six minutes. The PR was correct — a human would have done the same in maybe three. This is the good case: frontier model, clear issue, verifiable test.

The bad case, with a 7B local model on the same issue: it spent twelve minutes editing main.py (the wrong file), "fixed" the bug by deleting the flag entirely, broke the feature for interactive use, and opened a PR titled "fix verbose." Same scaffold, opposite outcome. The model is the whole game.

7. Writing a Good Issue Spec (the Part That Decides Success)

Most "the agent is dumb" complaints are actually "the issue was vague." The agent's output is bounded by the spec. A good issue for OpenHands reads like a good ticket for a human:

State the goal, not the solution. "Make --verbose print when piped" beats "remove the isatty check." The agent should decide the how.
Give the verification. "Run pytest tests/test_cli.py::test_verbose_pipe — it should pass." An agent with a test to satisfy outperforms one guessing.
Scope it. "Fix the auth module's token refresh" beats "fix auth." Smaller scopes = higher success, easier review.
Point at the right branch. The agent clones what you give it; a stale default branch wastes a run.

This is the underrated skill: prompting an agent is ticket-writing, not chatting. Spend two minutes on the issue and the run is twice as likely to land. The best teams I have seen keep a "good agent issues" template — goal, acceptance criteria, test command, out-of-scope list. It turns a flaky tool into a reliable one.

8. Pairing It With a Local Model

The promise of this blog is "AI you can run on your own machine," so the natural question is: can OpenHands run on a local model, end to end, with no cloud in the loop?

Yes — with a hardware floor. The agent's reasoning load is heavier than chat. It must read files, plan multi-step, and recover from errors, all of which need a capable model. Empirically:

7B local (Q4): a tech demo. Loops, picks wrong files, "fixes" by deleting. Do not rely on it for real work.
14B local (Q4): surprisigly usable for mechanical tasks with clear tests — renames, small bug fixes, test writing. Hit-or-miss on anything requiring judgment.
32B+ local (Q4): the floor I would trust for unattended-ish runs on well-scoped tickets. Needs a 4090-class GPU or a big Mac.
Frontier cloud (Sonnet/Opus/GPT): the strongest, but your code leaves for the model call (unless you self-host the frontier-equivalent — see Kimi K3, which an org can host).

The pattern: start local for cheap, mechanical, non-sensitive tickets; escalate to a frontier model (cloud or self-hosted) for hard ones. OpenHands' model-agnostic layer makes this trivial — swap the config per task. You are not locked to one brain.

A concrete home setup: Ollama serving qwen3:32b-q4_K_M on a 4090, OpenHands pointed at host.docker.internal:11434. Mechanical tickets get auto-PRs overnight; you review in the morning. The marginal cost is electricity. That is the local-agent dream, and it is real at the 32B tier.

9. Performance: The SWE-bench Numbers

OpenHands' headline metric is SWE-bench Verified — whether an agent can resolve real GitHub issues from popular Python repos. This is the closest thing to an objective "can it actually code" score:

| Configuration | SWE-bench Verified | Notes |
|---------------|---------------------|-------|
| OpenHands + Claude Sonnet 4.5 | ~53% | Solid default for most users |
| OpenHands + CodeAct v3 + Claude Opus 4.6 | 68.4% | Strongest published config |
| Aider (top config) | mid-60s% | Comparable, lighter footprint |
| Raw model, no agent scaffold | lower | The loop does real work |
| Local 32B (Q4) + OpenHands | ~30–40% (est.) | Mechanical tickets only |

Two takeaways. First, the agent loop matters — the same model resolves more issues inside OpenHands than when prompted directly, because the loop gives it the ability to run code, see errors, and retry. That is the entire point of an agent over a chatbot. Second, the score tracks the model. OpenHands with a frontier model competes with anything open-source; OpenHands with qwen2.5-coder:7b will plan poorly and loop.

A note on reading these numbers: 68% means it resolves roughly two-thirds of real issues end to end, unattended. The other third it either fails or produces a PR you reject. For a junior-engineer-assistant framing, that is useful. For "replace my team," it is not. Manage expectations accordingly — and remember the local-32B tier lands far lower, so calibrate your trust to the model behind it.

10. Honest Limitations

This is where most "just use the agent!" posts go quiet. OpenHands has real edges:

Heavier setup. Needs Docker for sandboxing; the CLI is lighter but less capable. Not a 5-minute install like Ollama. Budget an afternoon the first time.
Quality floors at ~32B local models. Below that, local models struggle with multi-file reasoning and long tool chains. A 7B local model is a tech demo, not a teammate. If you self-host the model, you need real iron (a 4090-class GPU or a big Mac) to get agent-grade results.
Token costs climb on large repos. More files, more context, more iterations = more spend when using a cloud model. A single stubborn issue can burn a surprising number of tokens across retries.
Still experimental for unattended use. It can make sweeping changes; you must review the PR. Treat its output as a junior engineer's first draft, not a merged commit. Never let it merge its own PR.
Sandbox escape risk is low but nonzero. The Docker sandbox is the safety boundary — keep it on, never run it with host mounts you do not trust. I once saw a misconfigured volume mount let the agent read ~/.ssh. The fix was "do not mount ~." Obvious in hindsight; catastrophic if not.
Version churn. Releases move fast (v1.8.0 shipped June 2026). Pin a version rather than trusting any number you read in a blog post. The runtime image and the app image must match.
Context can blow up. Huge log dumps or giant files in the loop will exhaust the window and the agent will "forget" its plan. Scope tightly.

None of these are fatal. All are bounded by configuration discipline — the pattern across this entire blog.

11. The Security Model: Keeping Your Code Home

This is the section that matters most for this blog's thesis, expanded because the sandbox is the whole trust boundary.

Self-hosted OpenHands with a local model = your code never leaves your machine. The agent runs in a Docker sandbox on your host, talks to Ollama on localhost:11434, and the repo stays local. No third-party server sees your source. The PR is opened against your own GitHub, from your own CI, under your own credentials. The entire pipeline is yours.

The boundary is the sandbox, and you configure it:

Mount only what the agent needs. A reckless :rw mount of your whole home directory defeats the isolation — the agent could read ~/.ssh, ~/.aws, everything. Mount the specific repo, read-only where possible. The principle: least privilege, even from your own tooling.
Scoped GitHub tokens. The agent needs a token to open PRs. Use a repo-only, no-admin token. If it leaks, the blast radius is "can open PRs in one repo," not "owns your org."
Never point it at prod. No prod DB credentials in the sandbox env. The agent runs code; if that code happens to read a connection string you mounted, it will. Keep prod far away.
The model call is the only egress risk. If the backend is local Ollama, there is no network path out — by construction. If you point OpenHands at a cloud model, that one call sends your issue text and (possibly) code snippets to the provider. Choose deliberately.

For a team that wants autonomous coding without handing proprietary source code to a SaaS, self-hosted OpenHands + a local or privately-deployed model is the cleanest 2026 option. The math is simple: closed agent = your code on their servers; open agent on your hardware = your code on your servers. Same capability, different trust boundary.

12. Troubleshooting (the Stuff Nobody Posts)

"Model is dumb / loops forever": almost always the model, not OpenHands. A 7B local model will loop; the scaffold cannot compensate. Move to a 32B+ local model or a cloud key.
"Can't reach Ollama": host.docker.internal not set, or Ollama not bound to the right interface. Inside the container, localhost is the container, not your host.
"Sandbox won't start": Docker socket not mounted (/var/run/docker.sock). The runtime needs it.
"Ran but changed the wrong file": vague issue spec. See §7.
"PR opened but CI red": the agent stops at "PR opened," not "CI green." Review and fix, or add a step that waits for CI.
"Token limit hit mid-run": large repo + small context window. Raise the model context or narrow the scope.
"Read my SSH key?": you mounted ~ into the sandbox. Remount the specific repo only, read-only. This is the scary one — fix it before the next run.

13. Cost: What a Run Actually Burns

Two cost modes:

Local model (32B+ on your GPU): the run costs electricity (~$0.10–$0.30 for a multi-minute agent session) plus your hardware amortization. The model is free. This is the sovereignty play. At the 32B tier you can run dozens of mechanical tickets a day for the price of watts.

Cloud model (Claude/GPT behind the agent): each run is a token bill. A simple issue might cost $0.05–$0.20; a stubborn one that retries ten times can hit $1–$3. At team scale — hundreds of issues a week — that is real money, but it is also potentially far cheaper than the engineer-hours it saves.

The honest framing: the agent does not change whether you pay (hardware or tokens). It changes what you get — unattended progress on tickets. The local route trades capital cost for zero marginal cost; the cloud route trades zero setup for per-run spend. Pick by whether you already own the GPU, and by how sensitive the code is.

14. How It Compares

| Tool | Best for | Local model support | The catch |
|------|----------|---------------------|------------|
| OpenHands | Autonomous issue→PR, async tasks | LiteLLM (Ollama, 100+) | Heavier setup; needs Docker |
| Aider | CLI pair-programming, git-first | Any OpenAI-compatible | No autonomous PR loop |
| Cline | VS Code multi-file editing | Ollama, LM Studio, 30+ | Editor-bound |
| Devin (closed) | Managed autonomous coding | No (cloud only) | Your code leaves via their infra |

OpenHands wins on autonomy + self-hostability combined. Nothing else open-source opens a real PR unattended and lets you keep the model local. Aider is lighter and git-native but stops at "here is a diff"; OpenHands goes to "here is a PR." Cline lives inside your editor but is not built for unattended async runs. Devin is the capability ceiling but the sovereignty floor.

15. Who Should (and Shouldn't) Use It

Use OpenHands if: you want an agent that closes issues end to end; you can self-host and supply a strong model (cloud key, or a 32B+ local model on real hardware); you review PRs carefully anyway; your code cannot leave your infrastructure.

Skip it if: you want lightweight in-editor completions (use Continue/Cline); you only have a 7B local model (it will frustrate you — the scaffold cannot compensate for weak weights); you need a managed, hands-off service (that is Devin, at the cost of data leaving your infra); you are not prepared to read every line of its PRs.

16. A Practical Self-Hosting Setup

For a team that wants the privacy win without the foot-guns, here is the configuration I would ship:

1. A dedicated host with a 4090-class GPU (or a Mac Studio for Apple-Silicon inference).
2. Ollama serving a 32B+ model (Q4) at localhost:11434.
3. OpenHands in Docker, pinned to a version, with the runtime image matching.
4. A scoped GitHub token (repo scope only) injected as a secret, never baked into the image.
5. The repo mounted read-write but specifically, never ~ or /.
6. Human review mandatory before any agent PR is merged — CI runs, a person approves.

This gives you Devin-class autonomy on your own metal, with your code never transiting a vendor. The marginal cost is electricity and a GPU you likely already own or can rent. The saved cost is the risk of your source code sitting on someone else's servers.

17. FAQ

Will it replace my engineers? No. It replaces the boring 30% — mechanical fixes, test writing, rename refactors — and frees humans for judgment. Treat its PRs as a junior's first draft.

Can it run fully offline? Yes, if the model backend is local Ollama and you use a scoped local GitHub token. The agent loop never needs the internet.

Why did it edit the wrong file? The issue was too vague, or the repo is a tangle only the original author understands. Tighten the spec (§7) and scope the branch.

Is my code safe with a cloud model? Not from the model provider — the issue text and possibly code snippets go to them. Use a local model for anything proprietary.

How big a GPU for local agents? 32B at Q4 wants ~24 GB (4090). 14B works for mechanical tasks on a 16 GB card but is hit-or-miss. Below that, it is a demo.

18. A Second Walkthrough: A Mechanical Refactor

The bug-fix run (§6) is the poster child. Here is a different shape — a rename refactor — that shows where the agent shines rather than merely copes.

Issue: "Rename the UserManager class to AccountService across the codebase. Update all references, imports, and tests. Do not change behavior."

What it did:

1. Grepped for UserManager — found it in 14 files (imports, instantiations, test mocks).
2. Edited each occurrence; the loop verified the file still parsed after each change.
3. Ran pytest — green, because it also renamed the test class reference.
4. Opened a PR titled "Rename UserManager → AccountService" with a one-line description and the test output pasted in.

Time: ~4 minutes. A human would take 10–15 (find all, edit all, run suite, open PR). This is the high-value case: verifiable, mechanical, multi-file, and exactly the kind of chore a senior dev begrudges. The agent does not need creativity here; it needs diligence, and diligence is what loops are good at.

Contrast with the bad case (§6): the difference is the issue, not the scaffold. A scoped, verifiable, behavior-preserving task = the agent looks brilliant. A vague, judgment-heavy task = it looks hopeless. The lesson repeats: the agent is a force multiplier on well-specified work, not a replacement for specification.

19. Measuring Whether It's Working for You

Before you wire OpenHands into a team workflow, you want a way to know if it is earning its keep — not just "it opened a PR" but "the PRs are good." A lightweight eval:

Sample 20 recent agent PRs. For each, did it resolve the issue correctly without breaking unrelated code? Tag yes/no.
Track the reject rate. If >40% of PRs are rejected or heavily edited, your issues are too vague or your model too small. Fix the input, not the agent.
Time saved, honestly. A PR that took the agent 6 minutes but you spent 25 reviewing is a net win over doing it yourself (10 min) only if it recurs often. For one-offs, do it yourself.
Model-swap A/B. Run the same class of ticket on a 32B local vs a frontier cloud key for a week. If the cloud closes 20% more and you are privacy-permitting, the cost may be worth it.

The goal is not "fully autonomous." It is "the repetitive 30% of tickets close themselves overnight, and I review in the morning." That is the realistic, valuable target — and it is reachable with the configurations in this article.

20. The Human-in-the-Loop Review Discipline

The single habit that determines whether OpenHands helps or hurts a team is the review gate. The agent opens a PR; a human decides if it merges. Skip the gate and you will, sooner or later, merge a PR that deletes a feature to "fix" a symptom.

The rule I ship with: the agent's PRs are drafts, never auto-merged. CI runs; a person approves. This is not paternalism — it is the same review you would give a junior. The agent is a fast junior who never sleeps and is occasionally confidently wrong.

What good review looks like: read the diff, not just the description. The description said "remove the isatty guard"; the diff also quietly changed a default timeout. Catching that second change is the whole job. A 30-second skim of the diff per PR is the price of the autonomy, and it is vastly cheaper than debugging a silent regression a week later.

Escalation discipline: if the same class of ticket fails twice, stop auto-running it and fix the spec (§7), not the agent. The agent is a mirror of your instructions; repeated failure is a signal your ticket was unclear, not that the tool is broken.

Why this scales trust. Teams that gate reviews properly end up trusting the agent with bigger tickets, because the gate proves the failures are caught. Teams that skip the gate lose trust after the first bad merge and ban the tool — throwing away the 80% of tickets it got right over the 20% it did not. The review gate is what makes the 80% sustainable. It is the difference between "we tried an agent and it broke prod" and "our agent closes a third of trivial tickets overnight."

21. Verdict

OpenHands is the strongest open-source autonomous coding agent you can self-host in 2026. With a frontier model behind it, it genuinely shortens the path from "bug reported" to "PR opened." With a tiny local model, it is a cautionary demo.

The limitations are real but bounded — and none of them are "your proprietary code leaked to a SaaS." Point it at your own hardware, keep the sandbox on, scope your tokens, and you have Devin-class autonomy with full data control. The model you plug in decides the quality; the architecture you choose decides the trust. OpenHands lets you pick both.

Related:

Ollama: Run LLMs on Your Own Machine — the local backend OpenHands can drive
DeepSeek V4: The MIT-Licensed Model That Fits on Your Desk — a local model strong enough to power the agent
n8n: Automation That Respects Your Data — orchestrate agent runs inside self-hosted workflows

"OpenHands: The Open-Source Autonomous Coding Agent That Opens Its Own PRs"