instalar OpenHands en un VPS con Docker

Qué es OpenHands y el primer riesgo que debe entender

OpenHands, anteriormente OpenDevin, es un agente autónomo de ingeniería de software. Usted le asigna una tarea en lenguaje natural y este planifica el trabajo, escribe código, ejecuta comandos, lee la salida e itera hasta completar la tarea. Se ejecuta en su propio servidor con Docker y se le asigna un modelo de lenguaje. En un VPS, se convierte en un agente de programación que trabaja mientras usted no está.

Un hecho debe definir toda su configuración. OpenHands no solo sugiere código, sino que lo ejecuta. Para ello, el contenedor controlador monta el socket de Docker del host en /var/run/docker.sock para poder crear contenedores sandbox para cada tarea. Cualquier proceso que pueda comunicarse con el socket de Docker puede iniciar un nuevo contenedor que monte todo el sistema de archivos del host; esto significa que el acceso al socket equivale a tener privilegios de root en la máquina. Por tanto, trate al servidor de OpenHands como un servidor que ejecuta código no confiable, porque eso es exactamente lo que hace. Todas las medidas de endurecimiento (hardening) descritas a continuación derivan de esto.

Requisitos

Necesita un VPS con Ubuntu 24.04 ejecutando una versión reciente de Docker Engine, al menos 4 GB de RAM y una clave API para un modelo de lenguaje (OpenAI, Anthropic o Google), o un modelo local servido por Ollama en el mismo VPS. OpenHands soporta decenas de backends de modelos, por lo que la elección es suya. Si nunca ha configurado contenedores, los conceptos básicos de Docker en un VPS cubren la base que asume esta guía.

Instalación con Docker

OpenHands se distribuye en dos imágenes: la imagen de la aplicación que se ejecuta y la imagen del servidor del agente que descarga para ejecutar el sandbox de cada tarea. Ejecútelo de esta forma, sustituyendo las etiquetas actuales de 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 le ahorrarán una hora de confusión. La imagen de la app y la imagen del servidor del agente tienen números de versión distintos a propósito; no intente que coincidan: use la etiqueta del servidor del agente que la documentación asocia con su versión de la app. Además, observe el uso de -p 127.0.0.1:3000:3000 en lugar de -p 3000:3000. Ese único cambio es la diferencia entre una interfaz Web accesible solo para usted y una accesible para todo internet, que es el tema de la siguiente sección.

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 permite que cualquier persona que la encuentre tenga una vía remota hacia un proceso que ejecuta comandos. Vincúlela al 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

Luego abra http://127.0.0.1:3000 en su propia máquina. El tráfico viaja a través de su sesión SSH existente y nada nuevo escucha en internet pública. Para una configuración más permanente, utilice una VPN. En cualquier caso, coloque un firewall con política de denegación por defecto (default-deny) delante del servidor para que nada quede expuesto accidentalmente. Recuerde que un firewall que solo cubre IPv4 deja el mismo puerto abierto en IPv6, que es el vacío de seguridad en el firewall IPv6 que afecta a muchos usuarios.

Aísle la clave del modelo y las credenciales del repositorio

OpenHands necesita una clave API para su modelo y, a menudo, un token para clonar y subir 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 variables de entorno que solo la cuenta autorizada pueda leer. Nunca los incluya en el comando de ejecución, ya que quedarían registrados en el historial de la shell y en la lista de procesos, y nunca los guarde en un archivo dentro de un repositorio git.

Ejecútelo en un servidor desechable

Debido a que el controlador debe tener el socket de Docker, no puede aislar completamente a OpenHands de su host. La mitigación real es el aislamiento por ubicación: ejecute OpenHands en un VPS dedicado que no contenga nada más que sea importante para usted, no en el servidor donde también se ejecutan su base de datos o su sitio web. Realice una instantánea (snapshot) antes de empezar y reconstruya el sistema desde esa instantánea en lugar de confiar en una máquina que ha ejecutado código generado por un agente durante una semana. Un VPS económico, desechable y de propósito único es el entorno adecuado.

Refuerce la seguridad del servidor

El resto es higiene estándar de servidores. Esto es más crítico aquí que de costumbre porque la carga de trabajo es más riesgosa. Cree un usuario administrador sin privilegios en lugar de trabajar como root, siguiendo la ejecución de servicios como usuario sin privilegios. Configure SSH para que use únicamente autenticación por clave. Luego, ejecute la siguiente lista de verificación y guárdela en un lugar donde pueda consultarla de nuevo.

Para entender los componentes internos en lugar de solo ejecutarlos, consulte cómo construir su propio agente de IA en un VPS; para una plataforma con menos código, autoalojar Dify es una opción más sencilla.

Preguntas frecuentes (FAQ)

¿Es seguro ejecutar OpenHands en un servidor?

Puede serlo, con precaución, pero es más riesgoso que una aplicación web ordinaria porque escribe y ejecuta código, y su controlador posee el socket de Docker del host, lo que equivale a tener privilegios de root en la máquina. Ejecútelo en un VPS dedicado y desechable que no contenga nada valioso, mantenga su interfaz Web en loopback mediante un túnel SSH o VPN, aísle sus claves y refuerce la seguridad del servidor. 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 demonio Docker del host que cree esos contenedores montando /var/run/docker.sock en su controlador. Esto otorga al contenedor controlador el control sobre Docker en el host, lo cual es potente y riesgoso; por tanto, el host debe tratarse como un sistema que ejecuta código no confiable.

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

Sí. OpenHands soporta modelos locales servidos por Ollama o vLLM, por lo que puede ejecutarlo de forma totalmente autoalojada, sin costes por token y sin que los datos salgan de su servidor. Necesita una máquina con suficiente memoria para un modelo de programación capaz, lo cual es la misma cuestión de capacidad de hardware que se trata en la guía de Ollama.

¿Debería ejecutar OpenHands en mi servidor principal?

No. Debido a que ejecuta código generado por un agente y posee el socket de Docker, manténgalo en un VPS separado y de propósito único que esté dispuesto a reconstruir. Co-ubicarlo con una base de datos, un sitio web u otros servicios significa que un error del agente, o un error de software en él, puede alcanzar elementos que nunca debería tocar.