Instalar o agente em uma frota

Instalar o agente em uma máquina é fácil e está no README do repositório do cliente. Este guia é sobre a frota: dezenas ou centenas de máquinas, sem visitar nenhuma.

Antes de instalar a primeira: decida a retenção

Configurações → Dados, ou as variáveis MANAGER_TELEMETRY_RETENTION_DAYS e MANAGER_HEARTBEATS_RETENTION_DAYS.

Não é ordem arbitrária. Cada amostra de telemetria custa cerca de 11 kB, e na cadência padrão de 60 segundos são ~15 MB por endpoint por dia. Com 500 máquinas isso dá ~227 GB por mês sem poda.

Endpoints	Retenção de 7 dias	30 dias	90 dias
50	5,4 GB	23 GB	70 GB
500	53 GB	227 GB	682 GB

0 desliga a poda. A poda remove o que passou da janela — ela não recupera o que você acumulou sem janela configurada, e é por isso que este passo vem primeiro.

Se a sua operação não precisa detectar máquina caída em um minuto, subir AGENT_HEARTBEAT_INTERVAL_SECONDS para 300 corta o volume em cinco vezes. É o ajuste de maior efeito.

1. Confirme o endereço que as máquinas vão usar

AGENT_PUBLIC_API_BASE_URL=https://openscale.suaempresa.com.br

Vazia, o produto deriva o endereço do cabeçalho Host da requisição — funciona em teste local e falha atrás de proxy que não repassa o host original. O sintoma é traiçoeiro: a máquina registra com sucesso e depois tenta se conectar a um endereço que não existe.

As máquinas precisam alcançar, por HTTPS de saída:

Destino	Para quê
O endereço acima	Sinal de vida, busca de trabalho, telemetria
O armazenamento de objetos	Envio de evidência por URL assinada

Nada precisa alcançar a estação. Ver Portas e exposição.

2. Gere um token de lote

Manutenção → Gerência de ativos, ou pela API:

curl -sS -X POST https://openscale.suaempresa.com.br/manager-api/agent-control/enrollment-tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Lote sede - agosto","max_uses":80,"expires_at":"2026-09-15T00:00:00.000Z"}'

O $TOKEN vem de /auth/api-token, e a conta precisa de ativos.computadores em nível de editar.

A resposta traz o token com prefixo ose_enroll_, exibido uma única vez.

Três escolhas que valem pensar:

max_uses com folga, não exato. Instalação falha, máquina é reinstalada. Um token de 80 usos para 60 máquinas evita gerar outro no meio do rollout.
expires_at curto. Uma janela de duas semanas para um rollout de duas semanas. Token de lote com validade de um ano é credencial permanente esperando vazar.
Um token por lote, com label que diga qual. Assim é possível revogar um lote sem derrubar os outros.

3. Distribua por política de grupo

O instalador aceita o servidor e o token como parâmetro, o que permite instalação silenciosa:

msiexec /i \\servidor\deploy\openscale-client.msi /qn `
  SERVERURL="https://openscale.suaempresa.com.br" `
  ENROLLTOKEN="ose_enroll_…"

Os nomes exatos das propriedades acompanham a versão do instalador — confira no README do repositório do cliente.

4. Comece por um lote pequeno

Cinco máquinas, de modelos diferentes se possível. Em Manutenção confirme que cada uma:

aparece na lista, com estado online
reporta CPU, memória e disco
reporta inventário — programas instalados e serviços; se ficar vazio, o primeiro ciclo de inventário não saiu
aceita um comando inofensivo, como abrir o terminal

Só depois libere o resto. Um problema de rede ou de política descoberto em 5 máquinas é ajuste; descoberto em 300, é um fim de semana.

5. Confira o custo real depois de uma semana

Com a frota rodando, meça em vez de confiar na estimativa:

SELECT pg_size_pretty(pg_total_relation_size('manager_endpoint_telemetry')) AS total,
       COUNT(*) AS linhas,
       COUNT(DISTINCT (agent_row_id, collected_at)) AS amostras_distintas
FROM manager_endpoint_telemetry;

Se linhas for muito maior que amostras_distintas, há reenvio — a mesma coleta gravada mais de uma vez. Nesse caso o disco cresce sem que a operação tenha mais informação, e comprar disco resolve o sintoma e não a causa. Vale abrir a questão antes de aumentar o volume.

Permissões da equipe que vai operar a frota

Três chaves independentes, e a separação é o ponto:

Chave	Concede
`manutencao` + `manutencao:<setor>`	Ver as máquinas daquele setor
`manutencao.remoto`	Entrar na máquina: sessão remota, terminal, arquivos
`manutencao.software`	Alterá-la: instalar e remover software, scripts

Nenhuma herda da outra. Dar visibilidade da frota ao suporte de primeiro nível sem dar acesso remoto é a combinação mais pedida — e é possível justamente porque as chaves são separadas. Ver Permissões e papéis.