How to Use OpenHands to Build Software with AI Agents

OpenHands is an open-source AI software engineering agent that can write code, run commands, browse the web, and debug projects directly on your machine. This guide shows you how to install OpenHands, connect a model, and run your first autonomous coding task safely.

What Is OpenHands?

OpenHands (formerly OpenDevin) gives a language model a real sandboxed workspace: a shell, a browser, a file editor, and the ability to execute code. Instead of copying snippets back and forth, you describe a task in plain English and the agent plans, edits files, runs tests, and iterates until the job is done.

How to Use OpenHands: Step by Step

1. Install the prerequisites

Make sure you have Python 3.12+, Docker, and a modern browser installed. Docker is required because OpenHands runs the agent inside an isolated container so it cannot damage your host system.

2. Install OpenHands

Clone the repository or install the package, then start the web UI with a single command. The first launch pulls the runtime Docker image, so allow a few minutes for the download.

3. Connect an LLM

Open the settings panel and add an API key from your preferred provider, or point OpenHands at a local model server. Choose a capable coding model, since the quality of the agent depends heavily on the underlying model.

4. Create your first workspace

Start a new session and give OpenHands a repository path or a fresh directory. The agent will index the files and build an internal understanding of the project structure.

5. Write a clear task prompt

Describe the outcome you want, not just the file to edit. For example: ‘Add pagination to the /users endpoint, write tests, and make sure the suite passes.’ Include acceptance criteria so the agent can self-verify.

6. Let the agent work and review

OpenHands will plan, edit files, run commands, and show every action in the interface. Watch the terminal output and diffs, and interrupt at any time if it goes off track.

7. Verify and export the changes

Review the final diff, run the test suite yourself, then commit the branch. You can copy the agent’s patch directly into your own workflow.

Tips for Getting the Most Out of OpenHands

• Keep tasks small and verifiable. One well-scoped ticket per session produces far better results than a vague mega-task.
• Enable the browser tool when a task requires reading documentation or checking a live site.
• Use a persistent Docker volume if you want workspaces to survive restarts.
• Always review generated code before merging; the agent is powerful but not infallible.

Final Thoughts

OpenHands removes the friction between an idea and a working result, whether you are automating research, writing code, or orchestrating multi-step AI workflows. Start with a small, concrete task, review every step the agent takes, and expand from there. With the workflow above you can go from installation to a finished, verified result in a single session.