---
url: https://developers.zarv.com/agent/configuration.md
description: >-
  Parâmetros locais de infraestrutura do Zarv Agent: onde ficam, quais variáveis
  existem e o que é gerenciado centralmente pela Zarv.
---

# Configuração

A maior parte da configuração operacional do agente (câmeras, tuning de
inferência, política de atualização) é gerenciada **centralmente pela Zarv** —
você não precisa mexer no dispositivo. O arquivo local serve apenas para
parâmetros de infraestrutura e para apontar/provisionar o agente.

## Onde fica

Variáveis de ambiente do serviço ficam em **`/etc/default/zarv-agent`** (um
conffile: suas edições sobrevivem a upgrades). O agente também lê
`<DataDir>/config.env`, escrito pela própria interface de Configurações; valores
ali têm precedência sobre o arquivo de defaults.

::: tip Nomes antigos (`EDGE_AGENT_*`)
Em versões anteriores todas as variáveis começavam com `EDGE_AGENT_`. Os nomes
antigos continuam funcionando por mais uma versão, tanto no ambiente quanto no
`config.env`; a interface de Configurações regrava o arquivo com os nomes novos
na próxima vez que você salvar. Atualize seus arquivos e automações para
`ZARV_AGENT_*`.
:::

Após editar, reinicie o serviço:

```sh
sudo systemctl restart zarv-agent
```

## Destino do tráfego

Toda a saída do agente — registro, configuração, heartbeat, eventos, telemetria
e atualizações (OTA) — vai para um **único host**:

`collector.zarv.com`.

| Variável           | Padrão  | Descrição                                           |
| ------------------ | ------- | --------------------------------------------------- |
| `ZARV_AGENT_DEBUG` | `false` | Uso interno da Zarv. Mantenha `false` (ou ausente). |

::: tip
Não é preciso configurar URLs de upstream manualmente: o agente já envia tudo
para `collector.zarv.com`.
:::

## Variáveis de infraestrutura

| Variável                                | Padrão                            | Descrição                                                                                                                                                                                                             |
| --------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ZARV_AGENT_DATA_DIR`                   | `/var/lib/zarv-agent`             | Diretório de estado: banco SQLite, blobs, `config.env`.                                                                                                                                                               |
| `ZARV_AGENT_HTTP_LISTEN`                | `0.0.0.0:8088`                    | Endereço da interface local de gerenciamento. Use `127.0.0.1:8088` para restringir ao host.                                                                                                                           |
| `ZARV_AGENT_MODELS_DIR`                 | `/opt/zarv/models`                | Diretório dos modelos ONNX (embutidos no pacote).                                                                                                                                                                     |
| `ZARV_AGENT_LOG_LEVEL`                  | `info`                            | Nível de log: `debug`, `info`, `warn`, `error`.                                                                                                                                                                       |
| `ZARV_AGENT_LOG_FORMAT`                 | `json`                            | Formato de log: `json` ou `text`.                                                                                                                                                                                     |
| `ZARV_AGENT_HEARTBEAT_INTERVAL_SECONDS` | `60`                              | Cadência do heartbeat para a Zarv.                                                                                                                                                                                    |
| `ZARV_AGENT_PING_TARGETS`               | `1.1.1.1,1.0.0.1,8.8.8.8,8.8.4.4` | Servidores usados para saber se o link está de pé (ping, com TCP 443 de reserva) e para medir o tempo de resposta de DNS exibido na interface. Lista separada por vírgulas; só endereços IP entram na medição de DNS. |
| `ZARV_AGENT_SPEEDTEST_TIME`             | `04:00`                           | Horário local (HH:MM, 24 horas) do teste de velocidade diário. O agente também mede uma vez ao iniciar.                                                                                                               |
| `ZARV_AGENT_FRAME_WIDTH_METERS`         | `10`                              | Largura real, em metros, do campo de visão da câmera na profundidade alvo. Define a conversão para km/h na linha do tempo e nos eventos.                                                                              |
| `ZARV_AGENT_PPROF_LISTEN`               | *(desativado)*                    | Endereço do endpoint de profiling (por exemplo `127.0.0.1:6060`). Vazio desativa. Restringir ao localhost é responsabilidade de quem opera.                                                                           |

## Provisionamento e atualização

| Variável                      | Exemplo             | Descrição                                                                                                   |
| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `ZARV_AGENT_ENROLLMENT_TOKEN` | *(chave)*           | Token de acesso do workspace para registro automático no primeiro boot. Veja [Registro](/agent/enrollment). |
| `ZARV_AGENT_UPDATE_WINDOW`    | `03:00-04:00`       | Janela de manutenção para aplicar atualizações. Veja [Atualizações](/agent/updates).                        |
| `ZARV_AGENT_UPDATE_TIMEZONE`  | `America/Sao_Paulo` | Fuso (IANA) da janela. Vazio = hora local do dispositivo.                                                   |

::: warning
Parâmetros de inferência, tuning e throttling não devem ser definidos
localmente: eles são geridos pela Zarv para preservar qualidade de detecção e
volume de eventos. A interface local de Configurações expõe apenas os ajustes
de infraestrutura acima.
:::

## Exemplo de `/etc/default/zarv-agent`

```sh
# Estado persistente.
ZARV_AGENT_DATA_DIR=/var/lib/zarv-agent

# Interface de gerenciamento (restrita ao host).
ZARV_AGENT_HTTP_LISTEN=127.0.0.1:8088

# Teste de velocidade diário às 4h (horário local do dispositivo).
ZARV_AGENT_SPEEDTEST_TIME=04:00

# Janela de manutenção para atualizações (madrugada, horário de São Paulo).
ZARV_AGENT_UPDATE_WINDOW=03:00-04:00
ZARV_AGENT_UPDATE_TIMEZONE=America/Sao_Paulo
```
