A reasoning loop
A provider-agnostic LLM interface drives an agent that plans, acts, observes the result, and iterates. Every step is a typed event you can replay, log, or hook into.
Open source · AI-driven development
Software that writes
software.
OpenHands is an open-source project for running AI software-development agents. You give it a task in plain language; it reads your code, runs shell commands, edits files, browses the web, runs tests, and opens pull requests — inside a sandbox it can't escape.
This page is a plain-English map of what OpenHands is, how the pieces fit together, and how to run it. It was written and deployed by an OpenHands agent — the thing it describes.
- Python SDK
- Browser UI
- Sandboxed execution
- Bring your own LLM
- REST + WebSocket APIs
- Self-host or Cloud
01 — The idea
What OpenHands actually is
Not a chat window that suggests code, and not autocomplete. OpenHands is an agent: a reasoning loop with hands. The model decides what to do, a tool does it in a real environment, and the result goes back into the model's context — over and over, until the task is done or it needs you.
Real tools, real effects
Bash, file editing, browsing, terminal interaction, custom tools, and anything an MCP server exposes. The agent doesn't describe the change — it makes it.
An isolated workspace
Execution happens in a sandbox — Docker, a local process, or a remote machine — scoped to one repository or folder. The blast radius is the workspace you handed it.
The one-sentence version
OpenHands gives a capable LLM a sandbox, a terminal, a file editor and a browser, then lets it work a ticket end-to-end while you watch, steer, and review the diff.
Why teams reach for it
Delegation, not pair-programmingHand off a whole task, not a line of code.
Model freedomAny LiteLLM-supported provider, or local models via Ollama/vLLM.
Where you want itLaptop, container, VM, Kubernetes, or managed Cloud.
InspectabilityEvery action is an event with a diff you can review and revert.
02 — The shape of it
How the pieces fit together
The mental model that makes everything else click: the UI is separate from the backend that runs the agent. They talk over HTTP and WebSocket, so they can live on entirely different machines.
Swap the backendPoint Canvas at local, Docker, VM, Modal, or Cloud. Only where the agent runs changes.
Swap the UICanvas is one client. The same backend is reachable from the SDK, REST, WebSocket, or an OpenAI-compatible endpoint.
Swap the modelModel routing, fallback strategies and profile stores let you change brains without touching code.
03 — Five ways in
Pick the flavour that fits
OpenHands ships as a product family rather than a single app. They share the same engine; they differ in who runs it and who it's for.
Agent Canvas
The open-source browser client and control centre. Conversations, files, terminals, model
configuration, backends and automations in one place. It connects to one or more Agent
Server backends, and the agent-canvas launcher runs client + backend as an
all-in-one stack — npm or Docker gets you going in minutes.
Software Agent SDK
A composable Python library for building agents that work with code. Configure an LLM, pick or write an agent, give it tools, start a conversation. The same repository ships Agent Server, which exposes execution, conversations, tools and workspaces over REST and WebSocket.
OpenHands Cloud
The hosted commercial service at app.all-hands.dev. No infrastructure to run:
hosted execution, GitHub / GitLab / Bitbucket and Slack integrations, collaboration,
access controls, usage reporting and budget management. Sign in with your Git provider and
start.
OpenHands Enterprise
Commercial capabilities and support for organisations that need licensed self-hosting or managed deployment. Helm charts for Kubernetes, VM installs, SAML SSO, external Postgres, custom sandbox images, warm runtime pools and observability integrations.
Sandbox Server
The community-supported standalone API and sandbox control plane. Its job is narrow and useful: create and manage sandboxed environments where agents can safely work.
Local GUI & CLI (V0)
The earlier generation: a single-container local GUI and a terminal openhands
command. Still documented, but the project's direction is Agent Canvas and the SDK.
04 — Under the hood
What the agent can actually do
Tools are the verbs of the system. The SDK ships a default set — BashTool,
FileEditorTool and friends — and you can add your own or import a whole toolkit
over MCP.
Bash
Run any shell command: build, test, install, inspect logs, drive git.
File editor
Read, create and patch files with real diffs instead of whole-file rewrites.
Browser
Navigate the web to read docs, reproduce a bug, or verify a running app.
Interactive terminal
Drive REPLs and interactive CLIs — not just fire-and-forget commands.
Custom tools
Define typed tools for your own internal systems and APIs.
MCP servers
Discover and use tools from any Model Context Protocol server, automatically.
Task tracking
Break a large job into tracked steps so progress is visible and resumable.
Parallel execution
Run independent tool calls concurrently when one response asks for several.
Ask the agent
Send a side question mid-run without interrupting the main execution flow.
The loop, step by step
- Perceive. The agent gets your task plus the current repository context — files, config, and the skills and rules that match.
- Reason. The LLM plans, choosing which tool to call next and with what arguments.
- Act. The tool runs inside the sandbox: a command executes, a file changes, a page loads.
- Observe. Output and diffs become typed events appended to the conversation history.
- Repeat until the goal is met, then stop — or pause and ask you.
Guard-rails worth knowing
- Sandbox boundary. Filesystem and network access are limited to the workspace and the sandbox's policy.
- Context condenser. Long conversations are compressed so the agent keeps working instead of running out of tokens.
- Persistence & fork. Save a conversation, restore it, or branch it to explore a second option without contaminating the first.
- Hooks. Observe, log, block or rewrite agent actions at lifecycle points.
- Secrets registry. Hand the workspace environment variables and credentials without pasting them into prompts.
- Critic & iterative refinement. An LLM judge reviews actions and loops until a quality bar is met.
05 — Making it yours
Extending OpenHands
Out of the box the agent is competent. The interesting part is teaching it your conventions — and doing it once, in a file, instead of in every prompt.
Skills
Reusable instructions, domain knowledge and supporting files for the agent. Trigger them by keyword, by path glob (they load automatically whenever a matching file is touched), or apply them globally, per organisation, or per user.
keyword path-triggered org user global
Plugins
Bundle skills, hooks, MCP servers, agents and commands into one reusable package in the portable Agent Plugins format, so a single package works across every compatible client.
skills hooks MCP agents commands
Automations
Event- and schedule-driven runs: react to a webhook, a label, a Slack message or a cron tick. Pre-built automations cover common workflows, and you can sync definitions through Git.
webhooks cron pre-built git-synced
Repository customisation
A .openhands directory at the root of your repo tells the agent how to work in
this project — setup commands, conventions and context that should not live in a prompt.
AGENTS.md .openhands/
06 — Hands on
Get started in two minutes
The browser route needs no code. The SDK route is a handful of lines and one API key.
Option A — the browser
Install Agent Canvas (npm or Docker), open it, point it at a model and start a conversation. Or skip installation entirely and sign in to OpenHands Cloud.
shell
# No install, hosted — the fastest taste of OpenHands
open https://app.all-hands.dev
# Or run Agent Canvas yourself
npm install -g @openhands/agent-canvas
agent-canvasOption B — the SDK
Install uv, export a key for any LiteLLM-supported provider, and run a real
agent against your current directory.
hello_world.py
from openhands.sdk import LLM, Conversation
from openhands.sdk.agent import get_default_agent
llm = LLM(model="anthropic/claude-sonnet-4-5",
api_key=api_key, service_id="agent")
agent = get_default_agent(llm=llm, cli_mode=True)
conversation = Conversation(agent=agent, workspace=cwd)
conversation.send_message(
"Write 3 facts about this project into FACTS.txt.")
conversation.run()
The default agent brings BashTool, FileEditorTool and the rest of the
standard tool set. Swap the model string for any provider LiteLLM supports — or for a local
server such as Ollama, vLLM, LM Studio or SGLang.
07 — Where it earns its keep
Use cases that work today
The pattern is the same everywhere: a well-scoped, verifiable task with a clear definition of done, in a repository the agent can run.
Vulnerability remediation
Triage a CVE report, locate the vulnerable call sites, patch them, and open the PR.
Automated code review
Read a diff with fresh eyes on every pull request and leave actionable comments.
Automated QA testing
Write and repair tests, then run them until the suite is green.
Incident triage
Correlate logs, form a hypothesis, and check out the commit that broke it.
Dependency upgrades
Bump a library, fix the fallout, run the tests, and report what changed.
COBOL & Spark migrations
Mechanical, high-volume translation work — exactly what an agent is good at.
Two rules of thumb from the docs: give it a task you could describe to a competent new engineer, and make the finish line checkable — a passing test, a clean build, a diff you can review.
08 — Go deeper