Visão geral

O WhyStack é 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 pela Frota 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 WhyStack 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.

WhyStack é o novo nome do RootPilot

O produto mudou de nome, e esta documentação já usa o nome novo em tudo o que ela mesma escolhe. Três grupos de identificador seguem com rootpilot, porque trocá-los só no texto quebraria o comando:

O que a imagem e o protocolo definem: as imagens (rootpilot-agent, rootpilot-profiler), o rootpilot-health, as variáveis ROOTPILOT_*, os nomes da base Kubernetes, as métricas rootpilot.* e o SPIFFE id spiffe://rootpilot/tenant/<slug>/runner. Mudam junto com os serviços.
Os domínios: app.rootpilot.sh, tunnel.rootpilot.sh e este docs.rootpilot.sh. A documentação troca quando o domínio novo estiver no ar.
O que a sua instalação já criou: o volume rootpilot-identity e o serviço rootpilot-agent do Compose, e o perfil AppArmor rootpilot-profiler. Renomear o volume num up -d custaria a identidade do Agent e um bootstrap token novo.

Os nomes que os guias sugerem para uma instalação nova já são whystack: a policy IAM, o prefixo dos secrets, a role do Vault, a conta do Argo CD, a entrada no cliente MCP. Se a sua instalação usa os nomes antigos, mantenha-os. Nenhum componente do WhyStack os lê: eles só ligam peças que você mesmo configurou.

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 das fontes externas: leitura, fora as seis escritas de ticket, chat e issue.
`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.