← Back to Blog

Self-Host OpenHands v1.7.0: Your Open-Source AI Coding Agent (Step-by-Step Guide)

2026-05-01

What is OpenHands?

OpenHands is the open-source alternative to Claude Code, Codex, and Cursor — a platform where AI agents write code, run terminal commands, browse the web, and manage files autonomously. Think of it as a self-hosted AI developer that works with any LLM (Claude, GPT, DeepSeek, local models via Ollama).

With 72,500+ GitHub stars and trusted by teams at Netflix, Amazon, Apple, and NVIDIA, it's the most popular open-source AI coding platform available.

What's new in v1.7.0 (Released May 1, 2026)

This release, published just hours ago, brings several improvements:

  • LLM model display on conversation cards — always know which model is working
  • KVM acceleration for sandbox containers (SANDBOX_KVM_ENABLED) — dramatically faster code execution
  • MCP-native search — Tavily search key moved to MCP settings, aligning with the MCP ecosystem standard
  • Exposed SDK settings schema — easier programmatic agent configuration
  • Security fixes — multiple CVEs resolved through dependency updates
  • Numerous UI fixes — smoother experience across the board

Prerequisites

  • A Linux VPS or local machine with Docker installed
  • 4 GB RAM minimum (8 GB recommended)
  • An API key for your preferred LLM (Anthropic, OpenAI, or any OpenAI-compatible provider)

Method 1: Quick Start with Docker (Recommended)

The fastest way to get OpenHands running:

# Pull the latest image
docker pull ghcr.io/openhands/openhands:latest

# Run OpenHands GUI
docker run -it --rm --pull=always \
  -e LLM_API_KEY="sk-ant-..." \
  -e LLM_MODEL="claude-sonnet-4-20250514" \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/openhands/openhands:latest

Open http://localhost:3000 in your browser, and you're ready to go.

Pro tip: Add --gpus all if you have an NVIDIA GPU and want to use local models via Ollama.

Method 2: Using the CLI Launcher with uv

If you prefer a Python-native installation:

# Install OpenHands via uv
uv tool install openhands --python 3.12

# Launch the GUI server
openhands serve

# With GPU support
openhands serve --gpu

# Mount your current directory
openhands serve --mount-cwd

Method 3: Docker Compose for Production

For a production setup with persistent storage:

services:
  openhands:
    image: ghcr.io/openhands/openhands:latest
    container_name: openhands
    ports:
      - "3000:3000"
    environment:
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_MODEL=claude-sonnet-4-20250514
      - AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server
      - AGENT_SERVER_IMAGE_TAG=1.19.1-python
      - LOG_ALL_EVENTS=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - openhands_data:/.openhands
      - ./workspace:/workspace
    restart: unless-stopped

volumes:
  openhands_data:

docker compose up -d

Connecting to Different LLMs

For OpenRouter or OpenAI-compatible providers, also set LLM_BASE_URL.

Pro Tips

  1. Start with Claude Sonnet — best results for code generation
  2. Mount your project directory with --mount-cwd
  3. Enable KVM (SANDBOX_KVM_ENABLED=true) if supported — speeds up sandbox execution
  4. Use CLI mode for automation: openhands run --task "fix the bug in src/main.rs"
  5. Configure MCP search in Settings for autonomous web browsing

Troubleshooting

  • GUI doesn't load → Check if port 3000 is free. Run docker ps.
  • No internet access → Ensure outbound access and no firewall blocking the container.
  • Docker-in-Docker issues → The Docker socket mount is required for sandbox containers.
  • Out of memory → Needs ~4 GB RAM. Use a lightweight model on small VPS.

OpenHands v1.7.0 was released on May 1, 2026 under the MIT license. GitHub | Docs