Como instalar Odysseus AI no Linux: guia nativo e Docker

Escolha Linux nativo ou Docker antes de instalar

Docker é a escolha padrão para obter a pilha documentada, contêineres reproduzíveis e separação do host. A instalação nativa é útil para desenvolvimento, inspeção direta dos processos Python e Uvicorn ou uso de ferramentas do sistema sem a camada de rede dos contêineres.

Um modelo local não obriga a instalação nativa. Odysseus pode se conectar a Ollama, vLLM, SGLang ou outro endpoint compatível nos dois métodos. Docker também não garante GPU: drivers, runtime e overlay precisam expor o dispositivo correto.

Faça as verificações antes de clonar

Confirme branch, Python, porta, armazenamento e local da inferência. dev é o branch padrão com mudanças mais recentes; main é descrito como mais curado. Não existem Releases, tags ou binários oficiais versionados, portanto esta página não inventa uma versão ou instalador mais recente.

Para a instalação nativa é necessário Python 3.11 ou posterior. Para Docker, verifique Engine e o plugin Compose. A porta 7000 deve estar livre, salvo outra escolha em APP_PORT. Para downloads e processos de modelos em segundo plano com Cookbook nativo, a documentação também menciona tmux.

1. Escolha dev ou main

   dev recebe novidades primeiro; main prioriza uma seleção mais curada.

2. Defina onde o modelo roda

   Pode ser neste host, em outro servidor ou por API.

3. Confira a porta

   Verifique 7000 ou configure outro APP_PORT.

4. Mantenha o primeiro início privado

   Use 127.0.0.1 até trocar a senha gerada.

python3 --version
docker --version
docker compose version
ss -ltn | grep ':7000' || true

Instalação nativa do Odysseus AI no Linux

O caminho nativo cria um ambiente virtual isolado, instala dependências, executa a configuração e inicia a aplicação ASGI com Uvicorn. Use um usuário comum em uma pasta controlada. Evite sudo pip, pois ele mistura pacotes do projeto com o Python do sistema e dificulta manutenção e remoção.

O comando inicial escuta apenas em loopback, o correto para o primeiro teste. Configure systemd ou outro supervisor somente depois de validar início interativo, login e modelo. O serviço deve reutilizar o mesmo diretório, interpretador virtual e variáveis testadas.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py

python -m uvicorn app:app --host 127.0.0.1 --port 7000

Instalar Odysseus AI com Docker Compose

O início rápido oficial recomenda Docker. Copiar .env.example é opcional, mas deixa os valores de implantação explícitos. Construa e inicie os contêineres, aguarde os health checks e consulte os logs do Odysseus para a senha temporária.

Compose vincula a interface a 127.0.0.1 por padrão. Se 7000 estiver ocupada, defina APP_PORT=7001 ou outra porta livre e recrie o contêiner. APP_BIND=0.0.0.0 não corrige conflito de porta; endereço e porta são configurações diferentes.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

docker compose ps
docker compose logs odysseus --tail=120

Verifique o primeiro login antes de adicionar modelos

Abra http://localhost:7000 no host Linux. A primeira configuração cria uma conta administrativa e mostra uma senha temporária no terminal ou nos logs. Entre, troque a senha nas configurações e teste uma nova sessão do navegador antes do acesso remoto.

Depois adicione apenas um endpoint conhecido e envie uma solicitação curta. Se a interface funciona mas a resposta falha, a instalação provavelmente está correta. Verifique URL, credenciais, nome do modelo, firewall e runtime em vez de reinstalar tudo.

1. Abrir a página local

   Confirmar a tela de login em localhost:7000.

2. Ler a senha gerada

   Usar terminal ou logs, sem adivinhar uma senha padrão.

3. Trocar a credencial

   Fazer isso antes de LAN, VPN ou proxy.

4. Testar um modelo

   Começar com um endpoint conhecido e prompt curto.

A GPU é principalmente uma escolha do runtime do modelo

O workspace é relativamente leve; a GPU é usada principalmente para inferência local. O modo nativo pode usar Ollama do host. Docker também pode acessar um endpoint do host ou remoto sem montar o socket Docker.

Para NVIDIA ou AMD em contêiner, valide primeiro drivers e passthrough. Scripts e overlays oficiais ajudam no diagnóstico. nvidia-smi dentro do contêiner confirma acesso ao dispositivo, não a presença das bibliotecas CUDA ou ROCm adequadas para llama.cpp, vLLM ou SGLang.

scripts/check-docker-gpu.sh

http://host.docker.internal:11434/v1

Conectar Odysseus ao Tailscale no Linux com segurança

Similarweb encontrou connect odysseus to tailscale linux como consulta de apoio de baixa dificuldade. Ela deve ficar neste guia porque o acesso remoto só começa depois de uma instalação local funcional; não justifica uma página separada e superficial.

Vincule o aplicativo de forma intencional a 0.0.0.0 ou à interface adequada, mantenha a autenticação, limite dispositivos por regras do Tailscale ou firewall e use HTTPS quando o navegador exigir uma origem segura. Não encaminhe diretamente para a Internet a porta do aplicativo nem a do modelo.

python -m uvicorn app:app --host 0.0.0.0 --port 7000

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Atualizar sem inventar uma versão

Em 30 de julho de 2026 não havia Release ou tag oficial. dev muda rapidamente e main é mais curado. Por isso este guia não afirma versão mais recente, tamanho, instalador binário ou link direto permanente.

Antes de atualizar, anote o branch, faça backup de dados e .env, leia as mudanças e atualize o mesmo branch. Não troque de main para dev durante manutenção não relacionada. Reconstrua contêineres ou dependências e repita os testes de login, modelo e rede.

git status --short
git branch --show-current
git pull --ff-only
# Docker
docker compose up -d --build

Tabela de solução de problemas no Linux

Isole processo, porta, login, endpoint do modelo e serviços opcionais nessa ordem. Alterar várias camadas ao mesmo tempo esconde a causa.