# 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](https://docs.clore.ai/guides/getting-started/gpu-comparison) 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](https://docs.clore.ai/guides/language-models/ollama) 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](https://docs.clore.ai/guides/language-models/vllm) 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](https://docs.clore.ai/guides/language-models/ollama) — Run local LLMs for free agent inference
* [vLLM on Clore.ai](https://docs.clore.ai/guides/language-models/vllm) — High-performance local LLM serving
* [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison) — 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