Getting Started with OpenHands: Your AI Software Engineer

Introduction

OpenHands (formerly OpenDevin) is an open-source AI software engineer platform that can autonomously complete complex software development tasks. It combines code understanding, tool use, and task planning capabilities to automatically write code, run tests, fix bugs, and even deploy applications. In this tutorial, you'll learn how to set up and use OpenHands.

Prerequisites

• Docker installed (recommended)
• Python 3.10+ (alternative installation method)
• An LLM API key (OpenAI, Anthropic, or local model)

Installation

Method 1: Docker (Recommended)

# Pull the OpenHands image
docker pull openhands/openhands:latest

# Run OpenHands
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/workspace:/opt/openhands/workspace" \
  -e LLM_API_KEY="your-api-key" \
  -p 3000:3000 \
  openhands/openhands:latest

Method 2: pip

pip install openhands-ai

# Run OpenHands
python -m openhands --workspace ./my-project

Quick Start

Step 1: Start OpenHands

# Using Docker
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/workspace:/opt/openhands/workspace" \
  -e LLM_API_KEY="sk-..." \
  -p 3000:3000 \
  openhands/openhands:latest

Step 2: Open the Web Interface

Visit http://localhost:3000 in your browser.

Step 3: Start a Conversation

> 请帮我创建一个 Python Flask API，包含用户注册和登录功能

> 请修复这个 bug：用户登录时出现 500 错误

> 请为这个函数添加单元测试

Core Concepts

Agent Architecture

OpenHands uses a multi-agent architecture:

• Planner Agent — Decomposes complex tasks into steps
• Coder Agent — Writes and modifies code
• Reviewer Agent — Code quality checks
• Tester Agent — Writes and runs tests

Tool System

OpenHands provides built-in tools:

Tool	Function
Bash	Execute shell commands
Editor	Read and edit files
IPython	Execute Python code
Browser	Web browsing and interaction
Git	Version control operations

Example 1: Creating a New Project

User: 帮我创建一个 React + TypeScript 的待办事项应用，包含以下功能：
- 添加、删除、完成待办事项
- 本地存储数据
- 响应式设计

OpenHands:
1. 初始化 React + TypeScript 项目
2. 创建组件结构（TodoList, TodoItem, TodoForm）
3. 实现状态管理（useState, useEffect）
4. 添加本地存储持久化
5. 编写 CSS 样式
6. 运行测试验证功能

Example 2: Fixing a Bug

User: 我的 Python 脚本在读取 CSV 文件时报错：
FileNotFoundError: [Errno 2] No such file or directory: 'data.csv'

OpenHands:
1. 分析错误信息
2. 检查文件路径
3. 发现路径问题：使用了相对路径但工作目录不同
4. 修复代码：使用 os.path.abspath 获取绝对路径
5. 运行测试验证修复

Example 3: Building a Full Stack App

User: 创建一个完整的电商网站，包含：
- 前端：React + Tailwind CSS
- 后端：FastAPI
- 数据库：PostgreSQL
- 用户认证：JWT

OpenHands will:
1. Plan the architecture
2. Create the project structure
3. Set up the database schema
4. Implement the backend API
5. Build the frontend components
6. Add authentication
7. Test the complete application

Advanced Usage

Using Custom LLMs

# Use a local model with Ollama
export LLM_API_KEY="ollama"
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL="llama3"

# Run OpenHands
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LLM_API_KEY="ollama" \
  -e LLM_BASE_URL="http://host.docker.internal:11434/v1" \
  -e LLM_MODEL="llama3" \
  openhands/openhands:latest

Using Multiple Agents

# In the OpenHands interface, you can specify:
# "Use a planning agent to break down this task, then a coding agent to implement it"

# OpenHands will automatically coordinate multiple agents

Working with Existing Codebases

# Clone your repository
git clone https://github.com/your-org/your-repo.git

# Run OpenHands with the codebase
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/your-repo:/opt/openhands/workspace" \
  -e LLM_API_KEY="your-api-key" \
  -p 3000:3000 \
  openhands/openhands:latest

Best Practices

1. Be Specific in Your Requests

# Good
"Create a Flask API endpoint POST /users that validates email format and stores users in SQLite"

# Less effective
"Make a user system"

2. Iterate in Small Steps

# Better to break down:
1. "Create a Flask app with a /users endpoint"
2. "Add email validation to the /users endpoint"
3. "Add database storage for users"
4. "Add unit tests for the /users endpoint"

3. Review Generated Code

OpenHands is powerful but not perfect. Always:

• Review generated code before committing
• Run tests to verify functionality
• Check for security issues

4. Use the Browser Tool for Research

"Research the latest best practices for React state management in 2026"

OpenHands can browse the web and incorporate current information.

Troubleshooting

Docker Socket Permission Issues

# Add your user to the docker group
sudo usermod -aG docker $USER

# Or run with sudo (less secure)
sudo docker run ...

LLM API Key Issues

# Verify your API key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

Workspace Not Persisting

# Make sure to mount the workspace volume
-v "$(pwd)/workspace:/opt/openhands/workspace"

Resources

• OpenHands Documentation
• OpenHands GitHub
• OpenHands Discord
• All-Hands AI

Summary

In this tutorial, you learned:

1. How to install OpenHands using Docker or pip
2. How to start a conversation with your AI software engineer
3. The core concepts: multi-agent architecture and tool system
4. Examples of creating projects, fixing bugs, and building full-stack apps
5. Advanced usage: custom LLMs, multiple agents, existing codebases
6. Best practices for effective use
7. Troubleshooting common issues

OpenHands provides a powerful, open-source AI software engineer that can handle complex development tasks autonomously. Start with simple tasks and gradually work up to more complex projects as you learn the system's capabilities.