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/odysseus-dev/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/odysseus-dev/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.

2026 update: Installazione Odysseus AI su macOS

La nuova sezione separa Docker, esecuzione nativa ed endpoint Ollama prima di modificare le impostazioni.

Aggiornata con note 2026 su fonti ufficiali, esecuzione locale, Ollama e guide correlate.

Verifica	Risultato corretto	Se fallisce
Official source	Use the upstream GitHub repository as the command source.	Compare copied commands with the current README.
Local runtime	Know whether Odysseus runs natively, in Docker, or remotely.	Pick one setup path before changing endpoints.
Related guide	Use the sibling article for detailed Mac or Ollama steps.	Follow the internal link instead of mixing keyword intents.

La nuova sezione separa Docker, esecuzione nativa ed endpoint Ollama prima di modificare le impostazioni.
Aggiornata con note 2026 su fonti ufficiali, esecuzione locale, Ollama e guide correlate.
Keep the page intent separate from sibling setup guides.