neogeeks/geekindex repository overview

⁠Brain (geekIndex)

El chat de tu equipo donde los agentes de IA son miembros, no un chatbot aparte. Con el conocimiento de la empresa dentro, permisos por colección, y tareas que se siguen solas.

Un contenedor: app, Postgres, worker y servicio de grafo. Multi-arquitectura (linux/amd64 y linux/arm64), así que el mismo comando sirve en un servidor Linux, en un Mac con Apple Silicon y en Windows con Docker Desktop.

docker pull neogeeks/geekindex:latest

⁠1. Arrancar

Lo mínimo que funciona, para probarlo en tu máquina:

docker run -d --name brain \
  -p 3000:3000 \
  -v brain-datos:/data \
  -e SITE_URL=http://localhost:3000 \
  -e GEEKINDEX_PUBLIC_URL=http://localhost:3000 \
  neogeeks/geekindex:latest

Abre http://localhost:3000 y el asistente de instalación te pide el primer administrador. Los secretos se generan solos en el primer arranque y se guardan en el volumen: no hay que inventarse SESSION_SECRET ni JWT_SECRET.

Tarda unos segundos la primera vez (crea la base y aplica migraciones). Para ver qué hace: docker logs -f brain.

⁠El código de reclamación

Para crear ese primer administrador hace falta un código de un solo uso que la instancia imprime en su log:

docker logs brain 2>&1 | grep -A6 "CÓDIGO DE RECLAMACIÓN"

También queda en /data/reclamacion-admin.txt dentro del volumen, con permisos 600.

Para qué sirve. Una instalación nueva arranca funcionando y sin administrador, así que la pantalla que crea el primero tiene que ser pública — todavía no hay nadie a quien pedirle permiso. Sin código, entre que arranca el contenedor y tú abres el asistente, cualquiera que llegue a esa dirección se queda como administrador de la instalación entera. El código solo se puede leer desde el anfitrión, que es donde tú ya eres dueño de todo.

Si lo pierdes, se emite otro: borra la fila reclamacion_admin de app_settings y recarga /setup. Con GEEKINDEX_ADMIN_EMAIL y GEEKINDEX_ADMIN_PASSWORD no hace falta código — el administrador ya existe antes de que nadie abra el asistente.

⁠Con tu dominio, que es como va en producción

docker run -d --name brain --restart unless-stopped \
  -p 3000:3000 \
  -v brain-datos:/data \
  -e GEEKINDEX_DOMAIN=brain.tuempresa.com \
  -e GEEKINDEX_PUBLIC_URL=https://brain.tuempresa.com \
  -e SITE_URL=https://brain.tuempresa.com \
  -e GEEKINDEX_TZ=America/Panama \
  neogeeks/geekindex:latest

GEEKINDEX_DOMAIN decide además si la cookie de sesión va como Secure, así que ponlo cuando haya HTTPS delante (un proxy inverso: Caddy, nginx, Cloudflare Tunnel).

⁠En Windows

Funciona igual —Docker baja la imagen amd64 sola—, con dos diferencias:

• Usa un volumen de Docker (-v brain-datos:/data), no una carpeta de C:\. El traductor de rutas cambia los permisos de los ficheros del corpus.
• --network host no existe en Docker Desktop. Si además vas a instalar el conector de un agente en esa máquina, la URL de despertar tiene que ser http://host.docker.internal:PUERTO.

⁠El volumen, que es todo lo que hay que respaldar

/data contiene la base de datos, el corpus (los .md de las colecciones), los originales subidos y los secretos. Respaldar eso es respaldar Brain.

⁠2. Actualizaciones automáticas (Watchtower)

Brain sabe cuándo hay una versión nueva y no puede bajarla solo: un contenedor no se reemplaza a sí mismo. Hace falta alguien fuera, y ese alguien es Watchtower. Sin esto, el botón «Actualizar ahora» de la pantalla de configuración existe y no hace nada — y eso se descubre el día que hace falta.

Dos cosas que hay que saber antes:

1. La etiqueta tiene que moverse. Watchtower compara el digest del tag que corre tu contenedor. Con neogeeks/geekindex:0.17.76 clavado, ese tag no cambia nunca y no hay nada que actualizar. Usa :latest.
2. Watchtower monta el socket de Docker. Es la única forma de parar y recrear contenedores, y significa que puede hacer cualquier cosa con Docker en ese host — en la práctica, root. Es el precio de la actualización automática y conviene saberlo antes, no después.

docker-compose.yml:

services:
  brain:
    image: neogeeks/geekindex:latest      # sin número: tiene que moverse
    restart: unless-stopped
    ports: ["3000:3000"]
    volumes: ["brain-datos:/data"]
    environment:
      GEEKINDEX_DOMAIN: brain.tuempresa.com
      GEEKINDEX_PUBLIC_URL: https://brain.tuempresa.com
      SITE_URL: https://brain.tuempresa.com
      GEEKINDEX_TZ: America/Panama
    labels:
      # Watchtower solo toca lo que lleva esta etiqueta. Sin esto actualizaría
      # TODOS los contenedores del host, incluidos los que no son tuyos.
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes: ["/var/run/docker.sock:/var/run/docker.sock"]
    environment:
      # Solo API: no vigila por su cuenta, espera a que Brain se lo pida.
      WATCHTOWER_HTTP_API_UPDATE: "true"
      WATCHTOWER_HTTP_API_TOKEN: "${WATCHTOWER_TOKEN:?define WATCHTOWER_TOKEN}"
      WATCHTOWER_LABEL_ENABLE: "true"
      # Borra la imagen vieja. Sin esto el disco crece con cada versión hasta
      # que un día la base no arranca por falta de espacio.
      WATCHTOWER_CLEANUP: "true"
    # El puerto NO se publica: Brain lo alcanza por la red interna del compose.
    # Publicarlo sería exponer «recrea mis contenedores» a la LAN.

volumes:
  brain-datos:

En tu .env, al lado del compose:

WATCHTOWER_TOKEN=<openssl rand -hex 32>

Ese token permite recrear contenedores en ese servidor: trátalo como una contraseña de administración.

Y decírselo a Brain: Configuración → la tarjeta de versión → configurar el actualizador

• URL: http://watchtower:8080/v1/update
• Token: el mismo WATCHTOWER_TOKEN

Desde ahí, «Actualizar ahora» funciona y la casilla de actualización automática también. Quién puede aplicarla es una persona concreta, no cualquier admin: por defecto el administrador fundador, y se cambia por ajuste o con GEEKINDEX_ACTUALIZA_EMAIL. Reiniciar el contenedor tira las sesiones de quien esté dentro y corre migraciones — la decisión de cuándo es de quien responde por esa instalación.

⁠3. El modelo de Brain, y por qué importa

Brain funciona sin modelo: el chat entre personas, las colecciones, los permisos y los canales van igual. Lo que no funciona sin modelo es todo lo que piensa, y eso incluye cosas que no parecen de IA:

Brain-PM es el que más se nota: es el que te habla en tu privado cuando una tarea vence, cuando alguien pide más plazo o cuando algo lleva días sin moverse. Sin modelo designado, esos avisos salen como mensajes de sistema — correctos y secos.

⁠Registrar un modelo

Configuración → Modelos → Registrar. Se acepta:

La distinción que importa: un endpoint local no tiene clave y exigírsela lo dejaría fuera del producto, que es justo el caso on-prem. Un proveedor de nube sin clave, en cambio, no es una configuración parcial: no es nada.

La clave se guarda cifrada y no vuelve a salir en pantalla. Al guardar puedes probar la conexión ahí mismo: si contesta, está listo.

⁠ChatGPT como modelo de Brain

Sí, y es el camino más corto para tener Brain-PM funcionando:

1. Configuración → Modelos → Registrar
2. Proveedor openai, modelo gpt-5 (o el que uses), URL vacía, y tu API key de OpenAI.
3. Probar la conexión.
4. Designarlo como Brain-PM en la fila del modelo.

Un modelo gestionado no es un agente: no tiene credencial propia, no mantiene ninguna conexión y no hay nada que instalar del otro lado. Brain lo conduce y solo habla cuando se le menciona o cuando le toca conducir una tarea.

Y un aviso que no es menor: agregar un modelo a un canal autoriza que el contenido de ese canal salga hacia su proveedor. Por eso lo decide un administrador canal por canal, y no se hace solo.

⁠4. Conectar un agente

Un agente sí es distinto: corre un proceso tuyo —OpenClaw, Hermes, un script— que decide y contesta por su cuenta. Necesita credencial y un conector.

Ajustes → Agentes → Conectar un agente, y son cuatro pasos:

1. Nombre — como lo van a llamar en el chat. El que quieras.
2. Colecciones — qué puede consultar. Solo lectura; lo que no marques no existe para él.
3. Qué agente es — OpenClaw o Hermes. Si eliges OpenClaw te pide su id, que sale de openclaw agents list. Cópialo de la primera línea, no de la Identity: el agente principal se llama main aunque su identidad diga «Charli», y con el id equivocado el despertar falla en cada mensaje.
4. Conectar — te da un comando. Lo pegas en la máquina donde vive el agente (o se lo pasas al propio agente por Telegram, si ya hablas con él).

El modal se queda mirando: verás subir la escalera de conexión y, cuando esté listo, Brain le escribe una prueba y espera su respuesta. Cuando contesta, Salir — y ya está en la lista.

⁠Lo que hace ese comando

Arranca el conector (brain-bridge), un proceso pequeño que vive al lado de tu agente. Es el único que habla con Brain: mantiene la conexión, guarda los mensajes si se cae la red, reintenta, y cuando llega trabajo le da un toque a tu agente.

Brain  ──(conexión permanente)──►  Conector  ──(un toque)──►  Tu agente

Dos cosas que ahorran una tarde:

• El conector va donde vive el agente, no en el servidor de Brain. Si lo metes en un contenedor, el comando de despertar se ejecuta dentro de ese contenedor, donde tu agente no está.
• Varios agentes en la misma máquina: cada uno lleva su propio BRAIN_HOME, así que no se pisan el cursor. La línea que te da la pantalla ya lo trae.

⁠Probar tu runtime antes de dar de alta nada

Si tu agente no es OpenClaw, el contrato es corto: el mensaje llega en el archivo $BRAIN_EVENT_FILE (JSON, el texto en message.body_md), lo que el comando escriba es la respuesta, y exit 0 significa «acepto el trabajo».

Y se puede verificar sin Brain de por medio, en la máquina del agente:

curl -fsSL https://brain.tuempresa.com/bridge.sh -o bridge.sh
BRAIN_WAKE_STDOUT_ES_RESPUESTA=1 BRAIN_WAKE_CMD='TU-COMANDO' sh bridge.sh --probar

Dice si arrancó, cuánto tardó y el texto exacto que Brain publicaría. Si falla, reconoce las averías conocidas y dice qué cambiar.

⁠Las tareas de un agente no se persiguen: se observan

A un agente no se le pone fecha de entrega, se le declara «avisarme si no hay resultado en [N]». Brain no le pregunta nunca «¿cómo vas?» — mira su actividad y te avisa a ti si se atasca, con botones para reintentar o reasignar. Un agente no llega tarde: se atasca, y eso se arregla distinto.

⁠5. Orden recomendado para dejarlo operativo

1. Arrancar el contenedor y crear el primer administrador, con el código de reclamación que sale en el log (docker logs brain | grep -A6 RECLAMACIÓN).
2. Zona horaria (GEEKINDEX_TZ): decide el «hoy» de los plazos y de las estadísticas.
3. Modelo y probarlo. Designar Brain-PM.
4. Correo saliente (SMTP) en Configuración: sin él no se pueden enviar invitaciones ni recuperar contraseñas.
5. Primera colección, con una descripción de verdad — es lo que los agentes leen para decidir a qué colección va cada pregunta.
6. Subir conocimiento y aprobar los borradores.
7. Invitar a tu equipo y crear los canales por tema.
8. Watchtower y su token, para que las actualizaciones sean un botón.
9. Conectar los agentes, si los hay.

El tour de bienvenida lleva por los puntos 2 a 8 la primera vez que entras como administrador, y está siempre en Ayuda.

⁠Variables de entorno

Ninguna es obligatoria salvo las de dominio: el resto tiene valor por defecto o se configura desde la pantalla.

⁠Salud y diagnóstico

• Configuración → Estado dice qué falta y con qué enlace arreglarlo: sin modelo, sin correo, sin índice, un agente caído.
• GET /api/instance responde sin sesión: sirve para saber si está vivo ({"product":"brain", ...}).
• Ajustes → Agentes → la ficha de un agente enseña su escalera de conexión y en qué peldaño se quedó, con el comando que falta.

⁠Soporte

Producto de ponteGEEK. El soporte va por la instancia de tu organización o por el canal que te haya dado quien te la instaló.