OpenHands/Development.md

Development Guide

This guide is for people working on OpenHands and editing the source code. If you wish to contribute your changes, check out the CONTRIBUTING.md on how to clone and setup the project initially before moving on. Otherwise, you can clone the OpenHands project directly.

Choose Your Setup

Select your operating system to see the specific setup instructions:

• macOS
• Linux
• Windows WSL
• Dev Container
• Developing in Docker
• No sudo access?

---

macOS Setup

1. Install Prerequisites

You'll need the following installed:

• Python 3.12 — brew install python@3.12 (see the official Homebrew Python docs for details). Make sure python3.12 is available in your PATH (the make build step will verify this).
• Node.js >= 22 — brew install node
• Poetry >= 1.8 — brew install poetry
• Docker Desktop — brew install --cask docker
  • After installing, open Docker Desktop → Settings → Advanced → Enable "Allow the default Docker socket to be used"

2. Build and Setup the Environment

make build

3. Configure the Language Model

OpenHands supports a diverse array of Language Models (LMs) through the powerful litellm library.

For the V1 web app, start OpenHands and configure your model and API key in the Settings UI.

If you are running headless or CLI workflows, you can prepare local defaults with:

make setup-config

Note on Alternative Models: See our documentation for recommended models.

4. Run the Application

# Run both backend and frontend
make run

# Or run separately:
make start-backend  # Backend only on port 3000
make start-frontend # Frontend only on port 3001

These targets serve the current OpenHands V1 API by default. In the codebase, make start-backend runs openhands.server.listen:app, and that app includes the openhands/app_server V1 routes unless ENABLE_V1=0.

---

Linux Setup

This guide covers Ubuntu/Debian. For other distributions, adapt the package manager commands accordingly.

1. Install Prerequisites

# Update package list
sudo apt update

# Install system dependencies
sudo apt install -y build-essential curl netcat software-properties-common

# Install Python 3.12
# Ubuntu 24.04+ and Debian 13+ ship with Python 3.12 — skip the PPA step if
# python3.12 --version already works on your system.
# The deadsnakes PPA is Ubuntu-only and needed for Ubuntu 22.04 or older:
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-dev python3.12-venv

# Install Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Add Poetry to your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Install Docker
# Follow the official guide: https://docs.docker.com/engine/install/ubuntu/
# Quick version:
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
# Log out and back in for Docker group changes to take effect

2. Build and Setup the Environment

make build

3. Configure the Language Model

See the macOS section above for guidance: configure your model and API key in the Settings UI.

4. Run the Application

# Run both backend and frontend
make run

# Or run separately:
make start-backend  # Backend only on port 3000
make start-frontend # Frontend only on port 3001

---

Windows WSL Setup

WSL2 with Ubuntu is recommended. The setup is similar to Linux, with a few WSL-specific considerations.

1. Install WSL2

Option A: Windows 11 (Microsoft Store) The easiest way on Windows 11:

1. Open the Microsoft Store app
2. Search for "Ubuntu 22.04 LTS" or "Ubuntu"
3. Click Install
4. Launch Ubuntu from the Start menu

Option B: PowerShell

# Run this in PowerShell as Administrator
wsl --install -d Ubuntu-22.04

After installation, restart your computer and open Ubuntu.

2. Install Prerequisites (in WSL Ubuntu)

Follow Step 1 from the Linux setup to install system dependencies, Python 3.12, Node.js, and Poetry. Skip the Docker installation — Docker is provided through Docker Desktop below.

3. Configure Docker for WSL2

1. Install Docker Desktop for Windows
2. Open Docker Desktop > Settings > General
3. Enable: "Use the WSL 2 based engine"
4. Go to Settings > Resources > WSL Integration
5. Enable integration with your Ubuntu distribution

Important: Keep your project files in the WSL filesystem (e.g., ~/workspace/openhands), not in /mnt/c. Files accessed via /mnt/c will be significantly slower.

4. Build and Setup the Environment

make build

5. Configure the Language Model

See the macOS section above for the current V1 guidance: configure your model and API key in the Settings UI for the web app, and use make setup-config only for headless or CLI workflows.

6. Run the Application

# Run both backend and frontend
make run

# Or run separately:
make start-backend  # Backend only on port 3000
make start-frontend # Frontend only on port 3001

Access the frontend at http://localhost:3001 from your Windows browser.

---

Dev Container

There is a dev container available which provides a pre-configured environment with all the necessary dependencies installed if you are using a supported editor or tool. For example, if you are using Visual Studio Code (VS Code) with the Dev Containers extension installed, you can open the project in a dev container by using the Dev Container: Reopen in Container command from the Command Palette (Ctrl+Shift+P).

---

Developing in Docker

If you don't want to install dependencies on your host machine, you can develop inside a Docker container.

Quick Start

make docker-dev

For more details, see the dev container documentation.

Alternative: Docker Run

If you just want to run OpenHands without setting up a dev environment:

make docker-run

If you don't have make installed, run:

cd ./containers/dev
./dev.sh

---

Develop without sudo access

If you want to develop without system admin/sudo access to upgrade/install Python and/or NodeJS, you can use conda or mamba to manage the packages for you:

# Download and install Mamba (a faster version of conda)
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

# Install Python 3.12, nodejs, and poetry
mamba install python=3.12
mamba install conda-forge::nodejs
mamba install conda-forge::poetry

---

Running OpenHands with OpenHands

You can use OpenHands to develop and improve OpenHands itself!

Quick Start

export INSTALL_DOCKER=0
export RUNTIME=local
make build && make run

Access the interface at:

• Local development: http://localhost:3001
• Remote/cloud environments: Use the appropriate external URL

For external access:

make run FRONTEND_PORT=12000 FRONTEND_HOST=0.0.0.0 BACKEND_HOST=0.0.0.0

---

LLM Debugging

If you encounter issues with the Language Model, enable debug logging:

export DEBUG=1
# Restart the backend
make start-backend

Logs will be saved to logs/llm/CURRENT_DATE/ for troubleshooting.

---

Testing

Unit Tests

poetry run pytest ./tests/unit/test_*.py

---

Adding Dependencies

1. Add your dependency in pyproject.toml or use poetry add xxx
2. Update the lock file: poetry lock --no-update

---

Using Existing Docker Images

To reduce build time, you can use an existing runtime image:

export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/openhands/runtime:1.2-nikolaik

---

Help

make help

---

Key Documentation Resources

• /README.md: Main project overview, features, and basic setup instructions
• /Development.md (this file): Comprehensive guide for developers working on OpenHands
• /CONTRIBUTING.md: Guidelines for contributing to the project, including code style and PR process
• DOC_STYLE_GUIDE.md: Standards for writing and maintaining project documentation
• /openhands/app_server/README.md: Current V1 application server implementation and REST API modules
• /frontend/README.md: Frontend React application setup and development guide
• /containers/README.md: Information about Docker containers and deployment
• /tests/unit/README.md: Guide to writing and running unit tests
• OpenHands/benchmarks: Documentation for the evaluation framework and benchmarks
• /skills/README.md: Information about the skills architecture and implementation
• /openhands/runtime/README.md: Documentation for the runtime environment and execution model