Cómo instalar LobeHub con Docker paso a paso

Si estás cansado de depender de una sola empresa de inteligencia artificial y quieres controlar dónde se almacenan tus conversaciones, LobeHub es una de las plataformas más completas que puedes instalar en tu propia infraestructura. No es solamente una interfaz de chat, sino un espacio de trabajo para crear y organizar agentes, conectar diferentes modelos y trabajar con archivos, herramientas y bases de conocimientos.

Además, puedes utilizar proveedores comerciales como OpenAI, Anthropic, Google u OpenRouter y combinarlos con modelos ejecutados localmente mediante Ollama. Esto facilita evitar que la IA acceda a información privada, siempre que configures correctamente los modelos, el almacenamiento y las integraciones externas.

LobeHub es un proyecto autohospedable y con su código disponible públicamente. Su despliegue oficial mediante Docker Compose permite instalar la aplicación, la base de datos, el almacenamiento de archivos y otros servicios auxiliares sin tener que configurar cada componente desde cero.

Eso sí, instalar la plataforma en tu servidor no garantiza por sí solo que toda la información permanezca en él. Si conectas un modelo alojado en la nube, los mensajes necesarios para generar la respuesta se enviarán al proveedor seleccionado. Para mantener todo el procesamiento dentro de tu infraestructura también tendrás que utilizar modelos, embeddings y herramientas locales.

Qué necesitas para instalar LobeHub con Docker

Antes de comenzar, necesitas un ordenador o servidor con una distribución compatible y acceso a una terminal. El procedimiento oficial utiliza un script interactivo que descarga los archivos necesarios y prepara las variables del entorno.

Estos son los requisitos principales:

• Docker Engine: se encarga de ejecutar los contenedores.
• Docker Compose v2: permite iniciar y administrar todos los servicios como una sola aplicación.
• curl y OpenSSL: el script los utiliza para descargar la configuración y generar secretos.
• Espacio persistente: necesario para conservar la base de datos y los archivos subidos.
• Un dominio: opcional para pruebas, pero muy recomendable si vas a publicar la aplicación en Internet.
• Una clave o servidor de modelos: LobeHub proporciona la plataforma, pero necesita conectarse a un proveedor de IA o a un modelo local.

Para un uso personal ligero, la documentación recomienda como mínimo 2 núcleos de CPU, 4 GB de RAM y 20 GB de almacenamiento. Para una instalación utilizada por varias personas, el punto de partida recomendado aumenta a 4 núcleos, 8 GB de RAM y 50 GB de almacenamiento o más.

Estos requisitos corresponden a la plataforma y sus servicios. Si también quieres ejecutar modelos locales en el mismo servidor, tendrás que sumar la memoria RAM, la VRAM y el almacenamiento que necesite cada modelo.

Servicios incluidos en el despliegue oficial

LobeHub no funciona como un único contenedor aislado. Aunque los componentes fundamentales son la aplicación, una base de datos compatible con PostgreSQL y un almacenamiento S3, el archivo Compose oficial despliega varios servicios coordinados:

• LobeHub: ejecuta la aplicación web, los agentes, las conversaciones y la administración.
• PostgreSQL mediante ParadeDB: almacena usuarios, conversaciones, configuraciones y los datos necesarios para las búsquedas.
• Redis: proporciona almacenamiento rápido y persistencia mediante AOF para determinadas operaciones internas.
• RustFS: actúa como almacenamiento de objetos compatible con el protocolo S3.
• rustfs-init: prepara el bucket utilizado por LobeHub durante el primer arranque.
• SearXNG: permite incorporar búsquedas web a los agentes cuando esta función está habilitada.

Docker Compose crea una red privada para que estos servicios puedan encontrarse mediante sus nombres internos. También configura volúmenes persistentes para evitar que la información desaparezca al reiniciar o sustituir los contenedores.

Opciones de despliegue con Docker

El script oficial ofrece tres modos. La elección determina desde dónde podrás acceder a LobeHub y qué direcciones se guardarán en el archivo de configuración.

Modo local

Es la alternativa adecuada para probar LobeHub en el mismo ordenador donde se ejecuta Docker. La aplicación queda disponible normalmente en una dirección como:

http://localhost:3210

Este modo no está pensado para que entren otros dispositivos de la red ni para publicar la plataforma en Internet.

Modo puerto

Permite acceder mediante la dirección IP del servidor y un puerto. Por ejemplo:

http://192.168.1.50:3210

Resulta útil dentro de una red local, aunque tendrás que comprobar el cortafuegos del servidor. Si pretendes utilizarlo desde Internet, es preferible pasar al modo dominio y habilitar HTTPS.

Modo dominio

Es la opción apropiada para una instalación permanente o utilizada por un equipo. Requiere configurar un proxy inverso, certificados HTTPS y, normalmente, dos dominios o subdominios:

• Uno para la aplicación, como ia.ejemplo.com.
• Otro para el almacenamiento S3, como s3.ejemplo.com.

El segundo dominio es importante porque el navegador debe poder acceder a determinados archivos almacenados en RustFS. No basta con utilizar el nombre interno del contenedor.

Cómo instalar LobeHub mediante Docker Compose

Primero crea una carpeta para la instalación y entra en ella:

mkdir lobehub-db
cd lobehub-db

Después ejecuta el script oficial de configuración:

bash <(curl -fsSL https://lobe.li/setup.sh)

El asistente solicitará el modo de despliegue y las direcciones que se utilizarán. También descargará archivos como docker-compose.yml, .env, la configuración del bucket de RustFS y los ajustes de SearXNG.

Durante el proceso se generan contraseñas y secretos utilizados para proteger la base de datos, el almacenamiento, las sesiones y las credenciales guardadas. No publiques el contenido del archivo .env ni lo subas a un repositorio.

Cuando termine la configuración, inicia todos los servicios:

docker compose up -d

La primera puesta en marcha puede tardar un poco porque Docker tiene que descargar las imágenes, crear la base de datos, iniciar RustFS y ejecutar las migraciones.

Cómo comprobar que LobeHub se ha iniciado correctamente

Consulta el estado de los contenedores mediante:

docker compose ps

Los servicios principales deberían aparecer iniciados o en estado saludable. Para seguir los registros en tiempo real, utiliza:

docker compose logs -f

También puedes consultar únicamente los registros de la aplicación:

docker logs -f lobehub

Durante un arranque correcto deberías ver que la migración de la base de datos termina satisfactoriamente y que el servidor queda listo para aceptar conexiones.

En el modo local, abre en el navegador:

http://localhost:3210

En los modos puerto o dominio tendrás que utilizar la dirección mostrada por el asistente de configuración.

Configuraciones críticas para el funcionamiento

El script prepara automáticamente la mayor parte de la instalación, pero conviene conocer las variables que provocan más problemas cuando se cambia el dominio, el puerto o la arquitectura de red.

APP_URL

APP_URL es la dirección pública desde la que los usuarios acceden a LobeHub. También se utiliza en devoluciones OAuth, webhooks y otros enlaces generados por la aplicación.

En una instalación con dominio podría tener este valor:

APP_URL=https://ia.ejemplo.com

El protocolo, dominio y puerto deben coincidir con la dirección real utilizada en el navegador. Si colocas LobeHub detrás de un proxy inverso, este deberá enviar correctamente las cabeceras de protocolo y host.

INTERNAL_APP_URL

INTERNAL_APP_URL se utiliza para las solicitudes internas que LobeHub realiza contra su propia aplicación. Algunas funciones asíncronas, como la generación de imágenes, pueden fallar si el contenedor intenta acceder a una dirección pública que no es alcanzable desde su red.

En el Compose oficial se utiliza normalmente:

INTERNAL_APP_URL=http://localhost:3210

También puede emplearse una dirección interna accesible desde la red de Docker. Su finalidad es evitar que estas llamadas tengan que atravesar un proxy, una CDN o la red externa del anfitrión.

S3_ENDPOINT

S3_ENDPOINT identifica la dirección desde la que se sirven los objetos almacenados en RustFS. En un despliegue con dominio puede configurarse así:

S3_ENDPOINT=https://s3.ejemplo.com

No debes introducir simplemente http://rustfs:9000 como dirección pública. Ese nombre solamente se resuelve dentro de la red de Docker y el navegador no podrá utilizarlo para abrir las imágenes o archivos.

DATABASE_URL y contraseñas

La cadena DATABASE_URL conecta LobeHub con PostgreSQL. La contraseña debe coincidir con POSTGRES_PASSWORD y el nombre de la base de datos con el definido en LOBE_DB_NAME.

Evita modificar estas variables después de haber creado la base de datos, salvo que también actualices las credenciales del servicio correspondiente.

Cómo proteger el acceso y el registro de usuarios

LobeHub 2.0 utiliza Better Auth como sistema de autenticación. Las guías antiguas basadas en Clerk o NextAuth ya no son aplicables a las versiones actuales.

El despliegue admite inicio de sesión mediante correo y contraseña, proveedores OAuth y sistemas SSO compatibles. En una instancia expuesta a Internet, comprueba las opciones de registro antes de compartir la dirección.

Para una instalación privada puedes utilizar AUTH_ALLOWED_EMAILS y limitar el acceso a determinadas direcciones:

AUTH_ALLOWED_EMAILS=usuario@ejemplo.com,otro@ejemplo.com

Cuando utilices exclusivamente un proveedor SSO también puedes desactivar el acceso mediante correo y contraseña:

AUTH_DISABLE_EMAIL_PASSWORD=1

Después de modificar el archivo .env, vuelve a crear el contenedor de la aplicación para aplicar los cambios:

docker compose up -d --force-recreate lobe

No expongas directamente PostgreSQL, Redis ni la consola administrativa de RustFS a Internet. En una instalación con dominio, publica solamente los servicios estrictamente necesarios mediante HTTPS y restringe el resto con el cortafuegos o la red interna de Docker.

Cómo conectar los modelos de inteligencia artificial

LobeHub es agnóstico respecto al proveedor. Puedes conectarlo a servicios comerciales o a servidores de inferencia controlados por ti.

Entre las alternativas disponibles se encuentran OpenAI, Anthropic, Google, OpenRouter y distintos proveedores compatibles con la API de OpenAI. También puedes utilizar modelos locales a través de Ollama u otros servidores compatibles.

Las claves pueden configurarse mediante variables del servidor o, según el proveedor y la configuración de la instancia, desde los ajustes de LobeHub. En una instalación compartida suele ser preferible que el administrador gestione las credenciales y decida qué modelos estarán disponibles.

Si el proveedor se ejecuta en otro contenedor, no utilices localhost para referirte a él. Dentro de Docker, esa dirección apunta al propio contenedor de LobeHub. Tendrás que utilizar el nombre del servicio, una dirección de la red interna o una URL accesible desde el contenedor.

Más allá del chat: funciones avanzadas de LobeHub

Una de las funciones más interesantes de LobeHub es su compatibilidad con el Model Context Protocol. La plataforma actúa como cliente MCP, descubre las herramientas ofrecidas por los servidores compatibles, administra las conexiones y envía las solicitudes del agente al servicio correspondiente.

Los servidores disponibles en el Marketplace permiten ampliar las capacidades de los agentes. También puedes añadir manualmente un servidor MCP compatible cuando la integración que necesitas no aparece en el catálogo.

Debes revisar cuidadosamente los permisos de cada conexión. Un servidor MCP puede permitir que el agente consulte servicios externos, lea archivos o ejecute acciones. Instalar LobeHub en tu servidor no elimina los riesgos de conceder acceso excesivo a una herramienta.

Otro punto fuerte es la gestión del conocimiento. Puedes subir documentos, hojas de cálculo, imágenes, audios y vídeos para crear una biblioteca de recursos. Esto permite convertir PDFs con IA, consultar información interna y asociar bases de conocimientos a agentes o espacios de trabajo.

La plataforma procesa el contenido compatible y utiliza técnicas de recuperación para seleccionar la información relacionada con la pregunta. Después, el modelo genera la respuesta tomando esos fragmentos como contexto. La precisión dependerá del documento, del modelo de embeddings, de la búsqueda y del modelo generativo utilizado.

LobeHub también ofrece funciones multimodales para trabajar con imágenes, audio y archivos, aunque su disponibilidad final depende del modelo seleccionado. Un modelo exclusivamente textual no podrá analizar una imagen aunque la interfaz permita subirla.

Cómo actualizar LobeHub

Antes de actualizar una instalación utilizada en producción, realiza una copia de seguridad de la base de datos, los archivos y la configuración.

Después puedes descargar las imágenes actuales y volver a crear los contenedores:

docker compose pull
docker compose up -d

Comprueba el arranque y las migraciones mediante:

docker compose logs -f

No conviene automatizar las actualizaciones importantes sin disponer de una copia restaurable. Una nueva versión puede incluir migraciones de la base de datos o variables adicionales que requieran revisar la configuración.

Cómo realizar una copia de seguridad

Una copia completa debe incluir la base de datos, los objetos almacenados en RustFS y los archivos de configuración. Guardar solamente PostgreSQL no permitirá recuperar las imágenes y documentos subidos.

Copia de PostgreSQL

Si mantienes el nombre predeterminado de la base de datos, puedes exportarla mediante:

docker compose exec postgresql pg_dump -U postgres lobechat > backup.sql

Para restaurarla:

docker compose exec -T postgresql psql -U postgres lobechat < backup.sql

Si has cambiado LOBE_DB_NAME, sustituye lobechat por el nombre real.

Copia de RustFS

Para empaquetar los datos del almacenamiento:

docker compose exec rustfs tar czf /tmp/backup.tar.gz /data
docker cp lobe-rustfs:/tmp/backup.tar.gz ./rustfs-backup.tar.gz

Guarda también el archivo .env, docker-compose.yml y los archivos de configuración de RustFS y SearXNG. El archivo .env contiene información sensible y debe almacenarse cifrado o en una ubicación protegida.

Mantenimiento y resolución de problemas

Algún servicio no arranca

Comprueba primero su estado:

docker compose ps
docker compose logs NOMBRE_DEL_SERVICIO

Los motivos más habituales son un puerto ocupado, poco espacio en el disco, una contraseña que no coincide o un servicio del que depende LobeHub que todavía no está saludable.

El puerto 3210 está ocupado

Cambia LOBE_PORT en el archivo .env y vuelve a crear los contenedores. Recuerda actualizar también la dirección pública si accedes mediante IP y puerto.

LobeHub no puede conectarse a PostgreSQL

Comprueba la salud de la base de datos:

docker compose exec postgresql pg_isready -U postgres

Después revisa sus registros:

docker compose logs postgresql
docker compose logs lobe

Verifica que POSTGRES_PASSWORD, LOBE_DB_NAME y DATABASE_URL sean coherentes.

Las imágenes o documentos no se abren

Consulta los registros de RustFS:

docker compose logs rustfs
docker compose logs rustfs-init

Comprueba también que S3_ENDPOINT sea accesible desde el navegador. En un despliegue remoto no puede apuntar a localhost ni al nombre interno del contenedor.

El dominio abre, pero algunas funciones fallan

Revisa que APP_URL utilice la dirección pública correcta y que INTERNAL_APP_URL permita al contenedor acceder internamente a la propia aplicación. Comprueba también que el proxy inverso envíe las cabeceras Host, X-Forwarded-For y X-Forwarded-Proto.

No aparece ningún modelo

Verifica que la clave del proveedor sea válida, que la URL de su API sea accesible desde el contenedor y que el modelo no esté oculto mediante la configuración de la lista. Si utilizas un servidor local, prueba su API desde la misma red donde se ejecuta LobeHub.

El servidor se queda sin espacio

Consulta el uso de Docker y del sistema de archivos:

docker system df
df -h

Las imágenes antiguas, los registros, PostgreSQL y los archivos de RustFS pueden crecer con el tiempo. No elimines volúmenes ni datos sin comprobar primero qué contienen y disponer de una copia de seguridad.

Instalar LobeHub con Docker permite crear un centro de trabajo con agentes, diferentes modelos, herramientas MCP y conocimientos privados dentro de una infraestructura controlada. El procedimiento oficial simplifica considerablemente el despliegue, pero sigue siendo importante configurar correctamente las direcciones públicas, el almacenamiento S3, la autenticación y las copias de seguridad.

Para una prueba personal, el modo local es suficiente. Si otras personas van a utilizar la plataforma, emplea un dominio con HTTPS, restringe el registro, protege los servicios internos y comprueba que ninguna integración envíe información fuera de la infraestructura sin que los usuarios lo sepan.