---
url: https://developers.zarv.com/agent/enrollment.md
description: >-
  Registre o Zarv Agent uma única vez depois de instalar, para que ele se
  identifique e receba a configuração da Zarv.
---

# Registro

Depois de instalado, o agente precisa ser **registrado** uma vez para se
vincular ao seu workspace na Zarv. O registro troca o **token de acesso** do
workspace por uma identidade persistente do dispositivo.

## Passo a passo

1. **Copie o token de acesso** do workspace no painel da Zarv, na área de
   agentes. O token é o mesmo para todos os agentes do workspace e pode ser
   reutilizado.
2. **Abra a interface local** do agente em `http://localhost:8088`. No primeiro
   boot, ela exibe a tela de registro.
3. **Cole o token** e confirme. O agente troca o token por sua identidade,
   persiste localmente e passa a operar sob controle da Zarv.
4. Pronto — o dispositivo aparece como registrado no painel e começa a enviar
   heartbeats.

::: tip Token por variável de ambiente
Para provisionamento automatizado, o token também pode ser fornecida via
`ZARV_AGENT_ENROLLMENT_TOKEN` em `/etc/default/zarv-agent`. O agente o usa
no primeiro boot, quando ainda não tem identidade.
:::

## O que acontece nos bastidores

* O agente troca o token por uma identidade (`instance_id` + tokens) junto à
  Zarv e persiste essa identidade no banco local em `/var/lib/zarv-agent`.
* Em boots seguintes ele **não** repete o registro: usa a identidade já
  persistida para renovar suas credenciais automaticamente.
* O vínculo é por dispositivo; cada agente tem sua própria identidade.

## Estados após o registro

A interface local e o painel da Zarv refletem o estado do agente:

| Estado       | Significado                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `registered` | Identidade válida persistida.                                              |
| `online`     | Conectividade de saída OK (verificada por sondagem periódica).             |
| `paused`     | A Zarv suspendeu a coleta; o agente segue autenticado, sem enviar eventos. |
| `revoked`    | O acesso foi cancelado na Zarv — é necessário **re-registrar**.            |

## Re-registro após revogação

Se o dispositivo for **revogado** no painel da Zarv, o agente detecta a
revogação na próxima sincronização, para de enviar dados e passa a exibir um
aviso de "registro necessário" na interface local.

Para reativar:

1. Copie o token de acesso do workspace no painel (se ele foi trocado, use o
   novo).
2. Abra `http://localhost:8088` e cole o token (mesmo fluxo do primeiro
   registro).

O agente limpa o estado de revogação e volta a operar com a nova identidade (um novo `instance_id`).

## Próximos passos

* [Atualizações automáticas](/agent/updates)
* [Solução de problemas](/agent/troubleshooting)
