Ejecutar OpenHands en Proxmox

Qué cubre este artículo sobre OpenHands en Proxmox

• Qué es OpenHands y para qué sirve.
• Cómo instalar OpenHands en Proxmox VE dentro de un LXC o una VM.
• Qué recursos se necesitan.
• Cómo conectar OpenHands con LLMs locales u hospedados.
• Aspectos importantes de seguridad y tramapas comunes.

Introducción: OpenHands en Proxmox

OpenHands es un framework de código abierto para desarrollo de software asistido por IA. Permite que agentes lean archivos, escriban código, ejecuten comandos e interactúen con control de versiones. Ejecutar OpenHands en Proxmox proporciona aislamiento, snapshots y gestión simple de recursos. Un LXC o VM dedicado separa OpenHands del resto de la red.

OpenHands puede conectarse a modelos locales a través de Ollama o a APIs hospedadas como OpenAI, Anthropic y muchas más. Dado que los agentes ejecutan código de verdad, un entorno aislado es especialmente importante.

¿Qué es OpenHands?

OpenHands es un framework de agentes de programación. Ofrece:

• Edición de código: Los agentes pueden leer y modificar archivos.
• Ejecución de shell: Ejecutar comandos en una sandbox.
• Control de versiones: Trabajar con repositorios Git.
• Integración con LLM: Conexión a muchos proveedores a través de LiteLLM.
• Interfaz web: Interfaz basada en navegador para la interacción.
• Extensibilidad: Soporte para servidores MCP y skills.

OpenHands está dirigido a desarrolladores que quieren automatizar tareas de programación repetitivas, como refactoring, corrección de bugs o documentación.

¿LXC o VM?

LXC

• Ventajas: Poco overhead, arranque rápido, gestión sencilla.
• Desventajas: Comparte el kernel con el host, Docker en LXC requiere permisos.
• Recomendado para: LXC dedicado con acceso al socket de Docker y acceso restringido al sistema de archivos.

VM

• Ventajas: Kernel propio, mejor aislamiento, uso más directo de Docker.
• Desventajas: Mayor overhead.
• Recomendado para: Mayor seguridad y passthrough de GPU.

Para comenzar, un LXC es suficiente. Si quieres máximo aislamiento o pasar una GPU, usa una VM.

Requisitos de hardware

• CPU: Mínimo 4 vCPUs, recomendado 8 vCPUs.
• RAM: Mínimo 8 GB, recomendado 16 GB, 32 GB para modelos más grandes.
• Disco: Mínimo 40 GB, recomendado 80 GB, ya que las imágenes Docker y modelos necesitan espacio.
• GPU: Opcional, acelera la inferencia de LLM.
• Red: Acceso a internet para descargar imágenes Docker y proveedores de API.

Requisitos previos

• Proxmox VE con soporte para LXC o VM.
• Ubuntu 24.04 LTS como sistema operativo invitado.
• Docker y Docker Compose instalados.
• Un proveedor de LLM o instancia local de Ollama.
• Opcional: Tailscale o VPN para acceso remoto seguro.

Instalación en un LXC

1. Crear el LXC

pct create 400 ubuntu-24.04-standard_24.04-1_amd64.tar.zst \
  --hostname openhands \
  --storage local-zfs \
  --rootfs 80 \
  --memory 16384 \
  --cores 4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

Si vas a usar Docker en el LXC, el perfil del contenedor debe tener keyctl=1 y nesting=1:

pct set 400 --features keyctl=1,nesting=1

2. Instalar Docker

pct start 400
pct exec 400 -- bash
apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
usermod -aG docker root

3. Arrancar OpenHands con Docker

mkdir -p ~/.openhands /projects
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 \
  -v /projects:/projects \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

OpenHands estará disponible en http://<lxc-ip>:3000.

Instalación con uv

Alternativamente, puedes instalar OpenHands con uv directamente:

apt install -y pipx
pipx install uv
uv tool install openhands --python 3.12

Para iniciar:

openhands serve

Esta variante se ejecuta sin Docker, pero renuncia al aislamiento de la sandbox.

Integración con LLM

Ollama local

Si Ollama se ejecuta en otro LXC o en el mismo host, conecta OpenHands a través de la IP interna:

http://192.168.1.50:11434

En la configuración de OpenHands, selecciona ollama como proveedor y un modelo como qwen2.5-coder:14b o codestral.

Proveedor externo

Para OpenAI, Anthropic, DeepSeek u OpenRouter, introduce la clave API en la configuración. LiteLLM se encarga de la comunicación.

Workspace y proyectos

El directorio /projects en el contenedor se utiliza como área de trabajo en OpenHands. Puedes clonar repositorios o cargar archivos. El agente trabajará entonces en este directorio.

cd /projects
git clone https://github.com/TU_USUARIO/repo.git

Seguridad

OpenHands puede ejecutar comandos de shell. Por lo tanto, hay que tener cuidado:

• LXC o VM aislado: Sin acceso directo al host de Proxmox.
• Activar sandbox: Usar contenedores Docker para agentes.
• Restricción del sistema de archivos: Montar solo /projects y rutas necesarias.
• Sin permisos root: No ejecutar OpenHands como root.
• Delimitar red: Usar Tailscale o reglas de firewall para controlar el acceso.
• Proteger claves API: Guardarlas en archivo .env o en un gestor de secretos.
• Snapshots antes de tareas importantes: Asegurar el estado.

Integración en el flujo de trabajo

• Configurar Git: Definir nombre y correo en el contenedor.
• Claves SSH: Para acceso a repositorios privados.
• VS Code Tunnel: Para edición directa de la salida del agente.
• Integración CI: Procesar resultados en GitHub Actions o GitLab CI.

Tramapas comunes

• Error de socket de Docker: LXC necesita nesting=1 y permisos de Docker.
• RAM insuficiente: Las imágenes del servidor de agentes son grandes, 8 GB apenas son suficientes.
• Modelo incorrecto: No todos los modelos son adecuados para agentes de programación.
• Sin GPU: Tiempos de espera más largos con modelos más grandes.
• Falta de aislamiento de red: Los contenedores pueden contactar servicios externos.
• URL de Ollama incorrecta: Usar endpoint /v1 cuando OpenHands habla compatible con OpenAI.

Enlaces e información adicional

• BotServ.de OpenClaw en Proxmox
• BotServ.de Copias de seguridad y restauración en Proxmox
• BotServ.de Fundamentos de Proxmox
• BotServ.de Fundamentos de Tailscale
• BotServ.de Gestión de Ollama

FAQ: OpenHands en Proxmox

¿Necesito una GPU? No, pero para modelos más grandes o respuestas rápidas es muy útil.

¿Puedo ejecutar OpenHands en Docker en Proxmox? Sí, ya sea en el LXC con Docker o directamente en una VM.

¿Es seguro OpenHands? Solo si está aislado y con sandbox. El acceso a shell siempre es un riesgo.

¿Qué modelo es el mejor? Modelos de programación como Qwen 2.5 Coder, DeepSeek-Coder o Codestral.

¿Puede OpenHands trabajar con Git? Sí, puede clonar repositorios, hacer cambios y crear commits.

Fuentes y lecturas adicionales

• OpenHands Docs: https://docs.openhands.dev/
• OpenHands GitHub: https://github.com/All-Hands-AI/OpenHands
• LiteLLM: https://docs.litellm.ai/

Conclusión: OpenHands en Proxmox

OpenHands es un framework de agentes de programación potente que funciona bien en un LXC o VM de Proxmox aislado. Lo importante es contar con suficiente RAM, una sandbox Docker, la integración correcta de LLM y una delimitación firme de red y sistema de archivos. Combinar OpenHands con Ollama o un proveedor externo económico te da un asistente autónomo para tareas de desarrollo que permanece en tu propia red.