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

2026 update: Instalacao Odysseus AI no macOS

A nova secao separa Docker, execucao nativa e endpoints Ollama antes de alterar configuracoes.

Atualizado com notas 2026 sobre fontes oficiais, execucao local, Ollama e guias relacionados.

Verificacao	Bom resultado	Se falhar
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.

A nova secao separa Docker, execucao nativa e endpoints Ollama antes de alterar configuracoes.
Atualizado com notas 2026 sobre fontes oficiais, execucao local, Ollama e guias relacionados.
Keep the page intent separate from sibling setup guides.