Visão geral

O RootPilot é um split runner / control-plane. O edge é a metade que roda na sua infraestrutura: o Agent, os connectors, a redação de PII e o contrato de comunicação. Nada dele decide nada — ele coleta, normaliza, redige e responde.

As duas metades

A direção é uma só: o control-plane pede, o Agent decide se pode e responde. A regra que separa os dois lados: coleta, normalização e redação acontecem na sua infra; julgamento acontece do outro lado, e só sobre dados já redigidos.

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

O control-plane pede uma operação do catálogo (por exemplo metrics.getServiceLatency).
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?
O connector correspondente executa a chamada read-only contra a sua fonte, usando as credenciais lidas do seu secret manager.
O resultado passa pela redação na borda: campo declarado, estrutural e de conteúdo, nessa ordem.
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.