1. Entiende los límites del despliegue
Hodman aloja la web y la API, incluida la administración del espacio, tareas y conversaciones. El agente se ejecuta en tu host y abre una conexión WebSocket autenticada saliente a wss://hodman.ai/ws-agent por TCP 443. Las tareas y resultados viajan en ambos sentidos por esa conexión. No hay un puerto entrante de gestión que exponer.
El agente controla Docker para ejecutar los contenedores. Los archivos y las bases aprovisionadas se almacenan en tu host. Las bases y APIs internas deben ser accesibles desde los contenedores del proyecto, no desde internet.
Almacenar localmente no garantiza que los datos no salgan. Archivos solicitados, consultas, salidas de comandos y registros pueden volver a Hodman y entrar en el contexto de IA. El proveedor elegido puede recibir ese contexto; esta configuración no hace local la inferencia. Usa credenciales acotadas y filtros verificados en conectores. No es un despliegue aislado de la red ni un plano de control de Hodman totalmente autogestionado.
2. Prepara el host
Usa un host Linux o una VM dedicados con Docker Engine y el plugin Docker Compose. Confirma que la versión admita tu arquitectura. Las notas de despliegue estiman inicialmente 4 CPU, 16 GB de RAM y 200 GB SSD para unos cuatro proyectos modestos; las compilaciones y cargas reales pueden requerir más. Es una estimación, no una garantía de capacidad.
Necesitas un espacio de Hodman apto, acceso de administrador a Agentes y una cuenta Unix dedicada con escritura en los directorios de proyectos. Pertenecer al grupo del socket de Docker otorga acceso potente al host. No lo compartas con cargas sensibles ajenas.
La configuración siguiente ejecuta PostgreSQL localmente sin publicar su puerto. La cuenta inicial crea bases y roles de proyectos; trátala como una credencial de infraestructura privilegiada. No la reutilices como cuenta de aplicación. Qdrant aparecía en el archivo antiguo de despliegue, pero no se necesita en la configuración mínima actual revisada para esta guía.
docker --version
docker compose version
uname -m
stat -c '%g' /var/run/docker.sock3. Planifica por separado gestión, acceso a aplicaciones y tráfico saliente
Gestión: permite resolver hodman.ai y abrir WSS a hodman.ai:443. El proxy saliente debe admitir conexiones WebSocket de larga duración. Nunca publiques en internet el daemon de Docker, PostgreSQL ni un puerto de gestión del agente.
Descargas de imágenes y dependencias: permite los endpoints de autenticación y contenido de Docker Hub, los registros de imágenes adicionales y los repositorios de paquetes de tus compilaciones. Aprueba integraciones y destinos de IA según el proceso real; el ejemplo no es una lista completa de tráfico saliente autorizado.
Acceso a aplicaciones: decide quién puede abrir vistas previas, aplicaciones publicadas y webhooks. DNS privado, ingreso HTTPS interno y VPN pueden mantener el acceso dentro de tu red. El navegador debe poder acceder a una vista previa interna. La conexión WSS de gestión no publica por sí sola una aplicación ni hace accesible en internet una vista previa interna.
Los nombres predeterminados usan project-slug.project-host.base-host, por ejemplo preview-demo.runner-1.apps.example.com. Configura PROJECT_HOST y DZUN_AI__ROUTING_BASE_HOST de forma coherente, crea los registros DNS y dirígelos a tu ingreso. Cada host puede tener un PROJECT_HOST diferente.
Traefik es una opción de ingreso, no un requisito para registrar el agente. El ejemplo omite ingreso y no publica puertos. Si lo agregas, conéctalo a dzun_ai_edge, expón solo las rutas previstas y alinea los nombres de entrypoint y certificate-resolver con las variables del agente. Para aplicaciones internas usa una CA interna o DNS-01 aprobado. HTTP-01 de Let's Encrypt requiere el puerto 80 entrante y no sirve para endpoints totalmente privados sin otro diseño. No agregues reglas públicas 80/443 solo para conectar el agente.
4. Registra el agente y protege su clave
Como propietario, abre Agentes en la consola de Hodman y emite una clave. Guarda su UUID y clave privada. Elige un ID de agente y host del proyecto para este equipo. Las claves deben pertenecer a tu espacio: nunca copies credenciales ajenas ni guardes claves privadas en Git.
Guarda la clave privada en ./secrets/agent-private.pem. La configuración usa AGENT_PRIVATE_KEY_PATH, compatible con el agente, en lugar de incrustar una clave multilínea en .env. Restringe el archivo al UID dedicado del agente y móntalo como solo lectura.
mkdir -p secrets
chmod 700 secrets
# Save the private key issued in the Hodman console here.
chmod 600 secrets/agent-private.pem5. Crea .env y los directorios persistentes
Reemplaza todos los valores CHANGE_ME. Usa el UID y GID numéricos de la cuenta dedicada; AGENT_DOCKER_GID debe coincidir con el grupo del socket de Docker en Linux. Genera una contraseña única y robusta de PostgreSQL. Usa rutas absolutas del host.
AGENT_IMAGE es deliberadamente un marcador de versión. El nombre de repositorio previsto es una suposición para la publicación pública, no prueba de disponibilidad. Fija una etiqueta o digest inmutable confirmado. Una imagen pública no implica licencia de código abierto. El entorno del proyecto usa otra imagen: fija su versión confirmada por separado; el ejemplo no adivina una compatible.
Una contraseña entre comillas evita que Compose interprete los signos de dólar. Protege .env, no lo agregues al control de versiones y nunca pegues la salida de docker compose config en soporte sin quitar los secretos.
AGENT_IMAGE=hodmanai/hodman-ai-runner:CHANGE_ME_RELEASE_TAG
RUNTIME_IMAGE=hodmanai/hodman-ai-runtime:CHANGE_ME_RELEASE_TAG
DATA_DIR=/srv/hodman
AGENT_UID=CHANGE_ME_NUMERIC_UID
AGENT_GID=CHANGE_ME_NUMERIC_GID
AGENT_DOCKER_GID=CHANGE_ME_DOCKER_SOCKET_GID
AGENT_ID=runner-1
PROJECT_HOST=runner-1
BASE_HOST=apps.example.com
AGENT_KEY_UUID=CHANGE_ME_KEY_UUID
POSTGRES_PASSWORD='CHANGE_ME_STRONG_PASSWORD'6. Configura la propiedad de los archivos
Ejecuta estos comandos en el host Linux dedicado después de reemplazar los IDs numéricos. La clave privada debe ser legible para el UID que ejecuta el agente. El contenedor oficial de PostgreSQL gestiona la propiedad de su directorio de datos: no lo asignes a la cuenta del agente.
El ejemplo de PostgreSQL 18 monta /var/lib/postgresql; la imagen gestiona su directorio de datos específico por versión. No montes un PGDATA de una versión mayor anterior: planifica una migración de PostgreSQL para bases existentes.
sudo mkdir -p /srv/hodman/workdir /srv/hodman/apps-data /srv/hodman/postgres
sudo chown CHANGE_ME_UID:CHANGE_ME_GID /srv/hodman/workdir /srv/hodman/apps-data
sudo chown CHANGE_ME_UID:CHANGE_ME_GID secrets/agent-private.pem
chmod 600 .env
sudo chmod 600 secrets/agent-private.pem7. Crea compose.yaml
Este ejemplo mínimo para un host nuevo y dedicado inicia el agente y PostgreSQL local, crea las dos redes Docker esperadas por los contenedores y no publica puertos. No configura ingreso, VPN, respaldos ni el firewall de tu empresa.
Dentro del contenedor del agente, las operaciones de archivos usan /workdir y /data. Docker crea contenedores hermanos con rutas del host, por lo que AGENT_HOST_WORKDIR_BASE y AGENT_HOST_DATA_BASE deben apuntar a los directorios absolutos correspondientes. Mezclar ambos espacios puede generar montajes vacíos o incorrectos.
El montaje del socket permite crear y controlar contenedores. Montarlo como solo lectura no convierte las llamadas a Docker en solo lectura. Protege el host y la clave del agente. El precalentamiento de plantillas está desactivado para evitar trabajo inicial innecesario; configúralo aparte si hace falta.
services:
postgres:
image: postgres:18
restart: unless-stopped
environment:
POSTGRES_USER: hodman_admin
POSTGRES_DB: hodman_agent
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
volumes:
- ${DATA_DIR:?Set DATA_DIR}/postgres:/var/lib/postgresql
healthcheck:
test: [CMD-SHELL, 'pg_isready -U hodman_admin -d hodman_agent']
interval: 10s
timeout: 5s
retries: 12
networks: [core]
agent:
image: ${AGENT_IMAGE:?Set a confirmed AGENT_IMAGE}
restart: unless-stopped
user: '${AGENT_UID:?Set AGENT_UID}:${AGENT_GID:?Set AGENT_GID}'
group_add:
- '${AGENT_DOCKER_GID:?Set AGENT_DOCKER_GID}'
depends_on:
postgres:
condition: service_healthy
environment:
API_WS_URL: wss://hodman.ai/ws-agent
AGENT_ID: ${AGENT_ID:?Set AGENT_ID}
PROJECT_HOST: ${PROJECT_HOST:?Set PROJECT_HOST}
AGENT_KEY_UUID: ${AGENT_KEY_UUID:?Set AGENT_KEY_UUID}
AGENT_PRIVATE_KEY_PATH: /run/secrets/agent-private.pem
AGENT_WORKDIR_BASE: /workdir
AGENT_HOST_WORKDIR_BASE: ${DATA_DIR}/workdir
AGENT_DATA_BASE: /data
AGENT_HOST_DATA_BASE: ${DATA_DIR}/apps-data
AGENT_PG__HOST: postgres
AGENT_PG__PORT: '5432'
AGENT_PG__DATABASE: hodman_agent
AGENT_PG__USERNAME: hodman_admin
AGENT_PG__PASSWORD: ${POSTGRES_PASSWORD}
AGENT_PROJECT_PG__HOST: postgres
AGENT_PROJECT_PG__PORT: '5432'
AGENT__MIGRATIONS: /app/harness/apps/runner/drizzle
AGENT__TEMPLATE_POOL_ENABLED: 'false'
AGENT__TEMPLATE_POOL_DEFAULT_DOCKER_IMAGE: ${RUNTIME_IMAGE:?Set RUNTIME_IMAGE}
DZUN_AI__ROUTING_BASE_HOST: ${BASE_HOST:?Set BASE_HOST}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ${DATA_DIR}/workdir:/workdir
- ${DATA_DIR}/apps-data:/data
- ./secrets/agent-private.pem:/run/secrets/agent-private.pem:ro
networks: [core, edge]
networks:
core:
name: dzun_ai_network
edge:
name: dzun_ai_edge8. Descarga la versión confirmada e inicia
Verifica que reemplazaste todos los marcadores. Validar Compose comprueba la estructura y los valores obligatorios, no la disponibilidad del registro, los permisos ni la conexión. No ejecutes source .env: un archivo de entorno de Compose no es un script de shell.
La distribución pública prevista no requiere credenciales del registro privado de Hodman. Tu organización puede usar autenticación de Docker Hub por política o límites de descarga. Si la imagen no está disponible, confirma la publicación y su referencia exacta en vez de probar credenciales privadas o adivinar etiquetas.
Debes validar arquitectura, inicio y registro contra la versión real publicada del agente. Abrir esta guía no despliega el ejemplo en tu infraestructura.
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 agent9. Verifica con datos de prueba no sensibles
Comprueba que PostgreSQL esté saludable y que los registros del agente muestren 'hello-ack received: agent is authenticated on API'. Confirma que el host aparezca en línea en Hodman con el host de proyecto previsto. Un contenedor en ejecución no prueba que el registro haya funcionado.
Asigna un proyecto descartable al host. Pídele que cree un archivo pequeño, ejecute un comando y lea la salida. Verifica los archivos en la carpeta del host y que las credenciales generadas de base de datos funcionen desde el contenedor. No uses datos de producción en la primera prueba.
Configura el ingreso por separado y abre la URL exacta de vista previa en un navegador autorizado, por VPN si corresponde. Verifica HTTP y cualquier WebSocket necesario. No construyas ni adivines URLs si la consola ya las ofrece.
Prueba un servicio interno con acceso de lectura acotado y datos sintéticos. Revisa lo que vuelve a la conversación alojada y al modelo. Verifica filtros y enmascaramiento cuando corresponda. Comprueba que PostgreSQL, Docker y el servicio interno no sean accesibles desde internet. Prueba restauración de respaldos y rotación de claves antes de considerar el host listo para producción.
10. Respaldos, actualizaciones y rotación de claves
Respalda las carpetas de proyectos, apps-data, la configuración del agente y los certificados del ingreso. Usa copias consistentes de PostgreSQL: copiar un directorio de base activa no basta. Protege los respaldos como datos sensibles y prueba la restauración.
Antes de actualizar, lee las notas de versión, registra la etiqueta o digest actual y realiza respaldos recuperables. Cambia AGENT_IMAGE por una versión confirmada, descárgala, recrea el agente y repite las verificaciones de registro y proyecto. Las migraciones de base de datos pueden impedir volver atrás solo cambiando la imagen. Actualiza las imágenes de proyecto por separado y valida los proyectos afectados.
Para rotar claves, emite una nueva en la consola, reemplaza el archivo montado y AGENT_KEY_UUID, recrea el agente y confirma el registro. Revoca la anterior según tu procedimiento. Si sospechas una vulneración, revoca el acceso de inmediato e investiga el host. Nunca elimines volúmenes Docker como parte rutinaria de una actualización.
docker compose pull agent
docker compose up -d --no-deps --force-recreate agent
docker compose logs --tail=100 agentSolución de problemas
Imagen inexistente o descarga denegada: confirma que la versión pública exista, su repositorio y etiqueta exactos y la política de registro y red. No confundas hodman-ai-runner, el servicio de ejecución, con hodman-ai-runtime, la imagen del proyecto.
Falta clave privada o UUID: revisa AGENT_KEY_UUID, el montaje de solo lectura y los permisos para AGENT_UID. Cambiar la clave en disco requiere recrear el agente porque el proceso la guarda en caché.
Falla de autenticación o host desconectado: verifica que la clave pertenezca al espacio correcto, la identidad del agente, DNS/TLS salientes y soporte WebSocket. Revisa registros acotados sin publicar claves ni salidas sensibles.
Permiso de Docker denegado: verifica el GID numérico del socket y group_add. No lo soluciones dando escritura global a docker.sock ni exponiendo un endpoint TCP sin autenticación.
Faltan archivos del proyecto: compara las rutas visibles para el agente con las del host; verifica permisos y que Docker use los mismos directorios.
Host en línea pero vista previa fallida: revisa por separado inicio de aplicación, DNS privado, ingreso, TLS y VPN del navegador. El registro WSS no verifica las rutas de la aplicación.
Base de datos no disponible: revisa la salud de PostgreSQL, la red core y la configuración del agente. No abras el puerto 5432 a internet para resolverlo.