Instalar Odysseus AI en macOS: Apple Silicon, Docker y Ollama

Elige la ruta de Mac según lo que quieras probar primero

Si solo quieres comprobar que el workspace de Odysseus AI arranca, Docker es una ruta controlada porque encapsula dependencias y se parece al flujo general de quick start. Si quieres que el Mac use runtimes locales de modelos con menos fricción, especialmente en Apple Silicon, la ruta nativa suele ser la mejor primera prueba.

La clave no es que una ruta sea siempre superior. Cada una responde una pregunta distinta: Docker confirma si la app levanta en un contenedor reproducible; la ruta nativa confirma si tu Mac puede ejecutar el workspace cerca de los modelos, archivos y herramientas locales que ya usas.

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

Ruta nativa Apple Silicon: valida el entorno antes del modelo

La ruta nativa en macOS importa porque muchos usuarios de Apple Silicon quieren mantener Ollama, modelos locales y archivos cerca del workspace. Haz primero las comprobaciones aburridas: repositorio actual, script ejecutable, dependencias de Python limpias y puerto local accesible.

Un primer arranque correcto debe mostrar una interfaz local alcanzable y pedir que completes la configuración o el inicio de sesión. Trata las contraseñas generadas y secretos locales como datos temporales de operación, no como contenido para capturas públicas.

1. Clona el repositorio oficial

Usa el repositorio oficial como fuente de verdad para scripts, issues y cambios del README. Evita comandos copiados cuando contradicen el estado actual del proyecto.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

2. Ejecuta el launcher de macOS y lee el primer error

El primer fallo suele indicar permisos, Python, dependencias o conflicto de puerto. Corrige esa capa antes de tocar endpoints de modelos.

chmod +x ./start-macos.sh
./start-macos.sh

3. Abre la UI local y completa el primer login

Si la app arranca en el puerto local documentado, usa esa URL en el navegador y cambia cualquier credencial temporal según los prompts actuales.

http://127.0.0.1:7860

4. Configura modelos solo después

Cuando el workspace esté sano, conecta Ollama u otro proveedor desde Settings. Depurar modelos antes de que la app funcione oculta el problema real.

http://127.0.0.1:11434/v1

Docker en macOS: aislamiento útil, pero con coste

Docker sigue siendo válido en Mac cuando buscas una prueba descartable, una frontera limpia de dependencias o una ejecución parecida a un servidor. Es menos ideal si tu objetivo principal es usar aceleración local del Mac sin pensar en redes entre contenedor y host.

El error común es mezclar modelos mentales: dentro del contenedor, localhost es el contenedor; en el host, localhost es el Mac. Esa diferencia explica muchos fallos de endpoint.

Ollama, aceleración Metal y elección de endpoint

Ollama normalmente es un servidor de modelos separado; Odysseus AI no se convierte automáticamente en Ollama. En Mac esa separación ayuda: puedes mantener Ollama donde ya aprovecha el runtime local y apuntar Odysseus AI al endpoint compatible.

Usa 127.0.0.1 cuando Odysseus AI y Ollama corren nativos en el mismo Mac. Usa host.docker.internal cuando Odysseus AI corre en Docker y Ollama en el host. No abras Ollama a la LAN solo para que funcione una prueba local.

http://127.0.0.1:11434/v1

Solución de problemas de Odysseus AI en macOS

Avanza de arranque a red y luego a selección de modelo. Si la UI no está sana, los errores de modelo probablemente son secundarios.

Lista final para una instalación en Mac

Una instalación en Mac está lista cuando el workspace, el endpoint de modelo y el límite de seguridad están claros.

1. La UI abre localmente tras un arranque limpio.
2. Sabes si la ejecución es nativa, Docker o remota, y el endpoint coincide.
3. Ollama responde por separado antes de usarlo en Odysseus AI.
4. Un modelo pequeño funciona antes de probar agentes o documentos.
5. El workspace no está expuesto a red hasta definir auth y reglas.