Instalar Odysseus AI en un servidor VPS Linux
En esta guía vamos a instalar Odysseus AI en un servidor VPS Linux con Docker Compose y después lo publicaremos correctamente detrás de un reverse proxy HTTPS. El objetivo es obtener un workspace IA privado, autoalojado, capaz de centralizar chat, agentes, documentos, memoria, búsqueda web, notas, tareas, calendario, correo y herramientas locales.
Odysseus es un proyecto open source presentado como un workspace IA self-hosted, local-first y privacy-first. Puede hablar con modelos locales o APIs compatibles, usar herramientas de agente, apoyarse en ChromaDB para la memoria, lanzar SearXNG para la búsqueda web y conectarse a Ollama, vLLM, llama.cpp, OpenRouter, OpenAI u otros endpoints. Si has seguido nuestra guía para instalar Hermes Agent, puedes ver Odysseus como un enfoque más orientado a interfaz web y workspace completo, mientras que Hermes se acerca más a un agente autónomo accesible desde terminal o mensajería.
Odysseus todavía es joven. El repositorio oficial indica que la rama dev contiene los cambios más recientes, pero puede ser inestable, mientras que main es la rama más estable y curada. Para un VPS que quieres mantener limpio, instalaremos main por defecto.
1. Qué tendrás al final
Al terminar este tutorial, tendrás:
- Una instancia Odysseus funcionando con Docker Compose.
- Una interfaz web protegida con autenticación.
- ChromaDB, SearXNG y ntfy arrancados con la stack oficial.
- Acceso HTTPS mediante NGINX, sin exponer directamente los puertos internos.
- Una base lista para conectar Ollama, una API compatible con OpenAI o un servidor remoto de modelos.
- Comandos de backup, actualización, diagnóstico y hardening.
Odysseus escucha por defecto en el puerto de aplicación 7000. La stack Docker también expone servicios internos como SearXNG, ChromaDB y ntfy. Lo importante es no abrir todos esos puertos al público: la interfaz Odysseus debe ser el único punto de entrada para el usuario, idealmente detrás de HTTPS.
2. Requisitos recomendados
Antes de empezar, prepara:
- Un servidor VPS Linux con acceso SSH y permisos sudo.
- Ubuntu 22.04, Ubuntu 24.04 o Debian 12 para seguir los comandos tal como están escritos.
- Al menos 2 GB de RAM para probar la interfaz con modelos mediante API.
- Preferiblemente 4 GB a 8 GB de RAM si también quieres búsqueda, documentos y algunos tratamientos locales.
- Más RAM y eventualmente GPU si quieres servir modelos locales reales en el mismo VPS.
- Un dominio o subdominio, por ejemplo
odysseus.example.com, si quieres un acceso HTTPS limpio.
Si usas un VPS pequeño sin GPU, no pasa nada. Odysseus puede funcionar muy bien como interfaz privada conectada a un proveedor externo o a un servidor remoto de modelos. La GPU empieza a ser útil sobre todo si quieres descargar y servir modelos localmente con Cookbook, llama.cpp, vLLM o un runtime similar.
Actualiza primero el sistema:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ca-certificates gnupg openssl ufw
3. Instalar Docker en el VPS
Odysseus recomienda Docker para la instalación en servidor. Si Docker ya se usa en producción en tu VPS, revisa el impacto antes de reemplazar paquetes existentes. En una máquina nueva, usa esta secuencia.
sudo apt remove -y $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null | cut -f1)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker
Comprueba que Docker y Docker Compose están disponibles:
docker --version
docker compose version
Si necesitas más detalles sobre Docker, puedes leer nuestra guía dedicada: Instalar Docker en Linux, guía práctica para empezar.
4. Descargar los archivos de despliegue de Odysseus
La instalación oficial de Odysseus se basa en el repositorio Git del proyecto. Este repositorio contiene el docker-compose.yml completo, la configuración de SearXNG, los scripts GPU y los archivos necesarios para arrancar los servicios usados por Odysseus.
Instala estos archivos en /opt/odysseus y devuelve la propiedad del directorio a tu usuario actual para no gestionarlo todo como root.
sudo apt update
sudo apt install -y git openssl
cd /opt
sudo git clone --branch main https://github.com/pewdiepie-archdaemon/odysseus.git
sudo chown -R "$USER:$USER" /opt/odysseus
cd /opt/odysseus
Para este tutorial VPS, quédate en main. También existe el tag dev, pero sigue la rama de desarrollo y puede cambiar más rápido.
5. Preparar el archivo .env
Copia el archivo de ejemplo:
cp .env.example .env
Después añade una configuración explícita para un primer despliegue detrás de reverse proxy. El puerto de Odysseus seguirá vinculado a 127.0.0.1, así que no quedará expuesto directamente a Internet.
ADMIN_PASSWORD=$(openssl rand -hex 24)
SECRET_KEY=$(openssl rand -hex 32)
cat <<EOF >> .env
APP_BIND=127.0.0.1
APP_PORT=7000
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false
ODYSSEUS_ADMIN_USER=admin
ODYSSEUS_ADMIN_PASSWORD=$ADMIN_PASSWORD
SECRET_KEY=$SECRET_KEY
ALLOWED_ORIGINS=http://localhost:7000,http://127.0.0.1:7000
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache
EOF
printf 'Contraseña admin inicial: %s\n' "$ADMIN_PASSWORD"
Guarda la contraseña mostrada en un gestor de contraseñas. Podrás cambiarla después desde la interfaz de Odysseus.
Puntos importantes:
AUTH_ENABLED=truemantiene la página protegida por login.LOCALHOST_BYPASS=falseevita un bypass pensado solo para desarrollo local.APP_BIND=127.0.0.1impide exponer directamente el puerto de la aplicación en la red pública.SECURE_COOKIES=falsees temporal hasta activar HTTPS.FASTEMBED_CACHE_PATH=/app/data/fastembed_cachemantiene la caché FastEmbed en el volumen persistentedata/. Sin este path explícito, Odysseus puede mostrar erroresNo embedding lanes availableal inicializar la memoria, el RAG y el índice de herramientas.
6. Arrancar Odysseus con Docker Compose
Arranca la stack oficial. En el primer arranque, Docker construye la imagen de Odysseus desde las fuentes y también lanza ChromaDB, SearXNG y ntfy.
docker compose up -d --build
Esta primera ejecución puede tardar varios minutos, sobre todo en un VPS pequeño. Los arranques siguientes serán más rápidos porque Docker reutiliza las capas ya construidas.
Comprueba el estado de los contenedores:
docker compose ps
Consulta los logs de la aplicación:
docker compose logs --tail=120 odysseus
Si no has definido ODYSSEUS_ADMIN_PASSWORD, Odysseus genera una contraseña temporal en el primer arranque. Puedes encontrarla con:
docker compose logs odysseus | grep -Ei 'password|admin'
En este punto, la interfaz debería responder localmente desde el VPS:
curl -I http://127.0.0.1:7000
También puedes probar con un túnel SSH desde tu ordenador:
ssh -L 7000:127.0.0.1:7000 usuario@direccion-del-vps
Después abre http://localhost:7000 en tu navegador local. Es una forma práctica de probar sin exponer la aplicación.
Cuando el servicio está arrancado, la página de login aparece con el usuario admin creado durante el primer arranque.
7. Poner Odysseus detrás de NGINX y HTTPS
Para un acceso web limpio, usa un subdominio y un reverse proxy. En los ejemplos, sustituye odysseus.example.com por tu dominio real. Antes de lanzar Certbot, asegúrate de que el DNS del subdominio ya apunta a la IP del VPS y de que el puerto 80 es accesible desde Internet.
Instala NGINX y Certbot:
sudo apt install -y nginx certbot python3-certbot-nginx
Crea la configuración NGINX:
sudo tee /etc/nginx/sites-available/odysseus.conf > /dev/null <<'EOF'
server {
listen 80;
server_name odysseus.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:7000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600;
proxy_send_timeout 3600;
}
}
EOF
Activa el sitio, verifica la sintaxis y recarga NGINX:
sudo ln -s /etc/nginx/sites-available/odysseus.conf /etc/nginx/sites-enabled/odysseus.conf
sudo nginx -t
sudo systemctl reload nginx
Genera el certificado HTTPS:
sudo certbot --nginx -d odysseus.example.com
Cuando HTTPS esté activo, actualiza .env para activar cookies seguras y permitir el origen público:
cd /opt/odysseus
sed -i '/^SECURE_COOKIES=/d;/^ALLOWED_ORIGINS=/d' .env
cat <<'EOF' >> .env
SECURE_COOKIES=true
ALLOWED_ORIGINS=https://odysseus.example.com,http://localhost:7000,http://127.0.0.1:7000
EOF
docker compose up -d
Abre https://odysseus.example.com e inicia sesión con el usuario admin y la contraseña generada antes.
8. Configurar el firewall del VPS
Antes de activar o modificar UFW, comprueba siempre su estado para evitar perder el acceso SSH:
sudo ufw status
Autoriza SSH para mantener el acceso administrativo y después abre el tráfico web:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
La regla OpenSSH sirve únicamente para conservar tu acceso SSH de administración o para mantener el túnel SSH utilizado para pruebas en este tutorial, y no es necesaria para el funcionamiento de Odysseus.
Si UFW todavía no está activo, actívalo solo después de añadir la regla SSH:
sudo ufw enable
sudo ufw status verbose
Si tu sistema no utiliza UFW, puedes configurar el equivalente mínimo con iptables. Esta regla SSH también sirve para conservar tu acceso de administración o el túnel de este tutorial (ten en cuenta que debes adaptar el puerto por defecto 22 si tu servicio SSH escucha en otro puerto):
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
No publiques directamente en Internet puertos internos como 7000, 8080, 8091, 8100, 11434 o 8000-8020. Déjalos en localhost, dentro de Docker, detrás de un VPN, con Tailscale o detrás de un reverse proxy controlado.
9. Primer recorrido por la interfaz Odysseus
Después de iniciar sesión, llegas a la pantalla de chat. En este punto la instalación está arrancada, pero Odysseus todavía no podrá responder hasta que configures al menos un proveedor de modelo.
Revisa tres ajustes antes de lanzar un agente:
- Cambia la contraseña admin si has usado una temporal.
- Comprueba que el registro abierto está desactivado si la instancia no está pensada para varios usuarios.
- Añade tu primer proveedor de modelo desde los ajustes.
La pantalla de bienvenida puede sugerir escribir /setup, pero según la versión instalada la orden sola puede responder Unknown subcommand. El atajo útil es empezar por la ayuda o por el asistente de endpoints:
/setup --help
/setup endpoint
También puedes ir directamente a Settings > Add Models. Es el método más claro para un primer despliegue, porque separa modelos locales, APIs externas y pruebas de conexión.
Odysseus puede funcionar de varias formas:
- Con una API compatible con OpenAI, OpenRouter, DeepSeek, Anthropic, Groq, Gemini o un proveedor equivalente para empezar rápido.
- Con Ollama en el mismo VPS o en otra máquina privada.
- Con un endpoint vLLM, llama.cpp u otro servidor compatible con OpenAI.
- Con Cookbook para detectar el hardware, descargar modelos y preparar un runtime adaptado.
Si configuras un servidor de modelo local desde Docker, recuerda que localhost visto desde el contenedor no es necesariamente el host VPS. Para Ollama instalado en el mismo VPS, usa http://host.docker.internal:11434/v1, como se explica en la sección siguiente.
Los demás módulos ya se abren en una instancia recién instalada. Library almacena documentos, resultados de investigación y conversaciones archivadas.
Brain agrupa la memoria a largo plazo y los skills. Empieza a ser realmente útil cuando hay un modelo y un backend de embeddings funcionales.
Deep Research prepara búsquedas web multi-etapa, con elección del motor de búsqueda, número de rondas, endpoint y modelo.
Odysseus también incluye Compare, un panel para enviar el mismo prompt a varios modelos y comparar las respuestas, incluso en modo blind test cuando hay varios modelos disponibles.
La zona Calendar ofrece un calendario local-first con vistas semana, mes, año y agenda. La sincronización CalDAV se configura después desde los ajustes de integración.
El módulo Tasks lista tareas programadas y automatizaciones internas: sesiones, email, memoria, documentos, investigaciones y skills. También permite ver qué jobs están activos o en pausa.
El módulo Email también forma parte de las funcionalidades destacadas, pero necesita una configuración IMAP/SMTP en Settings > Integrations antes de ser útil. En una instancia nueva, es normal no ver correos hasta conectar una cuenta.
Para un VPS pequeño, empieza con un proveedor externo o un servidor remoto de modelos. En una máquina más potente fuera de un VPS BoxToPlay con GPU, podrás probar después la descarga y ejecución de modelos locales.
10. Conectar Ollama a Odysseus
Si Ollama se ejecuta en el mismo VPS que Docker, Odysseus debe poder alcanzarlo desde el contenedor. El repositorio recomienda esta URL en Odysseus:
http://host.docker.internal:11434/v1
Ollama debe escuchar más allá de su propio loopback. En un servidor systemd, crea un override:
sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama
No abras el puerto 11434 en el firewall público. El objetivo es únicamente que el contenedor Odysseus pueda contactar Ollama mediante la ruta local host/Docker.
También puedes preconfigurar la URL en .env:
cd /opt/odysseus
sed -i '/^OLLAMA_BASE_URL=/d' .env
cat <<'EOF' >> .env
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
EOF
docker compose up -d
Después añade o verifica el proveedor correspondiente en los ajustes de modelos de Odysseus.
11. Activar opciones GPU si tu VPS lo permite
En un VPS BoxToPlay, puedes saltarte esta parte: nuestras ofertas VPS actuales no se venden con GPU. Las opciones siguientes no funcionarán en un VPS BoxToPlay estándar. Solo aplican a un servidor Linux que tenga realmente una GPU NVIDIA o AMD, con passthrough Docker compatible.
En un servidor Linux solo CPU, Cookbook puede detectar de todos modos la RAM, los núcleos CPU y sugerir modelos llama.cpp compatibles o marginales. Es útil para estimar qué puede ejecutarse localmente antes de descargar nada.
Para NVIDIA, empieza con un diagnóstico sin cambios:
cd /opt/odysseus
scripts/check-docker-gpu.sh
Para mostrar los comandos de instalación necesarios sin ejecutarlos:
scripts/check-docker-gpu.sh --print-install-commands
Para instalar el runtime NVIDIA y activar el overlay después de validar el passthrough:
sudo scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
docker compose up -d --build
Para AMD/ROCm, lanza el diagnóstico:
cd /opt/odysseus
scripts/check-docker-amd-gpu.sh
Después añade el overlay y el GID del grupo render a .env si el diagnóstico lo pide:
RENDER_GID=$(getent group render | cut -d: -f3)
sed -i '/^COMPOSE_FILE=/d;/^RENDER_GID=/d' .env
cat <<EOF >> .env
COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=$RENDER_GID
EOF
docker compose up -d --build
Un punto importante: ver la GPU dentro del contenedor no garantiza que llama.cpp o vLLM ya usen CUDA o ROCm. El passthrough Docker y las dependencias del runtime de modelos son dos temas distintos.
12. Hacer backup de Odysseus correctamente
Los datos importantes están en data/, .env y, según tu uso, logs/. Antes de una actualización o cambio importante, crea un archivo comprimido.
cd /opt/odysseus
tar --exclude='data/huggingface' --exclude='data/local' -czf "$HOME/odysseus-backup-$(date +%F).tar.gz" .env data logs
Los directorios data/huggingface y data/local pueden crecer mucho si descargas modelos o instalas motores locales. Hazles backup aparte si también quieres restaurar modelos y dependencias pesadas.
Para enviar el archivo a otro servidor:
scp "$HOME/odysseus-backup-$(date +%F).tar.gz" [email protected]:/home/usuario/backups/
Nunca compartas públicamente .env, data/, logs, exports, uploads o capturas que contengan claves API.
13. Actualizar Odysseus
Haz un backup antes de actualizar. Con la instalación oficial desde el repositorio Git, descarga los últimos archivos y reconstruye la stack:
cd /opt/odysseus
git checkout main
git pull --ff-only
docker compose up -d --build
docker compose logs --tail=120 odysseus
Luego revisa la interfaz y los providers configurados. Si usas dev, espera cambios más frecuentes y conserva una copia reciente antes de cada actualización.
14. Diagnóstico de problemas frecuentes
Si la interfaz no responde, revisa primero los contenedores:
cd /opt/odysseus
docker compose ps
docker compose logs --tail=120 odysseus
Si el puerto 7000 ya está ocupado, elige otro puerto local:
cd /opt/odysseus
sed -i '/^APP_PORT=/d' .env
cat <<'EOF' >> .env
APP_PORT=7001
EOF
docker compose up -d
Después cambia el proxy_pass de NGINX a http://127.0.0.1:7001.
Si SearXNG bloquea el arranque o queda en error:
docker compose logs --tail=120 searxng
docker compose restart searxng odysseus
Si ChromaDB parece no estar disponible:
docker compose logs --tail=120 chromadb
docker compose restart chromadb odysseus
Si los logs de Odysseus muestran FastEmbed init failed, No such file or directory: '' o No embedding lanes available, comprueba que .env contiene el path de caché FastEmbed usado en esta guía:
cd /opt/odysseus
grep '^FASTEMBED_CACHE_PATH=' .env
El valor esperado es:
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache
Después reinicia el contenedor:
docker compose up -d odysseus
docker compose logs --tail=120 odysseus
En el primer arranque, FastEmbed puede descargar un pequeño modelo ONNX desde Hugging Face. Una advertencia sobre peticiones Hugging Face no autenticadas es normal si no has definido HF_TOKEN.
Si has perdido la contraseña admin inicial, lo más limpio es definir un nuevo ODYSSEUS_ADMIN_PASSWORD antes del uso real. Si la instancia ya contiene usuarios y datos, gestiona la recuperación desde la interfaz de administración o la documentación del proyecto para no sobrescribir tu configuración.
Si pierdes la contraseña de administrador después de la configuración inicial, puedes restablecer la autentificación deteniendo el servicio y eliminando el archivo data/auth.json (lo que reiniciará el proceso de inicialización en el próximo arranque):
cd /opt/odysseus
docker compose down
mv data/auth.json data/auth.json.bak
docker compose up -d
15. Buenas prácticas de seguridad
Odysseus puede manejar herramientas potentes: shell, archivos, documentos, correo, calendario, modelos, webhooks, tokens y MCP. Trátalo como una consola de administración.
- Mantén
AUTH_ENABLED=truecuando la instancia sea accesible por red. - Mantén
LOCALHOST_BYPASS=falsefuera del desarrollo local. - Activa
SECURE_COOKIES=trueen cuanto el acceso pase por HTTPS. - No expongas directamente ChromaDB, SearXNG, ntfy, Ollama, vLLM, llama.cpp ni APIs de modelos.
- Limita las cuentas admin y revisa los privilegios de usuarios no admin.
- Activa 2FA si tu versión y configuración lo permiten.
- No pegues claves API en capturas, logs o conversaciones compartidas.
- Haz backup periódico de
.envydata/, y guarda las copias fuera del VPS.
Odysseus está diseñado con privilegios locales avanzados (privileged local capabilities), lo que le permite interactuar directamente con el sistema de archivos y ejecutar comandos a través de su terminal integrada. Trata esta interfaz como una verdadera consola de administración y no concedas acceso a usuarios no autorizados.
Con esta base, Odysseus se convierte en un workspace IA privado que puedes hacer crecer poco a poco: primero una interfaz conectada a un proveedor, después un agente con herramientas, y más adelante un entorno local real con modelos, memoria, búsqueda y automatizaciones.
Para alojar este tipo de workspace en una máquina estable, un servidor VPS es una buena base: acceso root, servicios persistentes, reverse proxy, backups y escalado progresivo. En BoxToPlay puedes probar gratis tu servidor VPS y construir tu propio entorno IA self-hosted a tu ritmo.