Deploy em produção

O RootPilot Agent é distribuído como imagem de container. Ele roda dentro da sua infraestrutura, lê as suas credenciais do seu secret manager e abre uma única conexão, de saída, até o control-plane.

Antes de começar, faça o Quickstart: ele valida imagem, certificado e túnel sem envolver nenhuma credencial sua. Se algo estiver errado na canalização, é bem mais barato descobrir lá.

O que o RootPilot te entrega

Item	O quê
Endereço da imagem	No ECR ou no Artifact Registry, com a sua conta/projeto autorizado a puxar.
Um caminho de identidade	Onde a sua plataforma prova identidade sozinha (GKE, EC2/EKS), nada — você configura a atestação. Senão, um bootstrap token que você minta em Onboarding. O certificado emitido por nós (runner.crt · runner.key · ca.pem) é a ponte para o resto.
RUNNER_TUNNEL_URL	O endereço do túnel.

Não há credencial do RootPilot para você guardar ou rotacionar: o pull usa a identidade da sua própria nuvem.

1. A imagem

# AWS (ECR)
docker pull <conta-rootpilot>.dkr.ecr.<região>.amazonaws.com/rootpilot-agent:<versão>

# GCP (Artifact Registry)
docker pull <região>-docker.pkg.dev/<projeto-rootpilot>/rootpilot/rootpilot-agent:<versão>

Multi-arquitetura: o mesmo endereço serve amd64 e arm64 (Graviton, Tau, Axion).

O registry é privado: autentique com as suas credenciais antes do pull, e garanta que a identidade que o orquestrador usa também esteja autorizada — ver A imagem › Autenticar antes do pull.

Fixe por digest em produção

O Agent é efêmero e puxa a imagem com frequência. Uma tag móvel faz réplicas diferentes rodarem builds diferentes sem aviso. Use ...rootpilot-agent@sha256:<digest>.

O container roda como usuário não-root (uid 1000). Não pede privilégio, capability extra nem acesso ao socket do Docker.

2. Identidade

O Agent se autentica por mTLS, e o certificado tem vida curta — 15 minutos, renovados sozinhos. A escolha aqui é de onde vem a primeira identidade, e ela decide se um deploy exige alguém no navegador. O assunto inteiro está em Identidade e enrollment; em produção, o resumo é:

Se a sua plataforma prova identidade (GKE, ou qualquer lugar com credencial AWS — EC2, EKS), use atestação de nuvem. É a melhor opção porque não há segredo para mintar, entregar ou girar:

RUNNER_ENROLL_URL=https://app.rootpilot.sh
RUNNER_ATTESTATION_MODE=gke-oidc     # ou aws-sts

Senão (VPS, host próprio), use bootstrap token — e persista a identidade, senão cada troca de container custa um token novo, mintado à mão:

RUNNER_ENROLL_URL=https://app.rootpilot.sh
RUNNER_ATTESTATION_MODE=bootstrap-token
RUNNER_BOOTSTRAP_TOKEN=<mintado em Onboarding>
RUNNER_IDENTITY_DIR=/identity         # volume gravável pelo uid 1000
RUNNER_INSTANCE_ID=agent-prod-1       # opcional: identifica a instância nos logs e no Fleet

Se o RootPilot lhe entregou um certificado, monte os três PEMs em /certs, somente leitura — o entrypoint os carrega sozinho:

/certs/runner.crt
/certs/runner.key
/certs/ca.pem

Se o seu orquestrador injeta segredo como variável e não como arquivo, passe o conteúdo inline em RUNNER_CERT_PEM, RUNNER_KEY_PEM e RUNNER_CA_PEM. É equivalente. Esse certificado não se renova: anote o notAfter do log de boot no calendário.

O certificado provisionado desliga os outros caminhos, calado

Com RUNNER_CERT_PEM e RUNNER_KEY_PEM presentes, o Agent os usa e ignora atestação e identidade persistida sem dizer que ignorou. Ao migrar para enrollment, remova o volume /certs — senão nada muda e não fica claro por quê.

Hostname certo ≠ porta aberta

O certificado do túnel tem SAN DNS:tunnel.rootpilot.sh. Conectar por outro hostname, mesmo que resolva para o mesmo IP, falha a verificação de hostname do TLS com is not in the cert's altnames. Quem manda é o SAN do certificado.

3. Segredos

O Agent lê as credenciais dos seus serviços do seu secret manager, no boot, e as mantém apenas em memória. Escolha o backend:

RUNNER_SECRET_STORE_MODE=aws      # AWS Secrets Manager
RUNNER_SECRET_STORE_MODE=vault    # HashiCorp Vault KV v2

Detalhes de cada um em Secret stores; quais chaves cada serviço pede, em Credenciais por connector.

Se o Agent roda na mesma conta que você quer observar, prefira a identidade do próprio workload a uma chave estática — RUNNER_AWS_CRED_MODE=chain ou RUNNER_GCP_CRED_MODE=chain. Veja Credenciais de nuvem.

4. Configuração

O mínimo:

RUNNER_TUNNEL_URL=wss://tunnel.rootpilot.sh:8443
RUNNER_CONNECTORS=real
RUNNER_SECRET_STORE_MODE=aws
NODE_ENV=production

RUNNER_CONNECTORS=real não é o default

A imagem vem com synthetic. Sem essa linha o Agent sobe, conecta e funciona — servindo dados fabricados. É a falha mais silenciosa da instalação, e a mais cara, porque parece ter dado certo.

A referência completa está em Variáveis de ambiente. Para Kubernetes, veja Kubernetes — em especial a parte de probes, que tem uma pegadinha.

5. Confirmar

Os logs saem em JSON, uma linha por evento. A que importa é a última:

{"level":"info","message":"hello accepted","context":"runner","sessionId":"..."}

A partir dela o Agent aparece no Fleet do control-plane, com o estado de cada serviço conectado: se a credencial existe e se ela funciona. Uma chave inválida ou sem permissão aparece ali como erro, com a causa.

Não existe endpoint HTTP de health — o Agent é cliente de saída e não escuta em porta nenhuma.

Rotação do certificado

O certificado tem data de validade e não se renova sozinho. Quando ele vence, o Agent para de conectar e a frota inteira para de responder.

O notAfter sai no log a cada boot, e é o seu aviso prévio:

{"level":"info","message":"using provisioned cert","context":"runner","notAfter":"2027-08-10T00:00:00.000Z"}

Trate a troca como manutenção planejada: o RootPilot emite o par novo, você substitui o conteúdo montado em /certs e recicla as réplicas. Não há perda de dado — o Agent não guarda estado durável.

Supervisão

Garanta que o seu supervisor (ReplicaSet, serviço de ECS, restart do Compose) suba um substituto quando o processo sair. O Agent é descartável por construção: ao receber SIGTERM ele para de aceitar trabalho novo, termina o que está em andamento e encerra, dentro de RUNNER_DRAIN_TIMEOUT_MS — 2 minutos por padrão. Dê ao orquestrador um timeout de parada maior que esse, senão o SIGKILL chega no meio da drenagem.

Como o Agent é cliente de saída e não tem endpoint de health, um processo que ficasse de pé sem servir seria invisível a qualquer probe. Por isso ele prefere sair a degradar em silêncio — e conta com o supervisor para trazer um substituto limpo.