Cómo instalar y ejecutar Odysseus AI: elige una ruta y verifica el primer acceso

Elige Docker, instalación nativa o una guía de plataforma

El proyecto oficial suele presentar Docker Compose como un punto de partida repetible. Mantiene la aplicación y los servicios auxiliares en una pila conocida, facilita reconstruir un entorno limpio y reduce los paquetes que debes administrar en el sistema anfitrión. La desventaja es que los contenedores cambian el significado de localhost: el localhost de un servicio dentro de la red de Odysseus no es automáticamente el localhost de tu navegador.

La instalación nativa sirve cuando necesitas controlar procesos, depurar Python o aprovechar el comportamiento de aceleración de tu sistema operativo. También hace más visibles las rutas y los puertos del host, pero tú debes mantener el entorno Python, las dependencias y la limpieza. En Windows conviene seguir la guía específica, porque WSL2, Docker Desktop, PowerShell y Ollama pueden añadir varias capas de red.

Comprueba el equipo antes de instalar

Muchos fallos del primer inicio son problemas del entorno. Antes de clonar el repositorio, decide dónde vivirá la aplicación, dónde se guardarán los datos persistentes y si el modelo estará en el mismo equipo, en otro host o todavía no se conectará. No añadas todas las integraciones durante el primer arranque; una base pequeña facilita encontrar el límite del error.

Reserva almacenamiento para el código, los contenedores, los registros, los modelos y los datos de documentos. La memoria y la VRAM de un modelo local son un problema distinto de los requisitos del espacio de trabajo. La guía de requisitos explica por qué una interfaz relativamente ligera puede convivir con una carga de inferencia mucho mayor.

Para el primer arranque, usa un navegador en el mismo equipo y una dirección de loopback. El acceso LAN, un proxy inverso, Tailscale o una exposición pública deben esperar hasta que cambies la contraseña de administrador y sepas qué proceso ocupa cada puerto.

• Confirma Git, Docker Compose o el runtime nativo que corresponda a la ruta elegida.
• Reserva una carpeta persistente para el repositorio, .env, volúmenes, registros y copias.
• Mantén la primera prueba en localhost y no enlaces todos los servicios a 0.0.0.0.
• Anota si Ollama y SearXNG se ejecutarán en el host, en Docker o en otra máquina.
• Compara siempre los comandos con el README y la guía de instalación actuales.

Instala e inicia el espacio de trabajo

Para el primer intento, Docker suele ofrecer la ruta más corta hacia una base repetible. Clona el repositorio oficial, revisa el README actual, copia el archivo de entorno de ejemplo cuando exista e inicia Compose. Mantén alineadas la rama y la guía de instalación; no inventes una versión ni supongas que un tutorial antiguo describe el estado actual.

La ruta nativa sigue la misma lógica con más responsabilidad en el host: crea el entorno Python compatible, instala las dependencias documentadas, ejecuta la configuración y arranca el proceso. En Windows, usa el lanzador del proyecto o la guía de Windows, en lugar de mezclar comandos de Linux con Docker Desktop.

1. Inicia solo la base

   No añadas proxy, acceso LAN, descarga de modelos y búsqueda al mismo tiempo. El primer objetivo es un proceso saludable.

2. Lee los registros antes de cambiar puertos

   Si el navegador no conecta, revisa la salud y los logs. Cambiar la URL no arregla un proceso que terminó durante la carga.

3. Mantén visible la rama

   El proyecto puede diferenciar una rama de desarrollo de una rama más curada. Comprueba la rama y las notas actuales antes de repetir comandos antiguos.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
./start-macos.sh

Conecta Ollama y la búsqueda por separado

Cuando el espacio de trabajo ya abre, añade el backend del modelo. Si Ollama y Odysseus se ejecutan de forma nativa en el mismo host, localhost puede ser correcto. Si Odysseus está en Docker y Ollama está en el host, localhost vuelve al contenedor; usa la dirección de gateway indicada en la guía de Docker. Prueba el endpoint desde el mismo entorno de red que usa la aplicación.

La búsqueda es otro límite de servicio. El SearXNG incluido puede usar el nombre del servicio de Compose, mientras que una instancia externa necesita una URL accesible desde Odysseus. Que la página abra no demuestra que el modelo o la búsqueda funcionen: ejecuta una petición pequeña al modelo y una prueba de búsqueda independiente.

No expongas Ollama o SearXNG solo porque el espacio de trabajo sea accesible. Cada servicio tiene sus propias decisiones de autenticación, binding y actualización.

Verifica el primer acceso antes de trabajar

El primer acceso es un punto de control operativo. Abre el puerto local indicado por la ruta actual, confirma que la página pertenece al espacio que acabas de iniciar y cambia inmediatamente la contraseña temporal. Si aparece una página vacía o un proxy inverso, vuelve primero a la dirección local directa.

Después del acceso, comprueba que Settings puede ver los servicios que quieres usar. Empieza con una tarea pequeña que no necesite archivos sensibles: pide un resumen corto, revisa la respuesta y detén la ejecución si no entiendes el plan o los cambios propuestos.

1. Llega a la página local

   Usa el puerto que muestran los logs y la ruta oficial actual. No des por bueno un puerto de un artículo antiguo.

2. Cambia las credenciales

   Sustituye la contraseña generada antes de experimentar con LAN, VPN o proxy inverso.

3. Prueba el modelo

   Envía un prompt pequeño y confirma el proveedor y el modelo seleccionados.

4. Prueba el flujo

   Abre un proyecto de ejemplo, revisa el plan y conserva la aprobación manual hasta conocer el comportamiento.

Crea un proceso de ejecución repetible

Un inicio fiable separa cuatro decisiones: preparación del equipo, arranque de la aplicación, conexión de servicios y aprobación del usuario. Si las mezclas, todos los errores parecen errores del modelo. Si las separas, sabrás si falló el proceso, el puerto, el endpoint o la propia tarea.

Guarda un pequeño runbook junto al repositorio. Anota la ruta elegida, la URL local, la rama o commit probado, el endpoint del modelo, el endpoint de búsqueda, la carpeta de datos y el comando para detener la pila.

Resuelve los fallos frecuentes

La mayoría de los fallos iniciales pertenecen a una de estas categorías: proceso no saludable, puerto incorrecto, localhost visto desde otro contenedor, servicio opcional inaccesible o volumen/credencial mal interpretado. Empieza por la capa más pequeña que falla y no cambies varias variables a la vez.

Si sigues un vídeo o tutorial comunitario, compara su rama, puerto, variables y nombres de servicio con el repositorio oficial. Un tutorial puede ser útil y estar desactualizado al mismo tiempo.

Actualiza sin perder el control

No existe un comando de actualización universal que sustituya la lectura de las instrucciones actuales. Antes de hacer pull o reconstruir contenedores, guarda los datos importantes, anota la rama o commit probado y comprueba si cambiaron variables o nombres de servicios. Un rebuild puede ser una operación con estado cuando hay volúmenes, documentos o credenciales.

Para un despliegue Docker, detén e inspecciona la pila antes de recrearla. Para un despliegue nativo, conserva el entorno y los cambios que entiendes, y actualiza dependencias de forma deliberada. Si el servicio debe salir de localhost, prepara autenticación, HTTPS, controles de red y una forma de rollback.