Cómo instalar OpenHands en un VPS con Docker

Qué es OpenHands y el riesgo que debe comprender primero

OpenHands, antes llamado OpenDevin, es un agente autónomo de ingeniería de software. Se le asigna una tarea en lenguaje natural y planifica el trabajo, escribe código, ejecuta comandos, lee la salida y repite el proceso hasta completar la tarea. Se ejecuta en su propio servidor con Docker y se conecta a un modelo de lenguaje. En un VPS, funciona como un agente de programación que trabaja mientras usted no está presente.

Hay un hecho que debe determinar toda la configuración. OpenHands no sólo sugiere código: también lo ejecuta. Para hacerlo, su contenedor controlador monta el socket de Docker del host en /var/run/docker.sock, de modo que puede iniciar contenedores aislados para cada tarea. Cualquier proceso que pueda comunicarse con el socket de Docker puede iniciar un contenedor nuevo que monte todo el sistema de archivos del host. Por tanto, el acceso al socket equivale en la práctica a tener root en el equipo. Trate el servidor de OpenHands como un servidor que ejecuta código no confiable, porque eso es exactamente lo que hace. Todas las medidas de protección que se indican a continuación se derivan de este hecho.

Lo que necesita

Necesita un VPS con Ubuntu 24.04, una versión reciente de Docker Engine, al menos 4 GB de RAM y una clave de API para un modelo de lenguaje (OpenAI, Anthropic o Google), o un modelo local servido por Ollama en el mismo VPS. OpenHands admite docenas de backends de modelos, por lo que puede elegir el que prefiera. Si nunca ha configurado contenedores, los conceptos básicos de Docker en un VPS cubren los conocimientos que se dan por supuestos en esta guía.

Instalación con Docker

OpenHands se distribuye como dos imágenes: la imagen de la aplicación que ejecuta y una imagen de agent-server que descarga para ejecutar el sandbox de cada tarea. Ejecútelo así y sustituya las etiquetas por las versiones actuales indicadas en la documentación del proyecto:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Dos detalles evitan perder una hora con problemas confusos. La imagen de la aplicación y la imagen de agent-server tienen números de versión diferentes de forma intencionada. No intente hacerlos coincidir: use la etiqueta de agent-server que la documentación asocia con la versión de la aplicación. Observe también -p 127.0.0.1:3000:3000 en lugar de -p 3000:3000. Ese cambio determina si sólo usted puede acceder a la Web UI o si puede acceder toda Internet. La siguiente sección trata este último caso.

Mantenga la interfaz web fuera de Internet pública

OpenHands sirve su interfaz en el puerto 3000. Esa interfaz controla un agente que ejecuta código, por lo que publicarla en Internet proporciona a cualquiera que la encuentre una vía remota hacia un proceso que ejecuta comandos. Enlácela a loopback, como hace el comando de ejecución anterior, y acceda desde su portátil mediante un túnel SSH:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Después, abra http://127.0.0.1:3000 en su propio equipo. El tráfico utiliza la sesión SSH existente y no se abre ningún puerto nuevo en Internet pública. No todos los agentes necesitan un puerto: las sesiones de Claude Code en el mismo VPS se envían mensajes entre sí mediante el terminal, por lo que lo único que debe exponer es SSH. Conviene aplicar el mismo patrón de loopback y túnel a todos los paneles de agentes que aloje; acceder a la interfaz de análisis de open-kritt mediante un túnel funciona igual, pero en el puerto 5173. Para una configuración más permanente, colóquelo detrás de una VPN. En cualquier caso, coloque un firewall con denegación predeterminada delante del equipo para que nada quede expuesto por accidente y recuerde que un firewall que cubre sólo IPv4 deja abierto el mismo puerto en IPv6. Esa es la brecha del firewall de IPv6 que afecta a tantos usuarios.

Aísle la clave del modelo y las credenciales de los repositorios

OpenHands necesita una clave de API para su modelo y, a menudo, un token para clonar y enviar cambios a sus repositorios. Ambos pueden generar gastos y actuar en su nombre, así que trátelos como contraseñas. Guárdelos en un archivo de entorno que sólo pueda leer la cuenta adecuada. No los incluya en el comando de ejecución, donde quedarían en el historial del shell y en la lista de procesos. Tampoco los guarde en un archivo dentro de un repositorio git. Si conserva los originales en un gestor de contraseñas autoalojado, refuerce también ese servidor, porque los puntos débiles de un almacén son su token de administrador y su archivo de copia de seguridad, no los elementos cifrados en sí, como se explica en Proceso de refuerzo de Vaultwarden.

Ejecútalo en un servidor que puedas desechar

Como el controlador debe tener acceso al socket de Docker, no puedes aislar OpenHands por completo de su host. La mitigación adecuada consiste en aislarlo mediante su ubicación: ejecuta OpenHands en un VPS dedicado que no contenga nada que te importe, no en el servidor donde también se ejecutan tu base de datos o tu sitio web. Crea una instantánea antes de empezar y vuelve a crear el servidor a partir de ella, en lugar de confiar en un servidor que haya ejecutado código escrito por el agente durante una semana. Un VPS económico, desechable y de propósito único es el entorno adecuado para OpenHands. La ubicación es el único control real que ofrece OpenHands en este caso. Si también quieres controlar cuánto puede hacer el agente antes de detenerse para pedir confirmación, los modos de permisos de Claude Code muestran cómo funciona ese segundo control en un servidor que nadie supervisa.

Refuerce el servidor

El resto corresponde a las tareas habituales de mantenimiento seguro del servidor. Aquí son más importantes de lo normal porque la carga de trabajo implica más riesgos. Cree un usuario administrador sin privilegios en lugar de trabajar como root, siguiendo ejecutar servicios con un usuario sin privilegios. Cambie SSH para usar únicamente autenticación mediante claves. Después, complete la lista de comprobación siguiente y guárdela en un lugar donde vuelva a verla.

Para entender los componentes en lugar de limitarse a ejecutarlos, consulte crear su propio agente de IA en un VPS; si prefiere una plataforma con menos código, alojar Dify por su cuenta ofrece una introducción más sencilla.

FAQ

¿Es seguro ejecutar OpenHands en un servidor?

Puede serlo si se hace con cuidado, pero es más arriesgado que una aplicación web normal porque escribe y ejecuta código, y su controlador tiene acceso al socket de Docker del host, lo que equivale prácticamente a tener acceso root en la máquina. Ejecútelo en un VPS dedicado y desechable que no almacene nada valioso, mantenga su interfaz web en loopback detrás de un túnel SSH o una VPN, aísle sus claves y refuerce la seguridad del sistema. No lo ejecute junto a sus servicios importantes.

¿Por qué OpenHands necesita el socket de Docker?

OpenHands ejecuta cada tarea en un contenedor sandbox nuevo y solicita al daemon de Docker del host que cree esos contenedores mediante el montaje de /var/run/docker.sock en su controlador. Esto da al contenedor del controlador control sobre Docker en el host. Es una capacidad potente y arriesgada, por lo que debe tratar el propio host como un sistema que ejecuta código no confiable.

¿Puede OpenHands usar un modelo local en lugar de una API de pago?

Sí. OpenHands admite modelos locales servidos por Ollama o vLLM, por lo que puede ejecutarlo completamente en su propia infraestructura, sin coste por token y sin que los datos salgan del servidor. Necesita una máquina con memoria suficiente para ejecutar un modelo de programación capaz. Es el mismo cálculo de recursos que se explica en la guía de Ollama.

¿Debo ejecutar OpenHands en mi servidor principal?

No. Como ejecuta código escrito por un agente y tiene acceso al socket de Docker, manténgalo en un VPS independiente y dedicado que esté dispuesto a reconstruir. Ejecutarlo junto a una base de datos, un sitio web u otros servicios significa que un error del agente, o un fallo del propio agente, podría afectar a recursos que nunca debería tocar.