Como instalar e executar o Odysseus AI: escolha o caminho e valide o primeiro login

Escolha Docker, modo nativo ou o guia da plataforma

O projeto oficial apresenta Docker Compose como um início repetível para muitos usuários. A aplicação e os serviços auxiliares ficam em uma pilha conhecida, o que facilita reconstruir um ambiente limpo. O cuidado principal é lembrar que localhost dentro de um contêiner não é automaticamente o localhost do navegador ou do host.

O modo nativo é útil quando você quer controlar processos diretamente, depurar Python ou aproveitar a aceleração específica do sistema. Nesse caso, você administra ambiente Python, dependências, portas e logs. No Windows, prefira o guia próprio, pois WSL2, Docker Desktop, PowerShell e Ollama podem formar várias camadas de rede.

Faça o pré-voo antes da instalação

Muitos erros do primeiro início vêm do ambiente. Antes de clonar o repositório, decida onde a aplicação ficará, onde os dados persistentes serão guardados e se o modelo estará no mesmo computador. Comece com uma base pequena; não adicione modelo, proxy, LAN e busca ao mesmo tempo.

Reserve espaço para código, contêineres, logs, modelos e documentos. RAM e VRAM de um modelo local são diferentes dos requisitos do workspace. O primeiro teste deve ser feito no navegador da mesma máquina usando localhost; rede local e exposição pública ficam para depois da troca de credenciais.

• Confirme Git, Docker Compose ou o runtime nativo do caminho escolhido.
• Escolha uma pasta persistente para repositório, .env, volumes, logs e backups.
• Mantenha o primeiro teste em localhost e não use 0.0.0.0 por padrão.
• Registre se Ollama e SearXNG ficarão no host, em Docker ou em outra máquina.
• Compare os comandos com o README e o guia oficial atuais.

Instale e inicie o workspace

Para a primeira tentativa, Docker costuma ser o caminho mais curto para uma base repetível. Clone o repositório oficial, leia o README atual, copie o arquivo de ambiente de exemplo quando existir e inicie o Compose. Não invente versão e não trate um tutorial antigo como se fosse o estado atual.

A instalação nativa segue a mesma ideia com mais responsabilidade no host: criar o ambiente Python compatível, instalar dependências, executar a configuração e iniciar o processo. No Windows, use o launcher do projeto em vez de misturar comandos de Linux com PowerShell.

1. Inicie apenas a base

   Não configure proxy, LAN, modelo e busca ao mesmo tempo. Primeiro, obtenha um processo saudável.

2. Leia os logs antes de mudar portas

   Se o navegador não conectar, verifique saúde do processo e logs antes de trocar a URL.

3. Registre a branch

   O projeto pode diferenciar branch de desenvolvimento e branch mais curada. Confirme o README atual.

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

Conecte Ollama e busca separadamente

Quando o workspace abrir, conecte o backend do modelo. Se os dois processos forem nativos no mesmo host, localhost pode funcionar. Se o Odysseus estiver em Docker e o Ollama no host, localhost normalmente aponta para o contêiner. Use o gateway descrito no guia Docker e teste a partir do mesmo ambiente de rede da aplicação.

A busca é outra fronteira. Um SearXNG incluído pode ser acessado pelo nome do serviço Compose; uma instância externa precisa de uma URL que o Odysseus consiga alcançar. Uma página aberta não prova que modelo e busca funcionam, então faça um teste pequeno de cada serviço.

Verifique o primeiro login antes de trabalhar

O primeiro login é um ponto de controle operacional. Abra a porta local indicada pelo caminho atual, confirme que é a instância que acabou de iniciar e troque imediatamente a senha temporária de administrador. Se houver uma página vazia ou proxy, volte ao endereço local direto.

Depois, confira em Settings se os serviços esperados aparecem. Use uma tarefa curta sem arquivos sensíveis, leia a resposta e o plano e pare se não entender as alterações propostas.

1. Abrir a página local

   Use a porta mostrada pelos logs e pelo guia atual, não uma URL antiga encontrada em outro artigo.

2. Trocar credenciais

   Substitua a senha gerada antes de testar LAN, VPN ou proxy reverso.

3. Testar o modelo

   Envie um prompt curto e confirme provedor e modelo selecionados.

4. Testar o fluxo

   Abra um exemplo, revise o plano e mantenha aprovação manual no início.

Crie um processo de execução repetível

Uma execução confiável separa preparação da máquina, inicialização da aplicação, conexão dos serviços e aprovação do usuário. Quando tudo é misturado, qualquer falha parece ser do modelo. Mantenha um pequeno runbook com caminho escolhido, URL local, branch ou commit testado, endpoints, pasta de dados e comando de parada.

Esse registro transforma a próxima reinicialização em um procedimento conhecido, especialmente quando Docker, Ollama, SearXNG e um proxy usam redes diferentes.

Resolva falhas comuns de execução

Os erros iniciais geralmente envolvem processo não saudável, porta errada, localhost visto de outro contêiner, serviço opcional inacessível ou volume e credencial mal interpretados. Comece pela menor camada que falhou e não mude várias variáveis ao mesmo tempo.

Ao seguir vídeos ou guias da comunidade, compare branch, porta, variáveis e nomes de serviços com o repositório oficial. Um tutorial pode ser útil e ainda estar desatualizado.

Atualize mantendo o controle

Nenhum comando universal substitui a leitura das instruções atuais. Antes de fazer pull ou rebuild, faça backup dos dados importantes, registre branch ou commit e verifique mudanças em variáveis e serviços. Com volumes, documentos e credenciais, um rebuild é uma operação com estado.

No Docker, pare e inspecione a pilha antes de recriá-la. No modo nativo, preserve o ambiente e as mudanças compreendidas e atualize dependências de forma deliberada. Antes de sair do localhost, prepare autenticação, HTTPS, controles de rede e rollback.