How to install OpenHands locally or with Docker: GitHub repo and first agent task

Install OpenHands, wire GitHub and an LLM, then let the agent fix one small issue you can review.

The first hour with OpenHands (formerly OpenDevin) usually breaks on Docker or Python prerequisites, a missing LLM API key, or a GitHub personal access token (PAT) with too little scope—not on the prompt. Start the Web UI with Docker Compose or from source per official docs, clone your repo into the workspace, then let the agent finish one reviewable small fix.

The query is how to install OpenHands and connect GitHub. This page follows All-Hands-AI docs at docs.all-hands.dev and the All-Hands-AI/OpenHands repository for install, configuration, and Git integration. It is an open-source agent platform, not this site’s meeting product. For a short huddle to walk a diff, open a room on wbmeet; see how to create and join a room.

Who OpenHands is for

OpenHands is an open-source AI software engineering agent: it reads repos, edits files, runs terminal commands, and uses a browser inside a sandbox to execute multi-step tasks from natural language. You need a supported LLM provider API key (Anthropic, OpenAI, etc.—see the current official list) and sensible repo access policy.

Install with Docker or locally, open the Web UI

1. 1

   Prepare Docker and Git

   Official paths assume Docker Desktop or a compatible engine on Linux, macOS, or WSL2. Confirm docker and git work in a terminal. Source installs must match README Python/Node versions.

2. 2

   Clone and start per README

   Clone All-Hands-AI/OpenHands, then run Docker Compose (docker compose up or the documented make target). First pull can take a while. Open the local URL from docs (often http://localhost:3000 or the current default port).

3. 3

   Configure LLM settings

   In the Web UI Settings or environment (e.g. LLM_API_KEY and model id in .env / compose), wire at least one supported LLM. Never commit keys to Git.

4. 4

   Check sandbox and network

   Agents run commands inside containers. Corporate proxies may need troubleshooting steps from docs. Use a test fork for the first hour, not production main.

Connect a GitHub repository

1. 1

   Create a least-privilege PAT

   GitHub → Settings → Developer settings → Personal access tokens. Private repos usually need repo scope. Paste the token only into OpenHands settings or a local secrets file.

2. 2

   Add the repo in OpenHands

   Use Connect GitHub / import repository in the UI with PAT or OAuth if your build supports it. Wait for the workspace clone before sending tasks.

3. 3

   Verify branch and permissions

   Confirm branch (e.g. main or a feature branch). Org SSO may require authorizing the PAT on GitHub. Without push access, you commit or push manually from your machine.

First agent task: fix a small issue

1. 1

   Pick a reversible issue

   Examples: README typo, unused import, or one failing unit test. State path and outcome: “Fix the lint error in src/foo.ts without changing public API.”

2. 2

   Approve terminal steps and diffs

   Review the plan, file diffs, and terminal output. Manually approve install or git push commands in the first hour.

3. 3

   Validate locally, then commit

   Run npm test, pytest, or your CI locally. Open a PR or commit when satisfied. If the agent drifts, reset the workspace with Git and shrink the prompt.

# First hour · OpenHands · 2026-09
# git clone https://github.com/All-Hands-AI/OpenHands
# docker compose up  →  Web UI (see docs for port)
# Settings: LLM_API_KEY + model id
# GitHub PAT (repo scope) → clone your fork
# Task: fix one lint/test issue → review diff → run tests

Docker vs source

Official path: install OpenHands → configure LLM → GitHub PAT → small task with reviewed diff and local tests. Trust docs.all-hands.dev and your deployed version.

Does OpenHands upload my code?

LLM calls send context to your chosen provider; the sandbox still holds a clone locally. Use private deployments and approved models for sensitive repos.

Vs IDE agents

OpenHands is a standalone Web/sandbox repo agent; editor Copilots stay in the IDE. They complement each other.

Not a meeting-product guide

Only OpenHands’ first hour. Short whiteboard call: wbmeet and when not to open another heavy meeting app.

Questions worth checking