Heimdall-ai

Arquitetura

Mapa

Mapa do Heimdall-aiNa linha de cima, a conversa: você usa o Open WebUI, que fala com o LiteLLM, que usa os modelos do Ollama, os servidores MCP e as bases de documentos e de busca. Na linha de baixo, as automações: o n8n usa o LiteLLM, aciona o agente do Mac, que grava nos aplicativos do Mac, e avisa no iPhone pelo Bark.ConversaVocênavegador ou iPhoneOpen WebUIinterface do chatLiteLLMacesso único, porta 9000Ollama6 modelos no MacServidores MCPportas 8000 e 8001Qdrant e SearXNGdocumentos e buscaAutomaçãon8nfluxos, porta 5678Agente do Macponte local, porta 8003Notas, Calendárioe Lembretes do macOSBarkavisos no iPhone
  • Interface
  • Acesso único
  • Modelos
  • Ferramentas e dados
  • Automação
As setas mostram quem chama quem. A descrição completa está em texto logo abaixo.

Visão geral

O Heimdall-ai tem quatro camadas, da base para o topo.

  1. Modelos. O Ollama executa os modelos de linguagem no Mac (chip Apple, 16 GB de memória).
  2. Acesso único. O LiteLLM Proxy (porta 9000) expõe todos os modelos em uma API compatível com a da OpenAI e repassa os servidores MCP. Clientes como o Open WebUI e aplicativos de iPhone falam só com ele.
  3. Ferramentas. Dois servidores MCP em Python (portas 8000 e 8001) e o servidor de documentação da AWS dão ao modelo ferramentas: busca na web, leitura de páginas, arquivos, memória, documentos pessoais.
  4. Automações. O n8n agenda fluxos que usam os modelos e as ferramentas. O agente do Mac (porta 8003) liga o n8n, que roda em Docker, aos aplicativos do macOS. O Bark entrega os avisos no iPhone.

O caminho de uma pergunta no chat

  1. A pessoa escreve no Open WebUI (pelo navegador ou pelo celular, pela rede privada Tailscale).
  2. O Open WebUI envia ao LiteLLM, que encaminha ao Ollama o modelo escolhido.
  3. Se o modelo decide usar uma ferramenta, devolve uma chamada estruturada; o LiteLLM a executa no servidor MCP correspondente e devolve o resultado ao modelo.
  4. O modelo escreve a resposta final com o que a ferramenta trouxe.

O caminho de uma automação

  1. O n8n dispara um fluxo no horário (ou por um evento, como um git push).
  2. O fluxo busca dados (feeds, SearXNG, Qdrant, notas) e pede análises ao modelo pelo LiteLLM.
  3. O resultado vai para o app Notas, o Calendário ou os Lembretes, pelo agente do Mac, e um resumo chega ao iPhone pelo Bark.
  4. Se qualquer etapa falha, o fluxo de aviso de falha notifica; nenhuma automação falha em silêncio.

Serviços e portas

Serviços do Heimdall-ai
ServiçoFunçãoPortaComo sobe
OllamaExecuta os modelos de linguagem no Mac.11434start_heimdall.sh (inicia se não estiver rodando)
LiteLLM ProxyPonto único de acesso (API compatível com a da OpenAI) aos modelos; também expõe os servidores MCP.9000start_heimdall.sh
Servidor MCP do Mac (admin)Ferramentas que mexem no Mac: arquivos, métricas, memória e documentos.8000start_heimdall.sh
Servidor MCP públicoFerramentas seguras para convidados: web, cálculo, feeds, transcrições.8001start_heimdall.sh
SearXNGMecanismo de busca na web que não rastreia quem pesquisa.8080start_heimdall.sh (Docker)
QdrantBase vetorial: busca por significado nos documentos e nas notas.6333start_heimdall.sh (Docker)
Open WebUIInterface de chat usada pelos convidados e pelo dono.3000--webui ou HEIMDALL_WEBUI=1
Open TerminalTerminal acessível pelo Open WebUI.8002--terminal
n8nAutomações e tarefas agendadas.5678--n8n ou HEIMDALL_N8N=1
Agente do MacPonte entre o n8n (no Docker) e o app Notas, o Calendário, os Lembretes e a voz do macOS.8003--agente (sobe sozinho com HEIMDALL_AGENTE_TOKEN)
DoclingExtração de texto de PDFs, com OCR.5001--docling ou HEIMDALL_DOCLING=1
Uptime KumaPainel de disponibilidade dos serviços.3001start_heimdall.sh (HEIMDALL_MONITORING=0 desliga)
DozzleLeitor de logs dos contêineres.8081start_heimdall.sh (HEIMDALL_MONITORING=0 desliga)
Emulador de AWS (Moto ou LocalStack)Para testar código de AWS sem custo.4566start_heimdall.sh (HEIMDALL_AWS_EMULATOR)

Os serviços de Docker escutam só no próprio computador. O acesso de fora passa pela rede privada Tailscale ou por túnel da Cloudflare com autenticação.

Princípios de privacidade e segurança

  • Dados pessoais ficam no Mac. Chaves e identificadores ficam no arquivo .env, com permissão restrita, e nunca no repositório.
  • Pastas privadas são intocáveis. Notas de pastas marcadas como privadas nunca são lidas, indexadas nem analisadas. Se a verificação falhar, nenhuma nota é entregue.
  • O agente só escreve onde deve. Grava apenas nas pastas do próprio Heimdall e nas pastas de temas de estudo.
  • Autenticidade antes de confiança. O vigia de e-mail só trata como oficial o remetente que o Gmail confirmou, e nunca segue links.
  • Sem falha silenciosa. Quando uma fonte não responde, o aviso diz isso e nunca finge que não há novidade.
  • Entradas externas são dados, não ordens. Textos de páginas, e-mails e documentos passados ao modelo são tratados como conteúdo não confiável.