Variáveis de ambiente

Toda a configuração do runner vem do ambiente e é validada por schema no boot, com fail-fast: se algo não bate, o processo morre com o erro legível em vez de subir meio configurado.

Invalid runner configuration:
  RUNNER_TUNNEL_URL: String must contain at least 1 character(s)

Por que o ambiente, e não um arquivo de config

O runner roda na infra do cliente, então o ambiente dele já é a configuração por tenant. Configuração específica de connector mora aqui, declarada no manifest, e não no client_config: aquele é parâmetro do control-plane, e connector nenhum o recebe.

Endpoints do control-plane

Variável	Default	Notas
RUNNER_TUNNEL_URL	nenhum	Obrigatória. Ex.: wss://tunnel.rootpilot.sh:8443.
RUNNER_ENROLL_URL	nenhum	Obrigatória, exceto com certificado provisionado. Ex.: https://app.rootpilot.sh.
RUNNER_ENROLL_PATH	/api/enroll	A rota de enrollment.

Identidade

Variável	Default	Notas
RUNNER_INSTANCE_ID	UUID sorteado a cada boot	Identifica a instância nos logs e no Fleet. Não tem relação com a persistência: o dono da identidade mora no próprio RUNNER_IDENTITY_DIR.
RUNNER_IDENTITY_DIR	nenhum	Diretório gravável onde a identidade é persistida, para sobreviver à substituição do container. Basta sozinha. Um por Agent — dois Agents no mesmo volume brigam por ele. Ver Identidade e enrollment.
RUNNER_ATTESTATION_MODE	bootstrap-token	bootstrap-token, aws-sts, gke-oidc. eks-oidc é aceito pelo schema e falha no boot.
RUNNER_BOOTSTRAP_TOKEN	nenhum	Obrigatória quando o modo é bootstrap-token.
AWS_REGION	nenhum	Obrigatória quando o modo é aws-sts. Também usada pelos connectors AWS.
RUNNER_GKE_TOKEN_PATH	/var/run/secrets/tokens/gke-oidc/token	Onde ler o token projetado da KSA.
RUNNER_CERT_PEM	nenhum	Certificado do seu tenant. PEM inline, não caminho — o entrypoint preenche a partir de /certs.
RUNNER_KEY_PEM	nenhum	Par do anterior. Os dois juntos pulam o enrollment.
RUNNER_CA_PEM	nenhum	Cadeia da CA, opcional.
RUNNER_CERT_RENEWAL	on	Liga o agendador de renovação. Exige RUNNER_ENROLL_URL; sem ela, nada renova.

Como a identidade nasce, e como ela sobrevive

São perguntas diferentes, e a segunda é a que decide se um deploy exige alguém no navegador.

Nasce de um destes: atestação de nuvem, bootstrap token (os dois via RUNNER_ENROLL_URL) ou certificado provisionado (RUNNER_CERT_PEM + RUNNER_KEY_PEM). Pelo menos um é obrigatório; sem nenhum, o boot falha. Havendo certificado provisionado, ele vence os outros — e o boot avisa por warn o que ficou de fora.

Sobrevive por renovação (dentro do processo) e por persistência (RUNNER_IDENTITY_DIR, através da troca de container). O certificado provisionado não renova: vence na data do notAfter e a troca é manual.

Detalhe em Identidade e enrollment.

Secret store

Onde as credenciais dos seus serviços são lidas. Detalhe em Secret stores.

Variável	Default	Notas
RUNNER_SECRET_STORE_MODE	env	env (desenvolvimento), aws, vault.
RUNNER_SECRETS_MANAGER_REGION	nenhum	Modo aws. Ausente ⇒ resolução default do SDK.
RUNNER_SECRETS_MANAGER_PREFIX	''	Modo aws. Prefixa o SecretId.
RUNNER_VAULT_ADDR	nenhum	Obrigatória no modo vault.
RUNNER_VAULT_AUTH	token	token ou approle.
RUNNER_VAULT_TOKEN	nenhum	Obrigatória com auth token.
RUNNER_VAULT_ROLE_ID	nenhum	Obrigatória com auth approle.
RUNNER_VAULT_SECRET_ID	nenhum	Obrigatória com auth approle.
RUNNER_VAULT_NAMESPACE	nenhum	Vault Enterprise.
RUNNER_VAULT_KV_MOUNT	secret	Mount do KV v2.
RUNNER_VAULT_KV_FIELD	value	Campo do secret a retornar.
RUNNER_VAULT_PREFIX	''	Prefixa o caminho lógico.

O schema valida as combinações e recusa cedo:

RUNNER_SECRET_STORE_MODE=vault requires RUNNER_VAULT_ADDR
vault auth requires RUNNER_VAULT_TOKEN (token) or RUNNER_VAULT_ROLE_ID+RUNNER_VAULT_SECRET_ID (approle)

Connectors

Variável	Default	Notas
RUNNER_CONNECTORS	synthetic	synthetic, real, demo. Ver Modos de connector.
RUNNER_OBSERVABILITY	datadog	datadog, grafana, none. Exclusivo. Ver Observabilidade.
RUNNER_CONNECTOR_MECHANISMS	native	CSV dos mecanismos de isolamento habilitados.
RUNNER_CONNECTOR_SIDECAR_TIMEOUT_MS	30000	Deadline de invoke do sidecar.
RUNNER_AWS_CRED_MODE	static	static ou chain. Ver Credenciais de nuvem.
RUNNER_GCP_CRED_MODE	static	static ou chain.
RUNNER_DENY_POLICY_FILE	—	Artefato JSON da denylist de tools.
RUNNER_DENIED_GROUPS	—	CSV de grupos negados (network-posture, iam).
RUNNER_DENIED_CAPABILITIES	—	CSV de capabilities negadas.
RUNNER_DENIED_CONNECTORS	—	CSV de connectors negados.
RUNNER_DENIED_OPS	—	CSV de operações negadas.

Mecanismo e fonte de dados são coisas ortogonais

RUNNER_CONNECTOR_MECHANISMS diz como o connector é isolado (native, sidecar, wasm). RUNNER_CONNECTORS diz de onde vêm os dados. Um não implica o outro.

Estado aprendido

Variável	Default	Notas
RUNNER_LEARNED_SYNC	on	off = estritamente local: o store nem é instanciado e nada sai do runner.
RUNNER_LEARNED_STORE_PATH	:memory:	Caminho do SQLite. É cache, não fonte de verdade.
RUNNER_LEARNED_FLUSH_INTERVAL_MS	60000	Flush periódico. 0 desliga e deixa só o flush do drain.
RUNNER_LEARNED_FLUSH_DEBOUNCE_MS	2000	Flush logo após uma extração, com debounce. 0 desliga.

Os dois prazos medem coisas diferentes. O periódico existe porque o único flush era no drain, então um reclaim duro (SIGKILL, OOM, spot) perdia tudo desde o boot — ele limita a perda. O debounce limita a latência: sem ele, uma aresta que o agente acabou de descobrir podia levar um intervalo inteiro para aparecer no control-plane. É debounce e não flush por operação porque uma wave dispara várias operações de uma vez, e um flush por operação viraria N chamadas para o mesmo resultado; o periódico segue valendo como teto, então sob extração contínua ele é quem garante o flush. Ele é watermark-safe: marca como sincronizado apenas o snapshot que de fato foi enviado, então re-flush após reconexão não dobra contagem.

Comportamento e tempos

Variável	Default	Notas
RUNNER_INVOKE_DEADLINE_MS	30000	Deadline por operação, aplicado no enforcement.
RUNNER_IDEMPOTENCY_TTL_MS	300000	TTL do cache de idempotência.
RUNNER_IDEMPOTENCY_MAX_ENTRIES	2000	Teto de entradas; despeja a mais antiga. Limita memória num runner longevo.
RUNNER_HEALTH_PROBE_TIMEOUT_MS	10000	Deadline por connector do self-check de credencial no boot.
RUNNER_RECONNECT_MAX_MS	30000	Teto do backoff de reconexão do túnel.
RUNNER_HEARTBEAT_INTERVAL_MS	15000	Cadência do ping de keepalive no túnel. Segura a conexão viva através de LB/proxy com idle timeout; dois intervalos sem resposta derrubam o socket para reconectar.
RUNNER_DRAIN_TIMEOUT_MS	120000	Teto do drain no SIGTERM. Dimensione a graça do orquestrador acima disso.
RUNNER_TLS_INSECURE_SKIP_VERIFY	false	Só teste. Ver aviso abaixo.
NODE_ENV	development	development, production, test.

O HEALTH_PROBE_TIMEOUT_MS é 10 s e não 5 s de propósito: vários runners no mesmo host disparando probes em paralelo, somados ao cold start, empurram uma chamada de ~2 s para além de 5 s e produzem um error falso.

RUNNER_TLS_INSECURE_SKIP_VERIFY

Desliga a verificação de identidade do servidor no TLS. O túnel continua validando o certificado do runner. Só o runner para de checar o do servidor. É uma escotilha de desenvolvimento para certificado expirado ou hostname divergente. Não a leve para produção.

Fora do schema do runner

Estas não são validadas pelo schema, mas mudam o comportamento:

Variável	Default	Onde age
ROOTPILOT_OTEL_ENABLED	false	Liga a telemetria OpenTelemetry. Ver Telemetria.
ROOTPILOT_PII_REDACTION	ligado	off desliga a camada estrutural de redação. Ver Redação de PII.
EKS_CLUSTER	nenhum	Sem ela o health check do EKS responde skipped: no cluster configured.
RUNNER_TENANT	nenhum	Dos scripts de frota, não do runner. Escolhe a pasta do cofre e liga RUNNER_CONNECTORS=real.

As credenciais de cada connector (DD_API_KEY, GITHUB_TOKEN, …) também não estão no schema do runner: elas são declaradas nos manifests e lidas do secret store. A lista completa está em Credenciais por connector.