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.

Ejecutarlo en un servidor que pueda desechar

Como el controlador debe tener acceso al socket de Docker, no puede aislar completamente OpenHands de su host. La mitigación adecuada es el aislamiento mediante la ubicación: ejecute OpenHands en un VPS dedicado que no contenga nada más importante, no en el servidor que también ejecuta su base de datos o sitio web. Cree una instantánea antes de empezar y reconstruya el sistema 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 lugar adecuado para ejecutarlo.

Sin embargo, la ubicación no es el único control disponible. OpenHands también permite controlar cuánto puede hacer el agente antes de detenerse para solicitar confirmación. A fecha de 2026-10-11, la documentación de su CLI enumera tres modos de confirmación: el modo predeterminado, openhands, siempre solicita confirmación; openhands --always-approve aprueba automáticamente todas las acciones, y la documentación indica que debe usarse «con precaución»; y openhands --llm-approve delega la decisión a un analizador de seguridad basado en un LLM. El SDK ofrece la misma selección mediante políticas de confirmación: AlwaysConfirm, NeverConfirm y ConfirmRisky. Esta última sólo pregunta por las acciones de riesgo y requiere un analizador de seguridad. La documentación del sandbox de Docker añade más controles. SANDBOX_VOLUMES define qué se monta en el sandbox, y todo lo que se monte con permisos de escritura en /workspace puede ser modificado por el agente; por tanto, monte sólo lo que necesite la tarea. AGENT_SERVER_USE_HOST_NETWORK=true ejecuta los sandboxes en modo de red del host y usa puertos fijos como 8000, así que déjelo desactivado salvo que lo necesite. En un servidor que nadie supervise, mantenga activadas las aprobaciones en lugar de aprobarlo todo automáticamente; los modos de permisos de Claude Code ofrecen una comparación útil para entender cómo funciona este segundo control en un servidor desatendido.

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.