How to Develop with Auto AI Agents Using OpenHands

How to Develop with Auto AI Agents Using OpenHands

Most teams trying AI-assisted development hit the same wall: the assistant is good at snippets, but weak at end-to-end execution.

OpenHands is built for that gap. Instead of only suggesting code, it can work like an autonomous developer inside a sandbox: edit files, run commands, and iterate on tasks.

This article is a practical playbook for using OpenHands in real development workflows.

As of March 4, 2026, the OpenHands/OpenHands repository shows release 1.4.0 (published February 2026), and the docs cover CLI, local GUI, headless mode, and GitHub Action-based automation.

What OpenHands actually gives you

The OpenHands project offers several entry points:

1. CLI for terminal-first usage.
2. Local GUI for a browser-based experience on your machine.
3. Headless mode for scripts and CI.
4. GitHub Action workflows that can auto-attempt issue resolution.
5. SDK for composing your own agents in Python.

If your goal is “auto AI agent development” for a normal engineering team, the most practical path is:

1. Start local (openhands serve) to learn prompting and control cost.
2. Add repository customization (.openhands/).
3. Move repeatable tasks to headless mode.
4. Add GitHub Action triggers for issue-driven automation.

Step 1: Get it running locally in 10 minutes

From the OpenHands docs, the recommended installation path is uv:

uv tool install openhands --python 3.12
openhands serve

You can also run with a mounted current directory:

openhands serve --mount-cwd

If you prefer Docker directly, the docs provide a full command including published images and port 3000.

Why local first:

1. You can test prompts cheaply.
2. You can watch exactly what the agent is doing.
3. You can tighten sandbox and repo controls before CI automation.

Step 2: Treat repository onboarding as mandatory

OpenHands supports repository-level customization with a .openhands directory. This is not optional if you want reliable autonomous behavior.

Use it to define setup and quality gates.

Example .openhands/setup.sh:

#!/usr/bin/env bash
set -euo pipefail

# Keep setup explicit and reproducible
npm ci
bundle install

Example .openhands/pre-commit.sh:

#!/usr/bin/env bash
set -euo pipefail

npm run lint
npm test

This gives the agent a consistent boot path and prevents low-value commits that skip basic checks.

Step 3: Prompt for execution, not vibes

OpenHands docs are very clear here: better prompts are concrete, location-specific, and scoped.

Bad:

Improve authentication.

Good:

Add email/password login to src/api/auth.ts.
Use existing Postgres helper in src/db/index.ts.
Return JWT on success and 401 on failure.
Add tests in tests/auth.test.ts for success, bad password, and missing user.
Success criteria: npm test passes and /api/auth/login returns token for valid credentials.

A simple rule that works in practice:

1. Name files.
2. Define expected behavior.
3. Define “done” with commands/tests.
4. Keep each task small enough for one focused PR.

Step 4: Use the sandbox intentionally

OpenHands uses Docker sandboxing by default for local runs. That helps with isolation and repeatability.

If you want the agent to work against local code, mount only what you want changed.

For example, the docs support:

export SANDBOX_VOLUMES=$PWD:/workspace:rw

Or simply start with:

openhands serve --mount-cwd

Practical tip: do not mount your entire home directory. Give the agent the minimum writable surface area.

Step 5: Move repeatable work to headless mode

When a workflow becomes predictable, move it from interactive chat to headless automation.

Basic usage from docs:

openhands --headless -t "Add unit tests for user serializer"

Structured output mode:

openhands --headless --json -t "Fix flaky test in payment webhook" > output.jsonl

Important constraint from the docs: headless mode runs in always-approve mode. That means no interactive confirmation, so your prompt quality and sandbox boundaries matter even more.

Step 6: Add issue-driven automation in GitHub

OpenHands docs describe an automation flow using GitHub Action triggers:

1. Create or select an issue.
2. Add fix-me label, or comment with @openhands-agent.
3. Let the resolver attempt a fix and open/update a PR.
4. Review and iterate by commenting.

This is where “auto AI agent” starts feeling production-useful. You can turn backlog items into runnable attempts without manually starting each session.

A workflow that works for small teams

Here is a lightweight operating model:

1. Triage issue into a small, testable unit.
2. Add acceptance criteria and exact file context.
3. Trigger OpenHands (fix-me or headless task).
4. Review PR diff and test output.
5. Provide targeted follow-up comments.
6. Merge only after normal CI and human review.

The key is to treat OpenHands as a high-speed implementer, not as a final authority.

Common failure modes and how to avoid them

1. Task too large

Symptom: the agent drifts across architecture, creates noisy diffs, and burns tokens.

Fix: split into smaller prompts with clear success criteria.

2. Missing repository context

Symptom: wrong coding style, wrong folder placement, broken internal conventions.

Fix: add .openhands/setup.sh, .openhands/pre-commit.sh, and explicit prompt constraints.

3. Over-trusting autonomous runs

Symptom: PR looks plausible but breaks edge cases.

Fix: require tests and review like any other contributor.

4. Unsafe write scope

Symptom: unexpected file changes outside the target area.

Fix: constrain mounts and branch strategy.

Where OpenHands fits best

OpenHands is strongest when:

1. The task is bounded and testable.
2. Your repository has clear structure and checks.
3. You can provide concrete instructions.
4. You use automation for first-pass implementation, then keep human review in the loop.

It is less effective when the task is vague, political, or requires architectural decisions without constraints.

Final takeaway

If you want to “develop with auto AI agents,” the trick is not just installing OpenHands. The real leverage comes from process design:

1. good prompts,
2. controlled sandbox access,
3. repository customization,
4. automated issue-to-PR loops,
5. strict review gates.

Do that, and OpenHands becomes a practical multiplier instead of a novelty.

References

1. OpenHands GitHub Repository
2. OpenHands Docs: Introduction
3. OpenHands Docs: Local Setup
4. OpenHands Docs: Prompting Best Practices
5. OpenHands Docs: Repository Customization
6. OpenHands Docs: Headless Mode
7. OpenHands Docs: GitHub Action