OpenHands: agente de IA para programación autónoma en tu VPS

OpenHands — el agente de IA que programa en el terminal por ti

OpenHands se basa en una arquitectura sencilla: un servidor web que orquesta uno o más agentes LLM, cada uno ejecutándose dentro de un sandbox Docker efímero aislado. El agente dispone de un shell, acceso al sistema de archivos del proyecto, una conexión a la API de GitHub y un bucle de razonamiento que alterna entre leer código, planificar y ejecutar.

El benchmark SWE-bench Verified mide la capacidad de un agente para resolver issues reales de GitHub sin asistencia humana. En abril de 2025, OpenHands emparejado con Claude Sonnet alcanzó el 60,6% en este benchmark con una sola trayectoria, y el 66,4% con cinco intentos y un modelo crítico. Bajo la licencia MIT, puedes alojarlo, modificarlo e integrarlo en tus herramientas internas sin restricciones comerciales. La v1.23.0 fue publicada el 23 de septiembre de 2026, con soporte para servidores MCP remotos y sincronización Git para administradores de organización.

Lo que OpenHands puede hacer solo

Corregir un bug documentado: el agente lee la issue de GitHub, localiza el código problemático, escribe la corrección, ejecuta los tests existentes y abre una PR con un mensaje de commit explicativo.
Añadir una suite de tests: partiendo de un módulo no cubierto, el agente genera tests unitarios o de integración alineados con el framework existente (pytest, PHPUnit, Jest…).
Refactorizar código: extraer una función, renombrar variables para seguir las convenciones, mover un módulo hacia una arquitectura más limpia.
Completar la documentación: generar o actualizar docstrings, archivos README y ejemplos de uso de la API a partir del código fuente.
Analizar un repositorio desconocido: producir un informe de estructura, identificar dependencias críticas, mapear flujos de datos entre módulos.
Abrir y describir una pull request: generar el título, el cuerpo de la PR con los cambios explicados, los tests que pasan e instrucciones de revisión para el equipo.

Requisitos numéricos antes de la instalación

OpenHands es un orquestador ligero, pero lanza contenedores sandbox por cada tarea. Los requisitos varían según el backend LLM elegido.

Hardware mínimo (API en la nube — Claude, GPT-4, Gemini):
- RAM: 4 GB mínimo, 8 GB recomendados para tareas concurrentes
- CPU: 2 vCPU mínimo, 4 vCPU para una experiencia fluida
- Almacenamiento: 20 GB libres (imágenes Docker + espacios de trabajo de proyectos)
- SO: Linux con Docker 24+ (Ubuntu 22.04 LTS o Debian 12 recomendados)

Hardware si se combina con Ollama (LLM local):
- RAM: 16 GB mínimo (8 GB para el modelo 7B cuantizado + 4 GB para el SO + margen)
- VRAM GPU: opcional pero muy recomendable — sin GPU, la inferencia es 10–30× más lenta
- Almacenamiento: 40 GB libres (modelos Ollama + Docker)

Versiones de software:
- Docker Engine 24.0 o posterior (verifica con docker --version)
- Docker Compose v2 (incluido en Docker Desktop y Docker Engine 24+)
- Linux kernel 5.4+ (requerido para el aislamiento del sandbox)

El puerto 3000 debe ser accesible desde tu navegador o VPN. Nunca lo expongas directamente a internet — usa un reverse proxy Nginx con HTTPS.

Instalar OpenHands en un VPS en 8 pasos

01
Instalar Docker Engine en tu VPS
En Ubuntu 22.04 o Debian 12, instala Docker con el script oficial:
```
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
```
Verifica la instalación:
```
docker --version
docker compose version
```
02
Crear el directorio de trabajo
Crea una carpeta dedicada para OpenHands y sus datos persistentes:
```
mkdir -p /opt/openhands/.openhands
cd /opt/openhands
```
La carpeta .openhands almacena la configuración persistente: claves API, historial de conversaciones, ajustes del agente.

Lanzar OpenHands con Docker

Inicia OpenHands con el comando oficial:

docker run -it --rm --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:latest

El flag --pull=always garantiza que ejecutas la última imagen estable. OpenHands está disponible en http://localhost:3000.

Alternativa: desplegar con Docker Compose

Para una gestión más sencilla, crea un archivo compose.yml en /opt/openhands:

services:
  openhands:
    image: docker.all-hands.dev/all-hands-ai/openhands:latest
    container_name: openhands-app
    pull_policy: always
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./.openhands:/.openhands
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped

Inicia la stack:

docker compose up -d
docker compose logs -f

Configurar el backend LLM en la interfaz
Abre http://localhost:3000 (o tu dominio HTTPS). En el primer inicio, OpenHands solicita:
1. Proveedor LLM: elige Anthropic, OpenAI, Google u openai-compatible para Ollama
2. Modelo: claude-sonnet-4-5 (mejor ratio calidad/coste) o claude-opus-4-5 para tareas complejas
3. Clave API: pega tu clave de Anthropic u OpenAI
Estos ajustes se guardan en ~/.openhands/config.toml y persisten entre reinicios.
Conectar OpenHands a GitHub
Para que OpenHands pueda clonar repos privados, leer issues y abrir PRs, configura un Personal Access Token de GitHub:
1. En GitHub: Configuración → Herramientas de desarrollador → Tokens de acceso personal → Tokens de grano fino
2. Otorga permisos: Contents (lectura/escritura), Pull requests (lectura/escritura), Issues (lectura)
3. En la interfaz de OpenHands: Ajustes → Git → pega el token

Configurar el reverse proxy Nginx con HTTPS

Nunca expongas el puerto 3000 directamente. Usa Nginx como reverse proxy:

server {
    listen 443 ssl;
    server_name openhands.tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/openhands.tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openhands.tu-dominio.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_read_timeout 600s;
    }
}

Obtén el certificado:

certbot --nginx -d openhands.tu-dominio.com

Probar con una primera tarea
Abre la interfaz, pega la URL de una issue de GitHub (ej. https://github.com/tu-org/tu-repo/issues/42) en el campo de tarea y haz clic en Iniciar.
OpenHands hará lo siguiente:
1. Leer la issue y planificar el enfoque
2. Clonar el repositorio en el sandbox
3. Explorar el código, escribir los cambios
4. Ejecutar los tests (pytest, npm test, etc.)
5. Mostrar un resumen y ofrecer abrir una PR

Configurar el backend de IA: Claude, GPT-4 u Ollama

OpenHands admite cualquier proveedor compatible con la API de OpenAI, además de los proveedores nativos Anthropic, Google y Azure. La elección del modelo es el factor más determinante en la calidad de los resultados.

Claude Sonnet (Anthropic) — recomendado para producción
claude-sonnet-4-5 ofrece la mejor relación calidad/coste para la ingeniería de software agéntica. Su ventana de contexto de 200.000 tokens le permite analizar grandes bases de código sin paginación. Espera gastar entre $0,03 y $0,15 por tarea según la complejidad. Configura LLM_MODEL=anthropic/claude-sonnet-4-5.

Claude Opus (Anthropic) — para tareas complejas
claude-opus-4-5 ofrece mejor rendimiento en problemas arquitectónicos y refactorizaciones a gran escala, pero a un coste 5–10× superior al de Sonnet. Resérvalo para tareas que superen las capacidades de Sonnet.

Ollama (LLM local) — para soberanía total
Si tu código es especialmente sensible o quieres cero dependencia externa, combina OpenHands con Ollama en el mismo VPS. Configura LLM_BASE_URL=http://host.docker.internal:11434 y LLM_MODEL=openai/qwen2.5-coder:32b. Los modelos qwen2.5-coder 32B logran los mejores resultados entre los modelos de pesos abiertos en benchmarks de programación. Inconveniente: la inferencia en CPU es 10–30× más lenta que una llamada API.

Variables de entorno clave:

LLM_MODEL=anthropic/claude-sonnet-4-5
LLM_API_KEY=sk-ant-...
AGENT=CodeActAgent

Asegurar docker.sock — socket proxy y modo rootless. Montar /var/run/docker.sock dentro de un contenedor es equivalente a dar acceso root completo a la máquina anfitriona: cualquier contenedor con acceso a este socket puede crear nuevos contenedores, montar volúmenes arbitrarios y escalar privilegios.

Dos enfoques para reducir esta superficie de ataque:

Opción 1 — Socket proxy (Tecnativa/docker-socket-proxy): interpón un proxy que filtre las llamadas a la API de Docker. OpenHands solo necesita POST /containers/create, GET /containers/{id}/json, POST /containers/{id}/start y DELETE /containers/{id}. El socket proxy bloquea todo lo demás.

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      CONTAINERS: 1
      POST: 1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  openhands:
    image: docker.all-hands.dev/all-hands-ai/openhands:latest
    environment:
      - DOCKER_HOST=tcp://socket-proxy:2375
    depends_on:
      - socket-proxy
    restart: unless-stopped

Opción 2 — Docker rootless: ejecuta Docker en modo rootless (tu usuario del sistema, no root). El socket queda entonces en /run/user/1000/docker.sock y pertenece a tu usuario. Comprometer este socket no escala más allá de los privilegios de ese usuario. Actívalo con dockerd-rootless-setuptool.sh install.

Casos de uso concretos

Caso 1 — Resolver un bug documentado en una issue de GitHub
Pega la URL de una issue bien descrita en OpenHands. El agente lee la issue, busca los archivos implicados con grep y el explorador de código, escribe la corrección, ejecuta la suite de tests y propone abrir una PR. Para bugs aislados con buena documentación, la tasa de éxito es alta sin intervención humana.

Caso 2 — Generar tests para un módulo no cubierto
Indica el módulo objetivo: Escribe tests unitarios para el módulo src/payments/stripe.py, apuntando al 80% de cobertura con pytest. Los mocks deben usar unittest.mock. El agente analiza el módulo, identifica los casos límite y genera una suite de tests coherente con los patrones existentes.

Caso 3 — Analizar un repositorio de código abierto antes de hacer un fork
Antes de integrar una dependencia o hacer un fork de un proyecto, pregunta a OpenHands: Analiza el repositorio https://github.com/org/repo. Identifica dependencias críticas, puntos de acoplamiento fuerte, tests faltantes y CVEs conocidos en las dependencias directas.

Caso 4 — Actualizar una dependencia principal
Las migraciones de versiones principales (Django 4 → 5, React 18 → 19, Laravel 10 → 11) implican muchos archivos. OpenHands puede leer el changelog oficial, aplicar los cambios mecánicamente y volver a ejecutar los tests para identificar lo que aún necesita atención manual.

Resolución de problemas — errores comunes

permission denied while trying to connect to the Docker daemon socket
El usuario que ejecuta OpenHands no está en el grupo docker. Corrígelo con:

sudo usermod -aG docker $USER && newgrp docker

Container exited with OOM kill (exit code 137)
El sandbox se quedó sin memoria. Aumenta la RAM disponible en el VPS o limita las tareas concurrentes. Añade --memory=4g al contenedor sandbox en la configuración de OpenHands.

LLM timeout after 120s
En bases de código grandes, el agente envía contextos grandes al LLM. Aumenta LLM_TIMEOUT en la configuración o reduce el alcance de la tarea.

No such container: openhands-sandbox-xxx
El contenedor sandbox fue eliminado entre dos acciones. Reinicia la tarea desde el principio — OpenHands no reanuda tareas interrumpidas por un reinicio de Docker.

Rate limit exceeded (Anthropic/OpenAI)
Añade LLM_NUM_RETRIES=5 y LLM_RETRY_MIN_WAIT=30 en la configuración para que OpenHands reintente automáticamente.

OpenHands vs Codex en la nube vs Devin

Desplace la tabla

Criterio	OpenHands self-hosted	GitHub Copilot Workspace	Devin (Cognition)
Coste mensual	0 € (+ coste API LLM)	19 $/mes (Copilot Pro)	500 $/mes (plan Team)
Código enviado al exterior	No (el código permanece en el VPS)	Sí (GitHub/Microsoft)	Sí (Cognition)
Backend LLM configurable	Sí (Claude, GPT, Ollama…)	No (modelo Microsoft)	No (modelo Cognition)
Puntuación SWE-bench Verified	66,4% (5 intentos, Claude)	No publicado	~49% (última publicación)
Licencia	MIT (código abierto)	Propietaria	Propietaria (SaaS)
VPS requerido	Sí (4 GB RAM mínimo)	No	No
Autonomía completa (PR automática)	Sí	Parcial	Sí

OpenHands: agente de IA para programación autónoma en tu VPS

OpenHands — el agente de IA que programa en el terminal por ti

Lo que OpenHands puede hacer solo

Requisitos numéricos antes de la instalación

Instalar OpenHands en un VPS en 8 pasos

Instalar Docker Engine en tu VPS

Crear el directorio de trabajo

Lanzar OpenHands con Docker

Alternativa: desplegar con Docker Compose

Configurar el backend LLM en la interfaz

Conectar OpenHands a GitHub

Configurar el reverse proxy Nginx con HTTPS

Probar con una primera tarea

Configurar el backend de IA: Claude, GPT-4 u Ollama

Casos de uso concretos

Resolución de problemas — errores comunes

OpenHands vs Codex en la nube vs Devin

Despliega OpenHands en un VPS ServOrbit

Artículos relacionados

Cómo alojar Flowise en un VPS

GitHub Copilot AI Credits: recuperar el control en un VPS

Alojar Hermes Agent en un VPS

¿Necesita ayuda?