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 Setup
1. Install Prerequisites
You'll need the following installed:
- Python 3.12 —
brew install [email protected] (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
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
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:
- Open the Microsoft Store app
- Search for "Ubuntu 22.04 LTS" or "Ubuntu"
- Click Install
- 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.
- Install Docker Desktop for Windows
- Open Docker Desktop > Settings > General
- Enable: "Use the WSL 2 based engine"
- Go to Settings > Resources > WSL Integration
- 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
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:
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
- Add your dependency in
pyproject.toml or use poetry add xxx
- Update the lock file:
poetry lock --no-update
Help
make help
Key Documentation Resources