# OpenHands AI Developer

## Overview

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (formerly OpenDevin) is an open-source platform for autonomous AI software development agents. With 65K+ GitHub stars, it has become one of the most popular tools for delegating real programming tasks to AI — writing code, fixing bugs, resolving GitHub issues, running shell commands, browsing the web, and interacting with your codebase end-to-end.

Unlike typical code-completion tools, OpenHands runs an **agentic loop**: it receives a task, plans, writes code, executes it, observes the output, and iterates — all without human intervention. It supports dozens of LLM backends including OpenAI, Anthropic Claude, Google Gemini, and locally-hosted models via Ollama or vLLM.

**Why Clore.ai for OpenHands?**

* OpenHands itself is CPU-based and does not require a GPU
* However, pairing it with a **local LLM** (Ollama, vLLM) on the same server eliminates API costs and latency
* Clore.ai's affordable GPU servers let you run both OpenHands and a local model for as little as **$0.20–$0.35/hr**
* You get persistent workspace storage, Docker-in-Docker support, and full root access
* Ideal for long-running autonomous tasks that would be expensive via cloud LLM APIs

**Typical use cases on Clore.ai:**

* Autonomous code generation from a spec or issue description
* Bulk refactoring large codebases
* Running OpenHands + Ollama together for 100% offline agentic development
* CI/CD task automation without API costs

***

## Requirements

OpenHands requires Docker socket access and runs a sandboxed runtime container internally. The following table covers recommended configurations on Clore.ai:

| Configuration                   | GPU            | VRAM  | RAM   | Storage | Est. Price      |
| ------------------------------- | -------------- | ----- | ----- | ------- | --------------- |
| **API-only (no local LLM)**     | Any / CPU-only | N/A   | 8 GB  | 20 GB   | \~$0.05–0.10/hr |
| **+ Ollama (Llama 3.1 8B)**     | RTX 3090       | 24 GB | 16 GB | 40 GB   | \~$0.20/hr      |
| **+ Ollama (Qwen2.5 32B)**      | RTX 4090       | 24 GB | 32 GB | 60 GB   | \~$0.35/hr      |
| **+ vLLM (Llama 3.1 70B)**      | A100 80GB      | 80 GB | 64 GB | 100 GB  | \~$1.10/hr      |
| **+ vLLM (Llama 3.3 70B INT4)** | RTX 4090       | 24 GB | 32 GB | 80 GB   | \~$0.35/hr      |

> **Note:** If you only use OpenAI/Anthropic/Gemini APIs, any server with ≥8 GB RAM works. GPU is only needed if you want to run a local LLM on the same machine. See the [GPU Comparison Guide](/guides/getting-started/gpu-comparison.md) for more details.

**Software requirements on the Clore.ai server:**

* Docker Engine (pre-installed on all Clore.ai images)
* NVIDIA Container Toolkit (pre-installed on GPU images)
* Docker socket accessible at `/var/run/docker.sock`
* Outbound internet access for pulling GHCR images

***

## Quick Start

### Step 1: Select and Connect to a Clore.ai Server

In the [Clore.ai marketplace](https://clore.ai), filter servers by:

* RAM ≥ 16 GB (for local LLM combo)
* Docker: ✓ enabled
* Choose your preferred GPU if using a local model

Connect via SSH once the server is provisioned:

```bash
ssh root@<server-ip> -p <port>
```

### Step 2: Verify Docker Is Running

```bash
docker info
ls -la /var/run/docker.sock
```

Both commands should succeed. If Docker socket is missing, contact Clore.ai support or choose a different image.

### Step 3: Pull and Run OpenHands

```bash
# Set workspace directory
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# Run OpenHands (pulls latest 0.38 image from GHCR)
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Step 4: Access the Web UI

The UI is available at `http://<server-ip>:3000`

> **Clore.ai Port Forwarding:** In the Clore.ai dashboard, make sure port `3000` is forwarded/exposed in your server configuration. Some templates restrict external ports — check the "Ports" section in your server details.

On first launch, OpenHands will prompt you to configure an LLM provider.

### Step 5: Configure Your LLM

In the web UI settings:

* **Provider:** Select OpenAI, Anthropic, Google, or Custom
* **API Key:** Enter your API key
* **Model:** e.g., `gpt-4o`, `claude-3-5-sonnet-20241022`, or `ollama/llama3.1`

For local Ollama (see GPU Acceleration section below), use:

* Provider: `ollama`
* Base URL: `http://host.docker.internal:11434`
* Model: `ollama/llama3.1:8b`

***

## Configuration

### Environment Variables

OpenHands can be configured entirely via environment variables passed to `docker run`:

```bash
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_BASE_URL="" \
  -e SANDBOX_TIMEOUT=120 \
  -e MAX_ITERATIONS=100 \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

| Variable          | Description                                                    | Default          |
| ----------------- | -------------------------------------------------------------- | ---------------- |
| `LLM_MODEL`       | Model identifier (e.g. `gpt-4o`, `claude-3-5-sonnet-20241022`) | Set in UI        |
| `LLM_API_KEY`     | API key for the LLM provider                                   | Set in UI        |
| `LLM_BASE_URL`    | Custom base URL (for Ollama, vLLM, LiteLLM)                    | Provider default |
| `SANDBOX_TIMEOUT` | Agent sandbox timeout in seconds                               | `120`            |
| `MAX_ITERATIONS`  | Max agentic loop iterations per task                           | `100`            |
| `SANDBOX_USER_ID` | UID to run sandbox as (use `$(id -u)`)                         | `0`              |
| `LOG_ALL_EVENTS`  | Enable verbose event logging (`true`/`false`)                  | `false`          |

### Persistent Configuration File

You can persist settings by mounting a config directory:

```bash
mkdir -p /opt/openhands/config

docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/config:/app/config \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Running in Background (Detached Mode)

For long-running sessions on Clore.ai:

```bash
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  --restart unless-stopped \
  --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=your_api_key_here \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

# View logs
docker logs -f openhands
```

***

## GPU Acceleration (Local LLM Integration)

While OpenHands itself doesn't use the GPU, combining it with a **local LLM** running on Clore.ai's GPU gives you a powerful, cost-effective, API-free autonomous agent.

### Option A: OpenHands + Ollama (Recommended for Beginners)

Run Ollama first, then point OpenHands at it:

```bash
# 1. Start Ollama (see Ollama guide for full details)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. Pull a coding-optimized model
docker exec ollama ollama pull qwen2.5-coder:7b
# Or for more power:
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. Start OpenHands pointing to Ollama
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=ollama/qwen2.5-coder:7b \
  -e LLM_BASE_URL=http://host.docker.internal:11434 \
  -e LLM_API_KEY=ollama \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> See the full [Ollama guide](/guides/language-models/ollama.md) for model selection, performance tuning, and GPU configuration.

### Option B: OpenHands + vLLM (High Performance)

For maximum throughput with larger models:

```bash
# 1. Start vLLM with a coding model
docker run -d \
  --name vllm \
  --gpus all \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.92

# Wait for model to load (~2-5 min)
docker logs -f vllm | grep "Application startup"

# 2. Start OpenHands with vLLM backend
docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=/opt/workspace \
  -e LLM_MODEL=openai/Qwen/Qwen2.5-Coder-32B-Instruct \
  -e LLM_BASE_URL=http://host.docker.internal:8000/v1 \
  -e LLM_API_KEY=none \
  -v /opt/workspace:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> See the [vLLM guide](/guides/language-models/vllm.md) for full setup, quantization options, and multi-GPU configurations.

### Recommended Local Models for Coding

| Model                   | Size | Min VRAM | Quality |
| ----------------------- | ---- | -------- | ------- |
| `qwen2.5-coder:7b`      | 7B   | 8 GB     | ★★★☆☆   |
| `deepseek-coder-v2:16b` | 16B  | 12 GB    | ★★★★☆   |
| `qwen2.5-coder:32b`     | 32B  | 24 GB    | ★★★★☆   |
| `llama3.1:70b`          | 70B  | 48 GB    | ★★★★★   |

***

## Tips & Best Practices

### 1. Use Workspace Mounts Wisely

Mount your actual project directory as the workspace so OpenHands can directly edit your files:

```bash
export WORKSPACE_BASE=/opt/my-project
git clone https://github.com/your/repo $WORKSPACE_BASE
```

### 2. Task Prompting for Best Results

OpenHands works best with specific, actionable prompts:

```
✅ Good: "Fix the authentication bug in src/auth/login.py where JWT tokens 
         expire immediately. The issue is in the token expiration calculation."

❌ Poor: "Fix the bug"
```

### 3. Monitor Resource Usage

```bash
# Watch GPU and memory usage
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. Set Iteration Limits

Prevent runaway agents from consuming too many API tokens:

```bash
-e MAX_ITERATIONS=50  # Limit to 50 steps per task
```

### 5. GitHub Integration

OpenHands can resolve GitHub issues directly. Configure in the UI:

* GitHub Token: Your personal access token with `repo` scope
* OpenHands will clone the repo, fix the issue, and create a PR

### 6. Cost Estimation

For API-based LLMs, estimate cost per task:

* Simple bug fix: \~$0.05–0.15 (Claude Haiku/GPT-4o-mini)
* Complex feature: \~$0.50–2.00 (Claude Sonnet/GPT-4o)
* For 100+ tasks/day, local LLM on Clore.ai pays for itself

***

## Troubleshooting

### Docker Socket Permission Denied

```bash
# Error: permission denied while trying to connect to Docker daemon
# Fix: ensure the socket is accessible
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker ...

# Add your user to docker group if needed
usermod -aG docker $USER
# Then restart the shell or use: newgrp docker
```

### Sandbox Container Fails to Start

```bash
# Check if the runtime image is accessible
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# Check GHCR rate limits (may need to authenticate)
docker login ghcr.io
```

### Port 3000 Not Accessible

```bash
# Verify the container is running and port is bound
docker ps | grep openhands
docker port openhands

# Check Clore.ai firewall — ensure port 3000 is in your port mapping
# In Clore.ai dashboard: Server → Ports → Add 3000:3000
```

### LLM Connection Errors with Ollama

```bash
# Test Ollama is reachable from OpenHands container
docker exec openhands curl http://host.docker.internal:11434/api/tags

# If it fails, verify --add-host flag was included in docker run
# Also check Ollama container is running:
docker ps | grep ollama
docker logs ollama | tail -20
```

### Agent Loops Indefinitely

```bash
# Reduce max iterations
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# Or set a timeout
-e SANDBOX_TIMEOUT=60
```

### Out of Memory (OOM)

```bash
# Check memory usage
free -h
docker stats

# If running local LLM, try a smaller model
docker exec ollama ollama pull qwen2.5-coder:3b

# Or use quantized version (less VRAM)
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M
```

***

## Further Reading

* [OpenHands GitHub Repository](https://github.com/All-Hands-AI/OpenHands) — Source code, issues, and releases
* [OpenHands Documentation](https://docs.all-hands.dev) — Official docs including LLM configuration
* [Ollama on Clore.ai](/guides/language-models/ollama.md) — Run local LLMs for free agent inference
* [vLLM on Clore.ai](/guides/language-models/vllm.md) — High-performance local LLM serving
* [GPU Comparison Guide](/guides/getting-started/gpu-comparison.md) — Choose the right GPU for your workload
* [OpenHands Discord](https://discord.gg/ESHStjSjD4) — Community support and model recommendations
* [SWE-bench Leaderboard](https://www.swebench.com) — Compare agent performance on real GitHub issues


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/ai-platforms-and-agents/openhands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.