Come installare ed eseguire Odysseus AI: scegli il percorso e verifica il primo accesso

Scegli Docker, nativo o una guida per piattaforma

Il progetto ufficiale presenta Docker Compose come un punto di partenza ripetibile per molti utenti. L'applicazione e i servizi ausiliari restano in uno stack noto, rendendo più semplice ricostruire un ambiente pulito. Il punto da ricordare è che localhost dentro un container non coincide automaticamente con localhost del browser o dell'host.

La modalità nativa è utile quando vuoi controllare direttamente i processi, fare debug di Python o usare l'accelerazione locale specifica del sistema. In questo caso amministri ambiente Python, dipendenze, porte e log. Su Windows è preferibile la guida dedicata, perché WSL2, Docker Desktop, PowerShell e Ollama possono creare più livelli di rete.

Fai i controlli preliminari prima dell'installazione

Molti errori del primo avvio dipendono dall'ambiente. Prima di clonare il repository, decidi dove vivrà l'applicazione, dove conserverai i dati persistenti e se il modello sarà sullo stesso computer. Parti da una base piccola: non aggiungere contemporaneamente modello, proxy, LAN e ricerca.

Riserva spazio per codice, container, log, modelli e documenti. I requisiti di RAM e VRAM di un modello locale sono diversi da quelli del workspace. Il primo test dovrebbe essere eseguito dal browser della stessa macchina usando localhost; rete locale ed esposizione pubblica vengono dopo il cambio delle credenziali.

• Verifica Git, Docker Compose o il runtime nativo del percorso scelto.
• Scegli una cartella persistente per repository, .env, volumi, log e backup.
• Mantieni il primo test su localhost e non usare 0.0.0.0 per abitudine.
• Annota se Ollama e SearXNG saranno eseguiti sull'host, in Docker o su un altro computer.
• Confronta i comandi con il README e la guida ufficiale aggiornati.

Installa e avvia il workspace

Per il primo tentativo, Docker è spesso il percorso più breve verso una base ripetibile. Clona il repository ufficiale, leggi il README attuale, copia il file di ambiente di esempio quando esiste e avvia Compose. Non inventare versioni e non trattare un tutorial vecchio come se descrivesse lo stato attuale.

L'installazione nativa segue la stessa idea, ma richiede più responsabilità sull'host: crea l'ambiente Python compatibile, installa le dipendenze, esegui la configurazione e avvia il processo. Su Windows usa il launcher del progetto invece di mescolare comandi Linux e PowerShell.

1. Avvia solo la base

   Non configurare proxy, LAN, modello e ricerca tutti insieme. Prima ottieni un processo sano.

2. Leggi i log prima di cambiare porta

   Se il browser non si connette, controlla lo stato del processo e i log prima di modificare l'URL.

3. Registra il branch

   Il progetto può distinguere tra un branch di sviluppo e uno più curato. Conferma il README attuale.

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

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

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

Collega Ollama e la ricerca separatamente

Quando il workspace si apre, collega il backend del modello. Se entrambi i processi sono nativi sullo stesso host, localhost può funzionare. Se Odysseus è in Docker e Ollama gira sull'host, localhost normalmente indica il container. Usa il gateway descritto nella guida Docker e prova la connessione dallo stesso ambiente di rete dell'applicazione.

La ricerca è un altro confine. Un SearXNG incluso può essere raggiunto tramite il nome del servizio Compose; un'istanza esterna richiede un URL raggiungibile da Odysseus. Una pagina aperta non dimostra che modello e ricerca funzionino, quindi esegui un test piccolo per ciascun servizio.

Verifica il primo accesso prima di lavorare

Il primo accesso è un controllo operativo. Apri la porta locale indicata dal percorso attuale, conferma che sia l'istanza appena avviata e cambia subito la password temporanea dell'amministratore. Se trovi una pagina vuota o un proxy, torna direttamente all'indirizzo locale.

Poi controlla in Settings che compaiano i servizi attesi. Usa una breve attività senza file sensibili, leggi la risposta e il piano e fermati se non comprendi le modifiche proposte.

1. Apri la pagina locale

   Usa la porta mostrata dai log e dalla guida aggiornata, non un URL vecchio trovato in un altro articolo.

2. Cambia le credenziali

   Sostituisci la password generata prima di provare LAN, VPN o proxy inverso.

3. Prova il modello

   Invia un prompt breve e conferma provider e modello selezionati.

4. Prova il flusso

   Apri un esempio, rivedi il piano e mantieni l'approvazione manuale all'inizio.

Crea una procedura di esecuzione ripetibile

Un'esecuzione affidabile separa la preparazione della macchina, l'avvio dell'applicazione, il collegamento dei servizi e l'approvazione dell'utente. Quando tutto è mescolato, ogni errore sembra dipendere dal modello. Conserva un breve runbook con percorso scelto, URL locale, branch o commit verificato, endpoint, cartella dati e comando di arresto.

Questo registro trasforma il prossimo riavvio in una procedura conosciuta, soprattutto quando Docker, Ollama, SearXNG e un proxy usano reti diverse.

Risolvi i problemi comuni di avvio

Gli errori iniziali riguardano spesso un processo non sano, una porta errata, localhost visto da un altro container, un servizio opzionale non raggiungibile o un volume e una credenziale interpretati male. Parti dal livello più piccolo che ha fallito e non cambiare più variabili contemporaneamente.

Quando segui video o guide della community, confronta branch, porta, variabili e nomi dei servizi con il repository ufficiale. Un tutorial può essere utile e allo stesso tempo non essere aggiornato.

Aggiorna mantenendo il controllo

Nessun comando universale sostituisce la lettura delle istruzioni attuali. Prima di fare pull o rebuild, esegui il backup dei dati importanti, registra branch o commit e controlla i cambiamenti a variabili e servizi. Con volumi, documenti e credenziali, un rebuild è un'operazione con stato.

In Docker, arresta e controlla lo stack prima di ricrearlo. In modalità nativa, conserva l'ambiente e le modifiche comprese e aggiorna le dipendenze deliberatamente. Prima di uscire da localhost, prepara autenticazione, HTTPS, controlli di rete e rollback.