Visão geral

O rootpilot-edge é a metade aberta de um split runner / control-plane. Este repositório contém tudo que roda na sua infraestrutura: o runner, os connectors, a redação de PII e o contrato de comunicação. Nada aqui decide nada: ele coleta, normaliza, redige e responde.

As duas metades

Sua infra (este repositório)

Connectors read-only, coletores, caches, loaders e o runner. Guarda as credenciais, faz as chamadas, redige PII antes de qualquer byte sair. Apache-2.0.

Control-plane (fora deste repositório)

Correlação diagnóstica multi-fonte, agregação de aprendizado, thresholds de decisão. É o produto comercial fechado.

A direção de dependência é uma só: o control-plane consome os pacotes daqui, nunca o inverso. Se você for contribuir, a regra de bolso é essa: coleta, normalização e redação são edge; julgamento é control-plane.

Como o runner se conecta

O runner disca para fora. Não há porta de entrada, não há endpoint de health exposto, não há nada que precise ser aberto no seu firewall para entrada. Ele abre um túnel WSS reverso com mTLS até o control-plane e passa a servir chamadas por dentro dele.

Isso tem uma consequência operacional que vale registrar cedo: como o runner é cliente e não servidor, um probe de liveness HTTP não existe. A saúde dele se observa pelos logs de boot e pelo Fleet do control-plane.

O que o runner faz numa chamada

1. O control-plane pede uma operação do catálogo (por exemplo metrics.getServiceLatency).
2. O runner valida contra o enforcement point: a op existe no catálogo versionado? Os argumentos batem com o inputSchema em modo estrito? O deadline cabe?
3. O connector correspondente executa a chamada read-only contra a sua fonte, usando as credenciais lidas do seu secret manager.
4. O resultado passa pela redação na borda: campo declarado, estrutural e de conteúdo, nessa ordem.
5. O resultado redigido volta pelo túnel.

O control-plane pede o quê. O runner decide se pode. As duas perguntas moram em lados diferentes de propósito.

Terminologia: “Agent” é o produto, runner é o código

O componente que roda na sua infra chama-se RootPilot Agent no produto, na UI e na documentação voltada a você, porque é o termo familiar de observabilidade, como o Datadog Agent. No código, no protocolo, nas variáveis de ambiente e no SPIFFE id ele se chama runner, e vai continuar assim: renomear quebraria o contrato de wire e toda a superfície de variáveis RUNNER_* sem ganho nenhum.

Se você encontrar a palavra “agent” dentro do código deste repositório, ela quase sempre significa outra coisa: o LLM que consome as ferramentas. Não confunda os dois.

O que tem em cada pacote

Pacote	O que é
apps/runner	O container efêmero. Enrollment, túnel, enforcement, redação, drain.
packages/connectors	Os 15 clientes read-only das fontes externas.
packages/core-edge	Utilitários de borda: cache, erros, redator de PII, catalog loader.
packages/protocol	O contrato versionado runner↔control-plane.
packages/connector-sdk	SDK aberto para escrever os seus próprios connectors.
packages/otel	Telemetria OpenTelemetry compartilhada.
packages/demo	Ambiente fictício completo, sem credencial nenhuma.

Cattle, não pet

O runner não tem estado durável. As credenciais vivem só em memória, o SQLite local é cache e o default é :memory:. Ele foi feito para morrer: spot reclaim, OOM, docker compose down. Sobe outro e o sistema segue. Não faça backup dele, não o trate como servidor nomeado, não guarde nada dentro dele que você precise de volta.