10 min di lettura 11 giugno 2026

Installare Odysseus AI su macOS: Apple Silicon, Docker e Ollama

Guida pratica per Mac: percorso nativo Apple Silicon, quando usare Docker, collegamento a Ollama e controlli prima di esporre il workspace.

Odysseus AI Wiki

Fan-made editorial notes based on public Odysseus AI documentation, GitHub setup discussions, and local self-hosting patterns.

Installare Odysseus AI su macOS: Apple Silicon, Docker e Ollama

Risposta breve: Su un Mac Apple Silicon, parti dal percorso nativo se vuoi accelerazione locale e meno confusione di rete. Docker è utile per test isolati, ma non sempre è il default migliore quando Ollama gira già sullo stesso Mac.

Chi usa Mac arriva a Odysseus AI con due obiettivi: avviare rapidamente l’app o collegare un workspace locale a Ollama e ai modelli già presenti su un Mac M-series. Questa guida separa i due casi prima di modificare porte, file di ambiente o impostazioni modello.

Scegli il percorso Mac in base a cosa vuoi verificare

Se vuoi solo verificare che il workspace Odysseus AI parta, Docker è un percorso controllato con dipendenze isolate. Se vuoi usare modelli locali su Apple Silicon, il percorso nativo è spesso il primo test più adatto.

Non esiste un percorso sempre migliore. Docker verifica l’avvio riproducibile in container. Il percorso nativo verifica se il Mac può eseguire il workspace vicino a modelli, file e strumenti locali.

Punto di partenza nativo macOS

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

Percorso nativo Apple Silicon: prima ambiente, poi modelli

Il percorso nativo macOS conta perché molti utenti Apple Silicon vogliono tenere Ollama, modelli locali e file accanto al workspace. Controlla prima repository, permessi dello script, dipendenze Python e porta locale.

Un primo avvio pulito deve mostrare una UI locale raggiungibile e chiedere configurazione o login. Password generate e secret locali restano dettagli operativi temporanei.

1. Clona il repository ufficiale

Usa il repository ufficiale come fonte per script, issue e modifiche README.

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

2. Esegui il launcher macOS e leggi il primo errore

Il primo errore indica spesso permessi, Python, dipendenze o conflitto di porta.

chmod +x ./start-macos.sh
./start-macos.sh

3. Apri la UI locale e completa il primo login

Se l’app parte sulla porta documentata, apri quell’URL e sostituisci eventuali credenziali temporanee.

http://127.0.0.1:7860

4. Configura i modelli solo dopo

Quando il workspace è sano, collega Ollama o un altro provider da Settings.

http://127.0.0.1:11434/v1

Docker su macOS: isolamento utile con compromessi

Docker resta utile su Mac per test usa e getta, confini chiari delle dipendenze o validazione simile al server.

L’errore comune è confondere localhost: nel container indica il container, sull’host indica il Mac.

Scelta	Ideale per	Attenzione
Apple Silicon nativo	Modelli locali, meno livelli di rete e Ollama più semplice	Mantieni sane Python e dipendenze locali.
Docker su macOS	Test puliti, dipendenze isolate e validazione tipo deploy	Usa host.docker.internal per raggiungere Ollama sull’host.
Host Linux remoto	Workspace sempre attivo, GPU server o accesso team	Non esporre senza auth, firewall e proxy.

Ollama, accelerazione Metal e scelta endpoint

Ollama è normalmente un server di modelli separato. Su Mac questo aiuta: Ollama resta nel runtime locale e Odysseus AI punta all’API compatibile.

Usa 127.0.0.1 se Odysseus AI e Ollama girano nativi sullo stesso Mac. Usa host.docker.internal se Odysseus AI gira in Docker e Ollama sull’host.

Endpoint Mac nativo verso Ollama locale

http://127.0.0.1:11434/v1

Risoluzione problemi Odysseus AI su macOS

Procedi da avvio a rete e poi modello. Se la UI non è sana, gli errori modello sono probabilmente secondari.

Sintomo	Causa probabile	Correzione
Lo script macOS non parte	Permesso, policy shell o dipendenza mancante.	Esegui chmod +x, parti dalla root del repo e leggi il primo errore.
Il browser non apre la UI	App non in ascolto o porta occupata.	Controlla il terminale e libera la porta.
Ollama funziona in Terminale ma non in Odysseus	Endpoint non coerente con nativo/Docker.	127.0.0.1 nativo, host.docker.internal da Docker.
Primo prompt lento	Modello in caricamento o memoria limitata.	Prova un modello piccolo prima di agenti/documenti.
Accesso da altro dispositivo	Il binding locale protegge il servizio.	Pianifica auth, firewall e proxy prima.

Checklist finale per Mac

L’installazione Mac è pronta quando workspace, endpoint modello e confine di sicurezza sono chiari.

La UI si apre localmente dopo un avvio pulito.
Sai se stai usando nativo, Docker o remoto.
Ollama risponde separatamente prima di Odysseus AI.
Un modello piccolo funziona prima di agenti/documenti.
Il workspace non è esposto senza regole.

Mantieni locale il primo test

Il default sicuro è localhost per Odysseus AI e Ollama finché capisci il flusso.