Cómo instalar Odysseus AI en Linux: guía nativa y con Docker

Elige entre Linux nativo y Docker antes de instalar

Docker es la opción predeterminada si buscas el stack documentado, contenedores reproducibles y separación del host. La instalación nativa resulta útil para desarrollo, inspección directa de Python y Uvicorn o integración con herramientas del sistema sin capas de red de contenedores.

No necesitas instalar de forma nativa solo por usar un modelo local. Odysseus puede conectarse a Ollama, vLLM, SGLang u otro endpoint compatible desde cualquiera de los dos métodos. Docker tampoco garantiza GPU: los controladores del host, el runtime y el overlay deben exponer el dispositivo correcto.

Lista previa para Linux

Antes de clonar, confirma rama, intérprete, puerto, almacenamiento y ubicación de inferencia. El repositorio usa dev como rama predeterminada para los cambios más recientes y describe main como una rama más curada. No hay Releases, etiquetas ni binarios versionados oficiales, por lo que esta página no inventa una versión o un instalador más reciente.

Para la instalación nativa necesitas Python 3.11 o posterior. Para Docker, comprueba Engine y el complemento Compose. El puerto 7000 debe estar libre salvo que configures APP_PORT. Si Cookbook administrará descargas o procesos de modelos en Linux nativo, la guía oficial también indica tmux.

1. Selecciona dev o main

   dev recibe antes los cambios; main prioriza una selección más estable y curada.

2. Decide dónde corre el modelo

   Puede estar en este equipo, otro servidor o una API alojada.

3. Comprueba el puerto

   Verifica 7000 o elige otro APP_PORT antes de iniciar.

4. Mantén privado el primer arranque

   Usa 127.0.0.1 hasta cambiar la contraseña generada.

python3 --version
docker --version
docker compose version
ss -ltn | grep ':7000' || true

Instalación nativa de Odysseus AI en Linux

La ruta nativa crea un entorno virtual aislado, instala las dependencias, ejecuta la configuración del proyecto y arranca la aplicación ASGI con Uvicorn. Ejecuta los comandos como usuario normal dentro de una carpeta controlada. Evita sudo pip: mezcla paquetes del proyecto con Python del sistema y complica actualizaciones y limpieza.

El comando inicial escucha solo en loopback, que es lo correcto para la primera prueba. Añade systemd u otro supervisor únicamente después de validar el inicio interactivo, el login y un modelo. El servicio debe conservar el mismo directorio de trabajo, intérprete virtual y variables verificadas.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py

python -m uvicorn app:app --host 127.0.0.1 --port 7000

Instalar Odysseus AI con Docker Compose

El inicio rápido oficial recomienda Docker. Copiar .env.example es opcional, pero hace visibles los valores de despliegue. Construye e inicia los contenedores, espera los controles de salud y consulta los logs de Odysseus para obtener la contraseña temporal.

Compose vincula la interfaz a 127.0.0.1 por defecto. Si 7000 está ocupado, define APP_PORT=7001 u otro puerto libre en .env y vuelve a crear el contenedor. APP_BIND=0.0.0.0 no resuelve una colisión de puerto; la dirección de escucha y el puerto son decisiones distintas.

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

docker compose ps
docker compose logs odysseus --tail=120

Verifica el primer acceso antes de añadir modelos

Abre http://localhost:7000 desde el host Linux. La primera configuración crea una cuenta administrativa y muestra una contraseña temporal en el terminal o los logs. Inicia sesión, cambia esa contraseña en Ajustes y prueba una nueva sesión del navegador antes de habilitar acceso remoto.

Después añade un único endpoint conocido y envía un mensaje breve. Si la interfaz funciona pero falla la respuesta, la instalación probablemente está correcta. Revisa URL, credenciales, nombre del modelo, firewall y runtime en vez de reinstalar todo.

1. Abrir la página local

   Confirma que aparece el acceso en localhost:7000 sin bucles.

2. Leer la contraseña generada

   Consúltala en terminal o logs; no adivines una contraseña predeterminada.

3. Cambiar la credencial

   Hazlo antes de LAN, VPN o proxy.

4. Probar un modelo

   Empieza con un endpoint conocido y una solicitud corta.

La GPU pertenece a la decisión del runtime del modelo

El workspace consume relativamente pocos recursos; la GPU se necesita sobre todo para inferencia local. Una instalación nativa puede usar Ollama del host. La aplicación en Docker también puede conectarse a un endpoint del host o remoto sin montar el socket de Docker.

Para NVIDIA o AMD en contenedores, comprueba primero controladores y passthrough. Los scripts y overlays oficiales ayudan al diagnóstico. Que nvidia-smi funcione dentro del contenedor confirma acceso al dispositivo, pero no que la compilación de llama.cpp, vLLM o SGLang tenga las bibliotecas CUDA o ROCm adecuadas.

scripts/check-docker-gpu.sh

http://host.docker.internal:11434/v1

Conectar Odysseus a Tailscale en Linux de forma segura

Similarweb encontró connect odysseus to tailscale linux como consulta de apoyo de baja dificultad. Debe resolverse dentro de esta guía porque el acceso remoto empieza después de una instalación local correcta; no justifica una página independiente y delgada.

Vincula la aplicación de forma deliberada a 0.0.0.0 o a la interfaz adecuada, conserva la autenticación, limita dispositivos mediante políticas de Tailscale o firewall y usa HTTPS cuando el navegador exija un origen seguro. No reenvíes el puerto de Odysseus ni el del modelo directamente a Internet.

python -m uvicorn app:app --host 0.0.0.0 --port 7000

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Actualizar Linux sin inventar una versión de lanzamiento

A 30 de julio de 2026 no había Releases ni etiquetas oficiales. dev cambia con rapidez y main es más curada. Por eso no se afirma una versión más reciente, tamaño de archivo, instalador binario o enlace directo permanente.

Antes de actualizar, registra la rama, guarda datos y .env, revisa cambios y actualiza la misma rama. No cambies de main a dev durante un mantenimiento no relacionado. Reconstruye contenedores o dependencias y repite las pruebas de login, modelo y red.

git status --short
git branch --show-current
git pull --ff-only
# Docker
docker compose up -d --build

Tabla de solución de problemas en Linux

Aísla las capas en este orden: proceso, puerto, login, endpoint del modelo y servicios opcionales. Cambiar varias a la vez oculta la causa.