10 min de leitura 11 de junho de 2026

Instalar Odysseus AI no macOS: Apple Silicon, Docker e Ollama

Guia prático para Mac cobrindo o caminho nativo no Apple Silicon, quando Docker faz sentido, como ligar Ollama e o que validar antes de expor o workspace.

Odysseus AI Wiki

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

Instalar Odysseus AI no macOS: Apple Silicon, Docker e Ollama

Resposta curta: Em um Mac com Apple Silicon, comece pelo caminho nativo se você quer aceleração local e menos confusão de rede. Docker é útil para teste isolado, mas pode não ser o melhor padrão quando Ollama e modelos locais já rodam no Mac.

Usuários de Mac normalmente chegam ao Odysseus AI com dois objetivos: iniciar a aplicação de forma limpa ou conectar um workspace local ao Ollama e aos modelos em um Mac com chip M. Este guia separa essas metas antes de mexer em portas, arquivos de ambiente ou configurações de modelo.

Escolha o caminho do Mac pelo que você quer provar primeiro

Se você só quer ver o workspace Odysseus AI iniciar, Docker é um caminho controlado e isola dependências. Se quer usar runtimes locais de modelos em um Mac Apple Silicon, o caminho nativo costuma ser o melhor primeiro teste.

Nenhum caminho é sempre superior. Docker responde se a app sobe em um contêiner reproduzível. O caminho nativo responde se o Mac consegue rodar o workspace perto dos modelos, arquivos e ferramentas locais.

Ponto de partida nativo no macOS

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

Caminho nativo Apple Silicon: valide o ambiente antes dos modelos

O caminho nativo importa porque usuários Apple Silicon geralmente querem manter Ollama, modelos locais e arquivos próximos do workspace. Confira primeiro repositório, permissão do script, dependências Python e porta local.

Um primeiro start limpo deve mostrar uma UI local acessível e pedir configuração ou login. Trate senhas geradas e secrets locais como detalhes temporários.

1. Clone o repositório oficial

Use o repositório oficial como fonte para scripts, issues e mudanças do README.

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

2. Execute o launcher macOS e leia o primeiro erro

O primeiro erro normalmente indica permissão, Python, dependência ou conflito de porta.

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

3. Abra a UI local e conclua o login

Se a app iniciar na porta documentada, abra essa URL e substitua credenciais temporárias.

http://127.0.0.1:7860

4. Configure modelos só depois

Com o workspace saudável, conecte Ollama ou outro provedor em Settings.

http://127.0.0.1:11434/v1

Docker no macOS: isolamento útil com tradeoff

Docker é válido no Mac para testes descartáveis, fronteira limpa de dependências ou validação parecida com servidor.

O erro comum é misturar localhost: dentro do contêiner é o contêiner; no host é o Mac.

Escolha	Melhor para	Atenção
Apple Silicon nativo	Modelos locais, menos camadas de rede e Ollama mais simples	Mantenha Python e dependências locais saudáveis.
Docker no macOS	Testes limpos, dependências isoladas e validação de deploy	Use host.docker.internal para alcançar Ollama no host.
Host Linux remoto	Workspace sempre ativo, GPU de servidor ou equipe	Não exponha sem auth, firewall e proxy.

Ollama, aceleração Metal e escolha de endpoint

Ollama normalmente é um servidor de modelos separado. No Mac, isso ajuda: Ollama fica no runtime local e Odysseus AI aponta para a API compatível.

Use 127.0.0.1 quando ambos rodam nativos no Mac. Use host.docker.internal quando Odysseus AI está em Docker e Ollama no host.

Endpoint nativo do Mac para Ollama local

http://127.0.0.1:11434/v1

Solução de problemas do Odysseus AI no macOS

Siga de inicialização para rede e depois modelo. Se a UI não está saudável, erros de modelo são secundários.

Sintoma	Causa provável	Correção
Script macOS não roda	Permissão, política de shell ou dependência.	Use chmod +x, rode na raiz do repo e leia o primeiro erro.
Navegador não abre a UI	App não escuta ou porta ocupada.	Veja o terminal e libere a porta.
Ollama funciona no Terminal, não no Odysseus	Endpoint não bate com nativo/Docker.	127.0.0.1 nativo, host.docker.internal no Docker.
Primeiro prompt lento	Modelo carregando ou memória pressionada.	Teste modelo pequeno antes de agentes/documentos.
Abrir de outro dispositivo	Binding local protege o serviço.	Planeje auth, firewall e proxy antes.

Checklist final para instalação no Mac

A instalação está pronta quando workspace, endpoint e limite de segurança estão claros.

UI abre localmente após start limpo.
Você sabe se é nativo, Docker ou remoto.
Ollama responde separado antes do Odysseus AI.
Modelo pequeno funciona antes de agentes/documentos.
Workspace não está exposto sem regras.

Mantenha a primeira instalação local

O padrão seguro é localhost para Odysseus AI e Ollama enquanto você entende o fluxo.