Odysseus na prática: montar uma bancada de IA self-hosted em 30 minutos

Resumo em uma frase: Você quer “sair” do ChatGPT/Claude na web e instalar toda uma bancada de IA na sua própria máquina? Este artigo te guia até o funcionamento de ponta a ponta do Odysseus — uma alternativa self-hosted ao ChatGPT, com foco em “local primeiro” e privacidade.

Visão geral do projeto

Odysseus é uma bancada de IA self-hosted (Self-hosted AI Workspace), criada pelo usuário do GitHub pewdiepie-archdaemon e lançada como software open source sob licença MIT. O objetivo dele é: fazer você ter, na sua própria máquina, a experiência de interface do ChatGPT/Claude, mas mantendo todos os dados, todas as conversas e todas as chamadas de ferramentas localmente.

Em comparação com apps tradicionais tipo ChatGPT, as diferenças são bem claras:

• Chat: assuma qualquer modelo local ou remoto (vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot)
• Agente: um agente de verdade, que consegue “agir” com MCP / Web / arquivos / Shell / Skills / memória (baseado em opencode)
• Cookbook: varre o hardware da sua máquina, recomenda modelos que realmente rodam, e você só clica uma vez para baixar + iniciar o serviço (baseado em llmfit, VRAM-aware)
• Deep Research: pesquisa em múltiplas etapas, faz fetch + leitura + síntese, e gera relatórios com visualização (adaptado de Tongyi DeepResearch)
• Compare: testes cegos entre vários modelos para escolher, sem vieses, o que é realmente bom
• Documents: você escreve texto, a IA ajuda ao lado — não é o contrário
• Memory / Skills: memória de longo prazo + sistema de habilidades; quanto mais você usa o agente, mais ele te entende (ChromaDB + fastembed ONNX)
• Email: caixa IMAP/SMTP; a IA classifica automaticamente, resume, rascunha respostas e filtra spam
• Notes & Tasks / Calendar: anotações + tarefas + calendário; sincronização CalDAV com Radicale / Nextcloud / Apple / Fastmail
• Suporte a PWA: a experiência no celular não fica atrás do desktop; dá para instalar na tela inicial

Em uma frase: não é só uma caixinha de chat — é todo o seu ambiente de IA, tudo na sua máquina, sem subir para a nuvem.

Dificuldade / tempo / ganhos

• Dificuldade: ⭐⭐⭐ (média, precisa entender um pouco de Docker / Python)
• Tempo: 30–45 minutos (caminho via Docker); 1 hora (instalação nativa + conectar modelos locais)
• Ganhos:
  • montar uma bancada self-hosted de IA com funcionalidades completas
  • entender a arquitetura típica de apps de IA “local-first” (FastAPI + ChromaDB + SearXNG + ntfy)
  • conectar APIs compatíveis com Ollama/vLLM/OpenAI na mesma interface
  • conhecer o “lado B” que é bem divertido: Cookbook escolhendo modelos automaticamente, passagem de GPU (GPU passthrough) e o sistema de memória

Para quem é

• Não quer mais assinar ChatGPT Plus / Claude Pro e quer manter os dados da IA no seu próprio ambiente
• Quer rodar modelos open source em NUC/estação/servidor com 8G / 16G / 24G de VRAM, mas com uma interface unificada
• Desenvolvedor full-stack/independente: quer juntar chat / e-mail / calendário / tarefas de agente em um único painel
• Tem interesse em “self-hosted” e quer ver um modelo de engenharia de um app FastAPI pronto para produção
• Já pagou por LLM na nuvem e quer encontrar uma forma menos dolorosa de fazer isso

Se a sua ideia é só um UI de chat leve, o Odysseus talvez não seja o mais adequado — ele tem muitas funções e é um pouco mais complexo de configurar do que o Open WebUI, mas em troca você ganha o pacote completo: e-mail, memória, Cookbook e Agent.

Dependências principais e ambiente

Requisitos mínimos:

Dependências opcionais / aprimoradas:

Estrutura completa em árvore do projeto

odysseus/
├── app.py                    # entrada FastAPI
├── setup.py                  # script de inicialização (cria admin / banco de dados / diretórios)
├── requirements.txt          # dependências Python principais
├── requirements-optional.txt # dependências opcionais (PDF/Office/voz/STT)
├── docker-compose.yml        # orquestração padrão (CPU)
├── docker-compose.gpu-nvidia.yml  # override NVIDIA GPU
├── docker-compose.gpu-amd.yml     # override AMD ROCm
├── Dockerfile
├── core/                     # camada de infraestrutura
│   ├── auth.py               # autenticação / sessões
│   ├── database.py           # inicialização do SQLAlchemy
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # camada de lógica de negócio
│   ├── llm_core.py           # abstração de LLM
│   ├── agent_loop.py         # ciclo do Agent
│   ├── agent_tools.py        # conjunto de ferramentas do Agent
│   ├── chat_processor.py     # processamento de chat
│   ├── cookbook_serve_lifecycle.py  # ciclo de vida do serviço do Cookbook
│   ├── memory_vector.py      # memória de longo prazo no ChromaDB
│   ├── deep_research.py      # deep research
│   └── ...
├── routes/                   # rotas FastAPI (40+ módulos)
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # recomendação/baixar modelos
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # serviços em background
│   ├── docs/                 # processamento de documentos
│   ├── hwfit/                # varredura de hardware (Cookbook)
│   ├── memory/               # serviço de memória
│   ├── research/             # serviço de pesquisa
│   ├── search/               # busca
│   ├── stt/ tts/             # conversão de voz para texto / texto para voz
│   └── shell/                # ferramenta Shell
├── static/                   # frontend (index.html + JS/CSS)
├── docs/                     # site de documentação + screenshots + demo
├── config/                   # configurações de serviços auxiliares como SearXNG
├── companion/                # companheiro desktop (macOS)
└── data/                     # dados do usuário (gitignored, gerado em runtime)
    ├── app.db                # SQLite
    ├── chroma/               # banco de vetores
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # cache de modelos

Dentro do diretório, você só precisa se preocupar com app.py / docker-compose.yml / .env — o resto fica por conta do Docker.

Passo a passo

Passo 1: Clonar o repositório

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

Passo 2: Preparar o .env (opcional, mas recomendado)

cp .env.example .env

Um .env mínimo que funciona assim:

# === LLM endpoints ===
LLM_HOST=localhost
# Se quiser usar uma API na nuvem, acesse o Ollama local dentro do container via host.docker.internal
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === Portas e binding ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === Segurança (crítico!) ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # Troque para true apenas se estiver usando reverse proxy com HTTPS
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # Se não preencher, na primeira inicialização ele gera aleatoriamente e imprime

# === Busca (SearXNG) ===
SEARXNG_INSTANCE=http://searxng:8080

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Passo 3: Inicialização com um clique do Docker (caminho recomendado)

docker compose up -d --build

O processo de build vai baixar imagens base + instalar dependências Python; na primeira vez, leva cerca de 3–5 minutos. Quando os 4 containers — odysseus / chromadb / searxng / ntfy — estiverem healthy / running, acabou:

docker compose ps

Abra http://localhost:7000; a primeira tela é a página de login. A senha admin inicial está nos logs do terminal:

docker compose logs --tail=200 odysseus | grep -i "temporary\|admin\|password"

Você deve ver algo como:

[odysseus] Created admin user 'admin' with temporary password: aB3x-9pQz-2vRt

Passo 4: Verificar se todos os serviços estão saudáveis

# 1. Status dos containers
docker compose ps

# 2. Ver os logs do próprio Odysseus (atenção: na primeira vez baixar modelos causa atraso)
docker compose logs --tail=120 odysseus

# 3. O ChromaDB realmente subiu (não caiu para modo degradado HTTP)
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

Se aparecer DEGRADED, na maioria das vezes é conflito entre chromadb-client e chromadb. O método de diagnóstico está na seção “Perguntas frequentes” abaixo.

Passo 5: Conectar ao seu primeiro modelo

Vá em Settings → Models / Providers e escolha um caminho de acordo com o seu ambiente:

Caminho A: Já tem Ollama rodando (o mais simples)

Base URL:  http://host.docker.internal:11434/v1
API Key:   (deixe em branco)
Model:     qwen2.5:7b (ou qualquer modelo que você tenha localmente)

Caminho B: Quer usar Cookbook para baixar e iniciar automaticamente

Entre no Cookbook. Ele vai varrer sua VRAM, recomendar modelos open source que rodam aí e te dá uma pontuação (fit score). Clique em "Download" para seguir huggingface-cli, baixando o modelo para ./data/huggingface/; depois ele sobe diretamente com llama.cpp / vLLM.

Caminho C: Conectar uma API na nuvem — é isso que vale detalhar hoje

A configuração do Provider do Odysseus é orientada por protocolo: ou seja, qualquer serviço que responda corretamente aos dois endpoints v1/chat/completions ou v1/messages pode ser conectado diretamente via Base URL — não só OpenAI/Anthropic oficiais, mas também gateways próprios e encaminhadores de terceiros.

No meu deployment, a rotina “Agent rodando código / documentos longos” usa API na nuvem por dois motivos:

1. Rodar um 70B quantizado com GPU local de 24G já custa, e abrir o Agent com várias etapas frequentemente leva a OOM
2. Modelos de ponta como Claude/GPT ainda são uma categoria acima do Qwen2.5-Coder em inferência complexa

Mas aí vem o problema — API oficial é cara. O faturamento do Claude Opus em uma semana facilmente passa de cem dólares; pra uso pessoal, vira basicamente trabalho para a Anyscale.

Minha solução agora é usar Defapi, que usa o endpoint compatível com v1/messages:

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # pegue no painel do defapi.org
Model:     anthropic/claude-sonnet-4.5 # ou haiku-4.5 / opus-4.6

Exemplos: Defapi Claude Sonnet 4.5 (força para programação/documentos longos), Claude Haiku 4.5 (para chamadas diárias do Agent, mais barato).

Na prática, para a mesma quantidade de conversas/tarefas por mês, a conta cai bem mais da metade em comparação com Anthropic oficial; e a capacidade do modelo, chamadas de ferramentas do Agent e formatos de prompt não mudam de forma alguma — porque é um proxy na camada de protocolo; o modelo em si continua o mesmo. Esse design “orientado a protocolo” do Odysseus casa perfeitamente com isso.

Caminho D: Conectar GitHub Copilot / OpenRouter etc.

Esses também são compatíveis com o protocolo OpenAI. Basta preencher o Base URL como https://api.githubcopilot.com / https://openrouter.ai/api/v1, respectivamente; não vou estender aqui.

Passo 6: Primeira conversa + primeira tarefa do Agent

Volte para a interface principal, selecione um modelo e faça um teste simples de prompt para validar a conexão:

Apresente-se em três frases e, em seguida, me dê uma lista de checagem de desempenho para troubleshooting de Linux que funcione hoje.

Se passou, significa que o caminho até o LLM está ok.

Agora teste o modo Agent: crie uma nova sessão, troque para "Agent" e insira:

Liste o número de linhas de todos os arquivos .py no diretório atual e, depois, me diga qual arquivo vale mais a pena refatorar.

O Agent vai planejar sozinho:

1. chamar a ferramenta shell para rodar find . -name "*.py" | xargs wc -l
2. analisar o resultado
3. dar recomendações

Essa é a diferença fundamental entre Agent self-hosted e o ChatGPT na web: ele realmente consegue “agir”; seu código, seus arquivos e o terminal — ele tem acesso.

Passo 7 (opcional): Habilitar GPU

Esta etapa é necessária apenas se você for usar inferência local “pesada” como vLLM/SGLang/llama.cpp CUDA. Se você só usa Ollama ou API na nuvem, pode pular.

NVIDIA:

# Diagnóstico rápido
scripts/check-docker-gpu.sh

# Instalar NVIDIA Container Toolkit (Ubuntu/Debian, precisa de sudo)
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# Só habilite o overlay depois de confirmar que o passthrough funciona
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# Verificar
docker compose exec odysseus nvidia-smi -L

Ele adiciona no .env:

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

AMD ROCm:

scripts/check-docker-amd-gpu.sh
# escreva o RENDER_GID que ele imprime no .env

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

Passo 8 (opcional): Habilitar Playwright MCP (proxy de navegador)

O Odysseus vem com alguns servidores MCP, mas o do navegador precisa primeiro baixar via npx:

npx -y @playwright/mcp@latest --version

Reinicie o container do Odysseus e, no Agent, já dá para usar MCP do navegador (capturas de tela, navegação, preenchimento de formulários):

Abra https://news.ycombinator.com, capture as 10 primeiras manchetes e links e resuma em 5 temas centrais.

Passo 9 (opcional): Rodar nativamente no Windows

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

O script cria automaticamente o venv → instala dependências → roda setup → inicia com uvicorn. Acesse http://localhost:7000.

Passo 10 (opcional): Deixar também acessível pelo celular

Com o Tailscale já conectado:

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# ou escrever no .env
APP_BIND=0.0.0.0

Mas expor HTTP puro para a LAN/Tailscale não é seguro; recomendo fortemente adicionar HTTPS via mkcert:

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem 100.x.y.z   # seu IP no Tailscale

python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

No celular, acesse https://<tailscale-ip>:7000 e instale o PWA na tela inicial; a experiência fica quase igual à do app nativo.

Solução de problemas comuns

Q1: Porta 7000 ocupada (comum no macOS)

No macOS, o AirPlay por padrão ocupa 7000. Duas soluções:

# Método 1: mudar a porta no .env
APP_PORT=7001
docker compose up -d
# Browser: abrir http://localhost:7001

# Método 2: Menu Apple → Configurações do Sistema → Geral → AirPlay Receiver → desligar

Q2: ChromaDB inicia, mas o log mostra DEGRADED

Normalmente é porque chromadb-client e chromadb foram instalados ao mesmo tempo: ele cai silenciosamente para modo só HTTP e perde a capacidade vetorial. Correção:

# Dentro do container em execução (ou no seu venv local)
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

Verificar: docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore" — deve mostrar inicialização bem-sucedida e sem mais DEGRADED.

Q3: Cookbook não vê minha GPU, só iGPU ou CPU

Por padrão, o Docker expõe todas as GPUs do host; mas se você só montar iGPU ou outra(s) placa(s), quase sempre é porque o NVIDIA Container Toolkit não está instalado/configurado, ou porque não rodou nvidia-ctk runtime configure --runtime=docker:

# Diagnóstico
scripts/check-docker-gpu.sh
# Veja a saída: ela vai dizer qual etapa está faltando

# Instalação + configuração (Ubuntu/Debian)
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4: GPU passthrough funciona, mas o log do llama.cpp diz Unable to find cudart

O dispositivo está ok; o que falta é o runtime do CUDA. Essa camada não é resolvida pelo Docker. Vá em Cookbook → Dependencies e reinstale a build CUDA do llama-cpp-python:

Abra Cookbook → Dependencies → encontre llama-cpp-python → Reinstall (build CUDA)

Ele mesmo faz pip install --no-cache-dir llama-cpp-python[cuda], em cerca de 2–3 minutos.

Q5: Outlook / Office 365 não conecta à caixa de e-mail

O módulo de e-mail do Odysseus hoje suporta apenas autenticação IMAP + usuário e senha. Depois de 2024, a Microsoft basicamente bloqueou senhas comuns; é preciso usar OAuth. Isso é uma limitação conhecida.

Solução temporária: usar Gmail/Fastmail/e-mail próprio, ou configurar um Microsoft App Password (conta com 2FA) para simular login por senha.

Q6: Quero acesso público; como deixar isso seguro?

Expor diretamente APP_BIND=0.0.0.0 para a internet = desastre. LOCALHOST_BYPASS contorna autenticação, e o Agent ainda tem ferramentas como shell — em 24 horas, o Shodan encontra uma pilha de instâncias abertas.

O jeito correto:

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik (encerramento HTTPS)
            → http://127.0.0.1:7000 (Odysseus, mantendo binding em localhost)

E no .env:

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7: Como controlar a conta da API na nuvem?

Vou detalhar o problema do caminho C no Passo 5.

Na prática, ao brincar sozinho, há três abordagens para ordenar por custo (do maior para o menor):

1. Conectar à API oficial — experiência mais completa, mas é a mais cara. Claude Opus + chamadas frequentes do Agent: passar de cem dólares na semana é normal
2. Conectar uma camada de proxy compatível com protocolo (eu uso Defapi) — mesmos modelos Claude/GPT/Gemini, e a conta mensal cai uma boa faixa em relação à oficial (quanto exatamente não calculei com precisão; mas basicamente: de conta semanal de ~100 para conta mensal de ~100, nessa ordem de grandeza). A vantagem é que a compatibilidade de protocolo é total; no Odysseus a configuração continua igual, sem mudar prompt/ código do Agent
3. Modelos quantizados locais — baixe no Cookbook um GGUF como Q4_K_M; com 16G de VRAM dá para rodar ~30B; custo zero de API, mas a inferência é mais lenta e a qualidade em tarefas complexas fica uma categoria abaixo

Minha combinação real: chat + Deep Research via Defapi Claude Sonnet 4.5, e Agent para chamadas de ferramentas via Claude Haiku 4.5 (barato); tarefas simples de classificação/resumo rodam em Qwen2.5 quantizado local. Cada Provider é cobrado separadamente, sem interferir entre si — no fim do mês, fica em dois dígitos de reais.

Leitura complementar / direções avançadas

• Ecossistema MCP: os pacotes MCP embutidos que o Odysseus registra automaticamente incluem playwright (navegador) / filesystem / shell. Você pode escrever seu próprio MCP server e registrar em mcp_servers/ para dar acesso ao Agent
• Sistema de Skills: routes/skills_routes.py gerencia “pedaços de skill” reutilizáveis, semelhante às Skills do OpenClaw — escreva uma vez e chame em qualquer sessão
• Tailscale + mkcert HTTPS: na seção anterior já mostrei o fluxo básico; avançando dá para adicionar renovação automática + desafio DNS-01
• Combinação com reverse proxy: Caddy com HTTPS + proxy do Cloudflare pode deixar o acesso público com zero manutenção
• Sincronização CalDAV: criar Radicale (um serviço leve CalDAV); o calendário do Odysseus sincroniza bidirecionalmente com o calendário do sistema no celular
• E-mail AI para “auto-bucket”: após conectar IMAP, depois de um tempo ele classifica automaticamente em “urgente / geral / lixo”, os rascunhos já ficam prontos, e você só precisa clicar em enviar
• Cookbook em servidor remoto: Cookbook → Settings → Servers permite configurar máquinas remotas com GPU; rodar inferência + baixar modelos via SSH — host pequeno, GPU longe, fica bem bonito
• Deep Research com relatórios em múltiplas etapas: adaptado do Tongyi DeepResearch da Alibaba, usa SearXNG para buscar múltiplas fontes → resumir → sintetizar, ideal para pesquisa de concorrentes e estudos do setor
• Roteamento com múltiplos Providers: no Odysseus, configure Providers diferentes para chat/Agent/Research — o Ollama local resolve 80% das conversas do dia a dia; problemas complexos vão para a nuvem, equilibrando custo e experiência

Repositório GitHub: pewdiepie-archdaemon/odysseus. A documentação fica em docs/, o roadmap em ROADMAP.md. Para contribuir, veja CONTRIBUTING.md.