Odysseus: despliegue práctico en 30 minutos para montar un escritorio de IA autoalojado

Resumen en una frase: ¿Quieres «escaparte» de ChatGPT/Claude en la web y montar todo el escritorio de IA en tu propio equipo? Este artículo te guía paso a paso con Odysseus, una alternativa autoalojada a ChatGPT con enfoque local y máxima prioridad a la privacidad.

Presentación del proyecto

Odysseus es un entorno de trabajo de IA autoalojado (Self-hosted AI Workspace), desarrollado y publicado en código abierto por el usuario de GitHub pewdiepie-archdaemon bajo licencia MIT. Su objetivo es este: darte la experiencia de la interfaz de ChatGPT/Claude en tu propio equipo, pero manteniendo todos los datos, todas las conversaciones y todas las llamadas a herramientas en local.

Comparado con las apps clásicas de ChatGPT, las diferencias son claras:

• Chat: delega a cualquier modelo local o remoto (vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot)
• Agentes (Agent): un agente realmente capaz de «ponerse manos a la obra», con MCP / Web / Archivos / Shell / Skills / Memoria (basado en opencode)
• Cookbook: escaneo automático del hardware de tu máquina, recomendación de modelos que sí pueden ejecutarse, y descarga + arranque de un clic (basado en llmfit, VRAM-aware)
• Deep Research: investigación en varios pasos, captura + lectura + síntesis, y genera informes con visualización (adaptado de Tongyi DeepResearch)
• Compare: comparación a ciegas con varios modelos, eligiendo sin sesgos el que realmente funciona mejor
• Documents: tú escribes texto y la IA te ayuda al lado, no al revés
• Memory / Skills: memoria a largo plazo + sistema de habilidades; cuanto más usa el agente, más te entiende (ChromaDB + fastembed ONNX)
• Email: bandeja IMAP/SMTP; la IA clasifica automáticamente, resume, redacta respuestas y filtra spam
• Notes & Tasks / Calendar: notas + tareas + calendario; sincroniza CalDAV con Radicale / Nextcloud / Apple / Fastmail
• Soporte PWA: la experiencia en el móvil no tiene nada que envidiar al escritorio; incluso puedes añadirlo a la pantalla de inicio

En una frase: no es solo una caja de chat; es todo tu entorno de IA, completamente en tu máquina, sin subir nada a la nube.

Dificultad / Duración / Lo que ganas

• Dificultad: ⭐⭐⭐ (media; necesitas saber lo básico de Docker y Python)
• Duración: 30–45 minutos (ruta con Docker); 1 hora (instalación nativa + conectar un modelo local)
• Lo que ganas:
  • Montar y poner en marcha un escritorio autoalojado de IA con funciones completas
  • Entender la arquitectura típica de las apps de IA con prioridad local (FastAPI + ChromaDB + SearXNG + ntfy)
  • Conectar APIs compatibles con Ollama / vLLM / OpenAI dentro de una misma interfaz
  • Descubrir habilidades «de cola larga» pero muy potentes del Cookbook: selección automática de modelo, passthrough de GPU y el sistema de memoria

Perfil de lectores objetivo

• No quieres seguir pagando suscripciones de ChatGPT Plus / Claude Pro y quieres mantener los datos de IA en local
• Tienes una NUC / workstation / servidor con 8G / 16G / 24G de VRAM y quieres ejecutar modelos open source con una interfaz unificada
• Desarrolladores full-stack o independientes que quieren unificar chat / correo / calendario / tareas de Agent en un solo panel
• Operadores / ingenieros de plataformas interesados en «autoalojar» y que quieran un ejemplo tipo de app FastAPI a nivel productivo
• Ya pagaste por LLMs en la nube y buscas alguna forma de hacerlo sin que duela tanto

Si solo buscas una interfaz ligera de chat, Odysseus quizá no sea para ti: tiene muchas funciones y es un poco más complejo empezar que con Open WebUI, pero lo que ganas es todo el paquete: correo, memoria, Cookbook y Agent.

Dependencias clave y entorno

Requisitos mínimos:

Dependencias opcionales / mejorables:

Estructura completa del proyecto

odysseus/
├── app.py                    # Entrada FastAPI
├── setup.py                  # Script de inicialización (crear admin / base de datos / directorios)
├── requirements.txt          # Dependencias Python principales
├── requirements-optional.txt # Dependencias opcionales (PDF/Office/voz/STT)
├── docker-compose.yml        # Orquestación por defecto (CPU)
├── docker-compose.gpu-nvidia.yml  # Sobrescritura NVIDIA GPU
├── docker-compose.gpu-amd.yml     # Sobrescritura AMD ROCm
├── Dockerfile
├── core/                     # Capa de infraestructura
│   ├── auth.py               # Autenticación / sesiones
│   ├── database.py           # Inicialización SQLAlchemy
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # Capa de lógica de negocio
│   ├── llm_core.py           # Abstracción del modelo
│   ├── agent_loop.py         # Bucle del Agent
│   ├── agent_tools.py        # Conjunto de herramientas del Agent
│   ├── chat_processor.py     # Procesamiento de chat
│   ├── cookbook_serve_lifecycle.py  # Ciclo de vida del servicio del modelo del Cookbook
│   ├── memory_vector.py      # Memoria a largo plazo en ChromaDB
│   ├── deep_research.py      # Deep Research
│   └── ...
├── routes/                   # Rutas de FastAPI (40+ módulos)
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # Recomendación/descarga de modelos
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # Servicios en segundo plano
│   ├── docs/                 # Procesamiento documental
│   ├── hwfit/                # Escaneo de hardware (Cookbook)
│   ├── memory/               # Servicio de memoria
│   ├── research/             # Servicio de investigación
│   ├── search/               # Búsqueda
│   ├── stt/ tts/             # Texto a voz / Voz a texto
│   └── shell/                # Herramientas de Shell
├── static/                   # Frontend (index.html + JS/CSS)
├── docs/                     # Sitio de documentación + capturas + demo
├── config/                   # Configuración de subservicios como SearXNG
├── companion/                # Acompañante de escritorio (macOS)
└── data/                     # Datos de usuarios (gitignored, generados en runtime)
    ├── app.db                # SQLite
    ├── chroma/               # Base vectorial
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # Caché de modelos

En el directorio, solo necesitas preocuparte por estos tres archivos: app.py / docker-compose.yml / .env. El resto lo gestiona Docker.

Paso a paso

Paso 1: Clonar el repositorio

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

Paso 2: Preparar .env (opcional, pero recomendado)

cp .env.example .env

El .env mínimo que funciona así:

# === Puntos de conexión LLM ===
LLM_HOST=localhost
# Si quieres usar APIs de la nube, accede desde el contenedor vía host.docker.internal (Ollama local)
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === Puertos y binding ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === Seguridad (clave) ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # Cambia a true solo si usas un reverse proxy con HTTPS
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # Si no lo escribes, se generará aleatoriamente al primer arranque y se imprimirá

# === Búsqueda (SearXNG) ===
SEARXNG_INSTANCE=http://searxng:8080

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Paso 3: Arranque en un clic con Docker (ruta recomendada)

docker compose up -d --build

Durante la construcción se descargan las imágenes base e instalan las dependencias de Python. La primera vez tarda aproximadamente 3–5 minutos. Cuando los cuatro contenedores (odysseus, chromadb, searxng, ntfy) estén en estado healthy / running, ya está:

docker compose ps

Abre http://localhost:7000: la primera pantalla es la de login. La contraseña inicial de admin aparece en el log del terminal:

docker compose logs --tail=200 odysseus | grep -i "temporary\|admin\|password"

Deberías ver algo parecido a:

[odysseus] Created admin user 'admin' with temporary password: aB3x-9pQz-2vRt

Paso 4: Verificar que todos los servicios estén saludables

# 1. Estado de los contenedores
docker compose ps

# 2. Logs de Odysseus (ojo: en el primer arranque puede haber retraso al descargar modelos)
docker compose logs --tail=120 odysseus

# 3. Comprobar que ChromaDB esté realmente arriba (no una degradación a HTTP)
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

Si ves DEGRADED, casi seguro es un conflicto entre chromadb-client y chromadb. El método de diagnóstico está más adelante en «Preguntas frecuentes».

Paso 5: Conectar tu primer modelo

Entra en Settings → Models / Providers y elige una ruta según tu equipo:

Ruta A: Ya tienes Ollama ejecutándose (lo más simple)

Base URL:  http://host.docker.internal:11434/v1
API Key:   (dejar vacío)
Model:     qwen2.5:7b (o cualquier modelo que tengas en local)

Ruta B: Usar Cookbook para descargar e iniciar automáticamente

Entra en Cookbook: escanea tu VRAM, recomienda modelos open source ejecutables y te da una puntuación (fit score). Pulsa «Download» para que ejecute huggingface-cli y descargue el modelo en ./data/huggingface/; luego se sirve directamente con llama.cpp / vLLM.

Ruta C: Conectar APIs de la nube — esto es lo que quiero comentar hoy

La configuración de Provider en Odysseus es impulsada por el protocolo: cualquier servicio que responda correctamente a los dos endpoints v1/chat/completions o v1/messages puede conectarse directamente rellenando el Base URL. No solo cuenta con OpenAI y Anthropic oficiales: también gateways propios o intermediarios de terceros funcionan igual.

En mi despliegue, la parte de «Agent diario para ejecutar código / documentos largos» la hago con APIs de la nube por dos razones:

1. En local, con una GPU de 24G, ejecutar cuantizaciones de 70B ya es duro; al abrir Agent con múltiples turnos es frecuente terminar en OOM
2. Modelos punteros como Claude/GPT siguen siendo una liga por encima de Qwen2.5-Coder en razonamiento complejo

Pero llega el problema: — las APIs oficiales son demasiado caras. Claude Opus se puede comer fácilmente más de 100 dólares en una semana; para uso personal es como trabajar para Anyscale.

Mi solución actual es conectar Defapi usando el endpoint compatible con v1/messages:

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # Obtener en el panel de defapi.org
Model:     anthropic/claude-sonnet-4.5 # o haiku-4.5 / opus-4.6

Ejemplos de configuración: Defapi Claude Sonnet 4.5 (fuerza en programación/documentos largos), Claude Haiku 4.5 (preferido para Agent en el día a día, porque es más barato).

En pruebas reales, para la misma cantidad de conversación/tareas al mes, la factura con Defapi baja por bastante frente a conectar Anthropic oficial. Y la capacidad del modelo, el uso de herramientas del Agent y el formato de prompts no cambian en absoluto — porque se trata de un proxy a nivel de protocolo: el modelo sigue siendo el mismo. Esto encaja de forma natural con un diseño «impulsado por protocolo» como el de Odysseus.

Ruta D: Conectar GitHub Copilot / OpenRouter, etc.

También son compatibles con el protocolo de OpenAI: basta con poner como Base URL https://api.githubcopilot.com / https://openrouter.ai/api/v1 respectivamente. No lo detallo más.

Paso 6: Primer chat + primera tarea del Agent

Vuelve a la interfaz principal, elige un modelo y lanza un prompt sencillo para comprobar la conectividad:

Preséntate en tres frases y luego dame una lista de verificación de diagnóstico de rendimiento para Linux que pueda usar hoy.

Si funciona, significa que el canal del LLM está bien.

Ahora prueba modo Agent: crea una nueva sesión, cambia a «Agent» e introduce:

Enumera cuántas líneas tiene cada archivo .py en el directorio actual y dime qué archivo vale más la pena refactorizar.

El Agent planeará por su cuenta:

1. Llama a la herramienta shell para ejecutar find . -name "*.py" | xargs wc -l
2. Interpreta los resultados
3. Da recomendaciones

Esta es la diferencia fundamental entre el Agent con prioridad local y el chat de la web de ChatGPT: realmente puede «hacer cosas»; tus códigos, archivos y terminal, tienen permiso para ser accedidos.

Paso 7 (opcional): Habilitar GPU

Este paso solo es necesario si vas a usar inferencia local «pesada» como vLLM / SGLang / llama.cpp CUDA. Si solo usas Ollama o APIs de la nube, puedes saltarlo.

NVIDIA:

# Diagnóstico en un clic
scripts/check-docker-gpu.sh

# Instalar NVIDIA Container Toolkit (Ubuntu/Debian; requiere sudo)
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# Habilitar overlay solo después de confirmar passthrough exitoso
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# Verificar
docker compose exec odysseus nvidia-smi -L

Lo añade en .env:

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

AMD ROCm:

scripts/check-docker-amd-gpu.sh
# Escribe el RENDER_GID de la salida en .env

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

Paso 8 (opcional): Habilitar Playwright MCP (proxy del navegador)

Odysseus trae algunos servidores MCP, pero el del navegador requiere primero descargarlo con npx:

npx -y @playwright/mcp@latest --version

Reinicia el contenedor de Odysseus y en Agent ya podrás usar el navegador MCP (capturas, navegación, rellenado de formularios):

Abre https://news.ycombinator.com, captura los primeros 10 títulos y enlaces y resúmelos en 5 temas clave.

Paso 9 (opcional): Ejecutar de forma nativa en Windows

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

El script crea automáticamente venv → instala dependencias → ejecuta setup → inicia con uvicorn. Abre http://localhost:7000.

Paso 10 (opcional): Que también lo puedas usar desde el móvil

Asumiendo que ya tienes Tailscale conectado:

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# o escribir en .env
APP_BIND=0.0.0.0

Pero exponer HTTP directo en LAN/Tailscale no es seguro; se recomienda encarecidamente añadir HTTPS con mkcert:

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem 100.x.y.z   # tu IP de Tailscale

python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

En el móvil entra a https://<tailscale-ip>:7000. Si instalas la PWA en la pantalla de inicio, la experiencia es casi igual a la de una app nativa.

Resolución de problemas frecuentes

Q1: El puerto 7000 está ocupado (común en macOS)

macOS AirPlay suele ocupar 7000. Dos soluciones:

# Método 1: cambiar el puerto en .env
APP_PORT=7001
docker compose up -d
# En el navegador abre http://localhost:7001

# Método 2: Menú Apple → Configuración del sistema → General → Receptor de AirPlay → desactivar

Q2: ChromaDB arranca pero en logs aparece DEGRADED

Normalmente es que chromadb-client y chromadb están instalados a la vez; se cae en modo HTTP-only en silencio y se pierde la capacidad vectorial. Solución:

# En el contenedor en ejecución (o en tu venv local)
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

Verifica la reparación: docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore"; debería mostrarse inicialización correcta y ya no aparecer DEGRADED.

Q3: Cookbook no ve mi GPU; solo veo iGPU o CPU

Por defecto, Docker expone todas las GPU al host, pero si solo cuelgas iGPU o alguna otra tarjeta, casi siempre es porque no está instalado el NVIDIA Container Toolkit o falta configuración de runtime: nvidia-ctk runtime configure --runtime=docker:

# Diagnóstico
scripts/check-docker-gpu.sh
# Mira la salida: te dirá qué paso falta

# Instalar y configurar en un clic (Ubuntu/Debian)
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4: El passthrough de GPU funciona, pero llama.cpp dice Unable to find cudart en los logs

El problema no es el dispositivo; lo que falta es el runtime de CUDA. Esa capa no la resuelve Docker. Ve a Cookbook → Dependencies y reinstala la build CUDA de llama-cpp-python:

Abre Cookbook → Dependencies → encuentra llama-cpp-python → Reinstall (build CUDA)

Se hará solo con pip install --no-cache-dir llama-cpp-python[cuda], tarda unos 2–3 minutos.

Q5: No se puede conectar el correo Outlook / Office 365

El módulo de correo de Odysseus ahora solo soporta autenticación IMAP + contraseña de usuario. Microsoft, después de 2024, prácticamente ha bloqueado el inicio de sesión con contraseñas normales y exige OAuth. Esta limitación es conocida.

Solución temporal: usa Gmail/Fastmail o un correo autoalojado, o crea un Microsoft App Password (para cuentas con 2FA) para simular el login con contraseña.

Q6: Quiero acceso público; ¿cómo hacerlo de forma segura?

Exponer directamente APP_BIND=0.0.0.0 al público = desastre. LOCALHOST_BYPASS evita la autenticación y además Agent incluye herramientas de shell: en Shodan, en 24 horas ya se escanean un montón de instancias expuestas.

Forma correcta:

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik (termina HTTPS)
            → http://127.0.0.1:7000 (Odysseus, mantener binding a localhost)

Y en .env:

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7: ¿Cómo controlar la factura de APIs en la nube?

Vamos a detallar el problema de la ruta del paso 5, el apartado C.

En la práctica, al usarlo de forma personal, estas tres ideas se ordenan de mayor a menor coste:

1. Conectar APIs oficiales — la experiencia más completa, pero la factura es la más cara. Claude Opus + llamadas frecuentes de Agent: es normal romper más de 100 dólares en una semana
2. Conectar una capa de intermediación compatible con el protocolo (uso Defapi) — los mismos modelos de Claude/GPT/Gemini; la factura mensual baja bastante frente a la oficial (no he calculado exactamente cuánto, pero la escala pasa de factura semanal ~100 a factura mensual ~100). La ventaja es que la compatibilidad a nivel de protocolo es total: en Odysseus mantienes la configuración, no necesitas cambiar prompts ni código del Agent
3. Modelos cuantizados en local — en Cookbook descargas un GGUF tipo Q4_K_M; con 16G de VRAM puedes ejecutar modelos de nivel 30B, coste de API es cero, pero la inferencia es más lenta que en la nube y la calidad en tareas complejas queda un escalón por debajo

Mi combinación real: chat + Deep Research con Defapi Claude Sonnet 4.5, Agent con llamadas a herramientas con Claude Haiku 4.5 (barato), y tareas simples de clasificación/resumen con una versión cuantizada de Qwen2.5 en local. Cada Provider cobra por separado, no se interfieren. En un mes, la factura queda en cifras de dos dígitos en RMB.

Lecturas complementarias / direcciones avanzadas

• Ecosistema MCP: los MCP integrados que registra Odysseus incluyen playwright (navegador) / filesystem / shell. Puedes escribir tu propio servidor MCP, registrarlo en mcp_servers/ y así el Agent podrá usarlo
• Sistema de Skills: routes/skills_routes.py administra «fragmentos de skills» reutilizables, similar a la clase Skills de OpenClaw. Escribes una vez y cualquier sesión puede llamarlos
• Tailscale + HTTPS con mkcert: en el apartado anterior ya se mostró el flujo base; para avanzar puedes añadir renovación automática + desafío DNS-01
• Combinación de reverse proxy: configuración de Caddy con HTTPS + proxy de Cloudflare; se puede lograr acceso público sin mantenimiento
• Sincronización CalDAV: autoalojas Radicale (un servicio CalDAV ligero) y el calendario de Odysseus sincroniza bidireccionalmente con el calendario del sistema del móvil
• AI para clasificar emails: al conectar IMAP, después de entrenar un tiempo, clasifica automáticamente en «urgente / normal / spam»; los borradores se redactan de antemano y tú solo tienes que pulsar enviar
• Cookbook en servidor remoto: Cookbook → Settings → Servers permite configurar una máquina remota con GPU; la inferencia y la descarga del modelo se hacen por SSH: el host es pequeño, la GPU está lejos y queda muy bien montado
• Deep Research con informes en varios pasos: adaptado del Tongyi DeepResearch de Alibaba; usa SearXNG para capturar múltiples fuentes → resumir → sintetizar. Ideal para investigación de competidores/estudio del sector
• Enrutado con múltiples Providers: en Odysseus, asigna distintos Providers para chat/Agent/Research. En general, usa Ollama local para el 80% de las conversaciones del día a día y deja los problemas complejos para la nube; así equilibras coste y experiencia

Repositorio de GitHub: pewdiepie-archdaemon/odysseus. Documentación en el directorio docs/, el roadmap en ROADMAP.md, y para contribuir mira CONTRIBUTING.md.