OpenHands

What this article covers

• What OpenHands is and what it’s built for.
• How to start OpenHands with Docker.
• How to connect a GitHub repository.
• What a typical workflow with OpenHands looks like.
• When OpenHands makes sense and where it hits limitations.

Introduction

OpenHands is an open-source project for AI-assisted software development. An agent can read code, make edits, suggest commits, and generate pull requests. The key difference: OpenHands works directly inside a real repository, reading files, running tests, and processing code feedback.

OpenHands at a glance

OpenHands consists of a container running the agent and a web interface. You connect a GitHub repo or local folder, then give the agent tasks in plain language. It plans which files to open, what changes to make, and how to test them.

Installation

The quickest way is Docker:

docker run -it --rm \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.18-nikolaik \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:0.18

Once it starts, navigate to http://localhost:3000. For older images or other versions, check the latest documentation.

Setting up a GitHub token

Working with repositories requires a GitHub token:

export GITHUB_TOKEN="your-token"

With this, OpenHands can create commits, branches, and pull requests. Without a token, it only works locally.

Getting started: giving your first task

1. Open http://localhost:3000.
2. Connect your repository or select a local folder.
3. Enter a task, such as: “Add a function that validates email addresses.”
4. Wait while the agent creates and executes a plan.
5. Review the proposed changes.

When OpenHands is useful

Use case	Benefit
Refactoring	Clean up and improve existing code
Feature implementation	Build small features from descriptions
Documentation	Add code comments and update README files
Learning	Follow step by step how an agent approaches code

Common pitfalls

• Security - OpenHands executes code. Only run it in isolated repositories or Docker containers.
• Token permissions - Your GitHub token needs appropriate permissions to create commits and pull requests.
• Cost and time - Large tasks require many model calls and take a long time to complete.

Further reading

• AutoGen
• What is an AI agent?
• AI PC beginner’s guide

FAQ - Common questions

Is OpenHands free?

Yes, the open-source project is free. Costs only occur when using model APIs or cloud hosting.

Can I run OpenHands locally?

Yes, with Docker. This is the recommended way to try it out.

Do I need GitHub?

No, local folders work too. For real project work, a GitHub repository is convenient.

Sources

• OpenHands GitHub
• OpenHands Documentation