Docker Setup & First Run

OpenHands runs every agent session inside an isolated Docker container. This means the agent can install packages, execute scripts, and modify files without touching your host system. Pull the image, mount your project, and access the web UI.

What you'll learn

• Docker-native: each agent session runs in its own container with full filesystem isolation
• Mount your project with -v $(pwd):/workspace to give the agent access to your code
• Web UI at localhost:3000 for managing agents, conversations, and settings

Build it

Pull the official image and start the container with your local project directory mapped. Make sure to pass your Anthropic API key through the environment variable so the agent can interact with the language model.

docker pull ghcr.io/openhands/openhands

docker run -d --name openhands \
  -p 3000:3000 \
  -v $(pwd):/workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LLM_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/openhands/openhands

Open http://localhost:3000. The web UI loads and you can start your first agent session.

What goes wrong

Mistake	How you notice it	The fix
Docker socket not mounted	Agent cannot execute commands	Mount /var/run/docker.sock
API key not set	Agent fails to call the model	Pass via LLM_API_KEY env var

Next: Web UI & Agent Canvas