Come installare Odysseus AI su Linux: guida nativa e Docker

Scegli tra Linux nativo e Docker prima di installare

Docker è la scelta predefinita per lo stack documentato, container riproducibili e una separazione chiara dall'host. L'installazione nativa è utile per sviluppo, osservazione diretta dei processi Python e Uvicorn o uso di strumenti di sistema senza il livello di rete dei container.

Un modello locale non obbliga al percorso nativo. Odysseus può collegarsi a Ollama, vLLM, SGLang o altri endpoint compatibili in entrambi i casi. Docker non garantisce automaticamente la GPU: driver host, runtime e overlay devono esporre il dispositivo corretto.

Esegui i controlli preliminari Linux

Prima di clonare, conferma branch, interprete, porta, spazio e posizione dell'inferenza. dev è il branch predefinito per le modifiche più recenti; main è descritto come più curato. Non esistono GitHub Releases, tag o binari ufficiali versionati, quindi questa pagina non inventa una versione o un installer più recente.

Per la modalità nativa serve Python 3.11 o successivo. Per Docker verifica Engine e plugin Compose. La porta 7000 deve essere libera salvo una scelta diversa in APP_PORT. Per download e processi di modelli in background con Cookbook nativo, la guida ufficiale cita anche tmux.

1. Scegli dev o main

   dev riceve prima le novità; main privilegia una selezione più curata.

2. Decidi dove gira il modello

   Può essere su questo host, su un altro server o tramite API.

3. Controlla la porta

   Verifica 7000 o imposta un altro APP_PORT.

4. Mantieni privato il primo avvio

   Usa 127.0.0.1 finché non cambi la password generata.

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

Installazione nativa di Odysseus AI su Linux

Il percorso nativo crea un ambiente virtuale isolato, installa le dipendenze, esegue la configurazione e avvia l'applicazione ASGI con Uvicorn. Usa un account normale in una cartella controllata. Evita sudo pip, che mescola i pacchetti del progetto con Python di sistema e rende più difficile la manutenzione.

Il comando iniziale ascolta solo su loopback, scelta corretta per il primo test. Configura systemd o un supervisore solo dopo aver verificato avvio interattivo, login e modello. Il servizio deve usare lo stesso percorso, interprete virtuale e variabili già testate.

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

Installare Odysseus AI con Docker Compose

Il quick start ufficiale raccomanda Docker. Copiare .env.example è facoltativo ma rende espliciti i valori di deployment. Costruisci e avvia i container, attendi i controlli di salute e leggi nei log Odysseus la password temporanea.

Compose lega l'interfaccia a 127.0.0.1 per impostazione predefinita. Se 7000 è occupata, imposta APP_PORT=7001 o un'altra porta libera e ricrea il container. APP_BIND=0.0.0.0 non risolve un conflitto di porta: indirizzo e porta sono impostazioni diverse.

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 il primo login prima di aggiungere modelli

Apri http://localhost:7000 dall'host Linux. La prima configurazione crea un account amministratore e mostra una password temporanea nel terminale o nei log. Accedi, cambiala nelle impostazioni e prova una nuova sessione del browser prima di consentire accesso remoto.

Poi aggiungi un solo endpoint noto e invia una richiesta breve. Se l'interfaccia funziona ma la risposta fallisce, l'installazione è probabilmente corretta. Controlla URL, credenziali, nome del modello, firewall e runtime invece di reinstallare tutto.

1. Apri la pagina locale

   Conferma la schermata di login su localhost:7000.

2. Leggi la password generata

   Usa terminale o log, senza indovinare password predefinite.

3. Cambia le credenziali

   Fallo prima di LAN, VPN o proxy.

4. Prova un modello

   Inizia con un endpoint conosciuto e un prompt breve.

La GPU è soprattutto una scelta del runtime del modello

Il workspace è relativamente leggero; la GPU serve soprattutto per inferenza locale. La modalità nativa può usare Ollama dell'host. Anche Docker può collegarsi a un endpoint host o remoto senza montare il socket Docker.

Per NVIDIA o AMD in container verifica prima driver e passthrough. Script e overlay ufficiali aiutano la diagnosi. nvidia-smi nel container conferma l'accesso al dispositivo, non la disponibilità delle librerie CUDA o ROCm corrette per llama.cpp, vLLM o SGLang.

scripts/check-docker-gpu.sh

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

Collegare Odysseus a Tailscale su Linux in sicurezza

Similarweb ha individuato connect odysseus to tailscale linux come query di supporto a bassa difficoltà. Va trattata in questa guida perché l'accesso remoto inizia solo dopo una corretta installazione locale; non giustifica una pagina separata e sottile.

Lega l'applicazione intenzionalmente a 0.0.0.0 o all'interfaccia corretta, conserva l'autenticazione, limita i dispositivi con regole Tailscale o firewall e usa HTTPS quando il browser richiede un'origine sicura. Non inoltrare direttamente su Internet né la porta dell'app né quella del modello.

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

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Aggiornare Linux senza inventare una versione

Al 30 luglio 2026 non erano presenti Release o tag ufficiali. dev cambia rapidamente e main è più curato. Questa guida non dichiara quindi una versione più recente, dimensione del file, installer o link diretto permanente.

Prima di aggiornare annota il branch, esegui il backup di dati e .env, leggi le modifiche e aggiorna lo stesso branch. Non passare da main a dev durante una manutenzione non correlata. Ricostruisci container o dipendenze e ripeti i test di login, modello e rete.

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

Tabella di risoluzione problemi Linux

Isola nell'ordine processo, porta, login, endpoint del modello e servizi opzionali. Cambiare più livelli insieme nasconde la causa.