---
url: https://developers.zarv.com/edge-agent/updates.md
---
# Atualizações automáticas

Depois de registrado, o Zarv Agent se mantém atualizado por conta própria, sob
controle da Zarv. Você **não** precisa entrar no dispositivo para atualizá-lo.

## Como funciona

* O agente consulta periodicamente sua configuração na Zarv e compara a versão
  desejada com a que está rodando.
* Quando há uma versão mais nova e a atualização está habilitada, o agente a
  aplica pelo mesmo canal da instalação (APT, RPM ou Docker) e reinicia no novo
  binário.
* A versão é validada (SemVer) antes de ser aplicada, e o estado da atualização
  é reportado nos heartbeats.

Nada disso exige ação no dispositivo: a versão da frota é definida na Zarv e os
agentes convergem sozinhos.

## Janela de manutenção

Por padrão, uma atualização é aplicada assim que fica disponível. Para que ela
seja aplicada **apenas em um horário tranquilo** (por exemplo, das 03:00 às
04:00), configure uma janela de manutenção.

No painel da Zarv, no edge-server (seção **Atualização automática**), defina:

* **Janela** — no formato `HH:MM-HH:MM` (24h). Vazio = aplicar imediatamente.
  Janelas que cruzam a meia-noite (ex.: `23:00-01:00`) são suportadas.
* **Fuso horário** — um nome IANA (ex.: `America/Sao_Paulo`). Vazio = hora local
  do dispositivo.

Fora da janela, o agente reporta o estado `waiting_window` e só aplica a
atualização quando a janela abrir.

::: tip Espalhamento automático da frota
Cada dispositivo escolhe um deslocamento determinístico dentro da janela
(derivado do seu hostname). Assim, uma frota inteira na mesma janela distribui
as atualizações ao longo do período em vez de baixar tudo ao mesmo tempo. O
deslocamento é estável entre reinícios, então um dispositivo nunca perde sua
vez.
:::

### Configuração local (alternativa)

A janela também pode ser definida por variáveis de ambiente em
`/etc/default/zarv-agent`:

| Variável                     | Exemplo             | Descrição                                                   |
| ---------------------------- | ------------------- | ----------------------------------------------------------- |
| `EDGE_AGENT_UPDATE_WINDOW`   | `03:00-04:00`       | Janela em que atualizações são aplicadas. Vazio = imediato. |
| `EDGE_AGENT_UPDATE_TIMEZONE` | `America/Sao_Paulo` | Fuso IANA. Vazio = hora local do dispositivo.               |

A configuração definida na Zarv tem precedência sobre as variáveis locais quando
ambas estão definidas.

::: warning Primeira atualização
A janela só governa atualizações de agentes que já a tenham configurada. Um
agente recém-instalado, sem janela definida, aplica a próxima atualização
imediatamente — a partir daí a janela passa a valer para as seguintes.
:::

## Acompanhamento

O estado da atualização aparece no painel da Zarv e na interface local:

* versão em execução;
* estado da atualização: `idle`, `waiting_window`, `applying`, `error`;
* última falha, quando houver.

Para uma implantação gradual, defina a nova versão primeiro em um dispositivo
canário, acompanhe o estado, e então amplie para o restante da frota.