OpenHands

Overview

OpenHands is an open-source AI software engineer platform maintained by the All-Hands-AI team. It inherits the OpenDevin project and aims to build general AI agents capable of autonomously completing software engineering tasks. OpenHands provides a complete development framework, including an agent runtime, tool system, sandbox environment, and evaluation framework. It supports multiple LLM backends and can be used for both research and production environments.

Installation

OpenHands is recommended to be installed using Docker to ensure environment isolation and consistency. Docker 26.0+ and Python 3.12+ are required. The installation process includes pulling the Docker image, configuring environment variables, and starting the service. Installing the Python package via pip for development is also supported.

# Docker installation
docker pull openhands/openhands:latest

# Start OpenHands
docker run -it \
  -p 3000:3000 \
  -e OPENAI_API_KEY=your-key \
  -v /var/run/docker.sock:/var/run/docker.sock \
  openhands/openhands:latest

# Or use pip
pip install openhands-ai

Docker Setup

OpenHands uses Docker for sandbox isolation, with each agent running in an independent container. You need to configure the Docker socket mount, working directory mapping, network settings, and more. Docker configuration ensures that agents execute code in a secure environment without affecting the host system.

# docker-compose.yml
version: '3'
services:
  openhands:
    image: openhands/openhands:latest
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./workspace:/workspace

Architecture

The architecture of OpenHands includes: Agent Runtime, Event Stream, Runtime Environment, and Tool System. Agents interact with the environment and tools through the event stream, and every operation is recorded in the event history, supporting replay and auditing.

Creating Agents

OpenHands supports custom agents. By inheriting from the Agent class, you can implement specific agent behaviors, tool invocation logic, and reasoning strategies. Agents can be configured with different LLMs, system prompts, toolsets, and more.

# Custom agent example
from openhands.agent import Agent

class MyAgent(Agent):
    def __init__(self, llm, config):
        super().__init__(llm, config)
        self.name = "MyAgent"
    
    def step(self, state):
        # Implement agent logic
        action = self.llm.chat(state.history)
        return action

Runtime

OpenHands' runtime environment provides sandbox execution capabilities, supporting file system operations, command execution, code running, and more. The runtime is based on Docker, ensuring that agent operations are performed in an isolated environment. Custom runtime images are supported, allowing pre-installation of specific tools and dependencies.

Security

OpenHands takes security seriously, using Docker sandboxes to isolate agent operations and prevent potential harm to the host system. It supports network isolation, resource limits, and file system permission control. It is recommended to use additional security measures in production environments, such as API key management and access control.

Evaluation

OpenHands provides an evaluation framework that supports evaluating agent performance on benchmarks such as SWE-bench and HumanEval. The evaluation framework can measure metrics such as the agent's task completion rate, code quality, and execution efficiency. This helps compare the effects of different configurations and models.

# Run SWE-bench evaluation
python -m openhands.eval \
  --benchmark swe-bench \
  --agent CodeActAgent \
  --model gpt-4 \
  --max-iterations 30

Community

OpenHands has an active open-source community with many contributors on GitHub. The community communicates via Discord and GitHub Discussions. Developer meetings are held regularly to discuss the roadmap and new features. Community contributions of code, documentation, and issue feedback are welcome.

Configuration

OpenHands is configured through environment variables and a config file. The LLM is selected via LLM_MODEL and authenticated with LLM_API_KEY (or OPENAI_API_KEY). Docker is required for the sandbox runtime—each agent runs in an isolated container. The docker-compose.yml mounts the Docker socket and a workspace directory.

# Environment variables (.env)
OPENAI_API_KEY=your-key
LLM_MODEL=gpt-4
LLM_API_KEY=your-key
WORKSPACE_BASE=/path/to/workspace

# docker-compose.yml
services:
  openhands:
    image: openhands/openhands:latest
    ports: ["3000:3000"]
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - LLM_MODEL=gpt-4
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./workspace:/workspace

# Start
docker compose up -d
# Access http://localhost:3000

Docker is mandatory—agents run in sandboxed containers so the host system stays safe.

FAQ

Common questions cover Docker setup, model support, security, cost, and custom agents. OpenHands supports any OpenAI-compatible LLM and runs each agent in an isolated Docker container. Custom agents are built by subclassing the Agent class.

Q: Why is Docker required?
A: Agents run in isolated Docker containers so file and command operations
   cannot harm the host system.

Q: Which models are supported?
A: Any OpenAI-compatible LLM (OpenAI, Anthropic via proxy, local vLLM/Ollama);
   set LLM_MODEL and LLM_API_KEY.

Q: Is it safe to run?
A: Yes—Docker sandboxing isolates agent operations; use resource limits and
   network isolation in production.

Q: Can I write a custom agent?
A: Yes—subclass the Agent class and implement the step() method.

Q: How do I cut costs?
A: Use a smaller model for routine steps, limit max-iterations, and run
   evaluation jobs on cheaper models.

For production, add API key management, access control, and resource limits on top of the default sandbox.