Agente local: instalação

Do README do agente (Zoppy-crm/zoppy-connect-agent@c7f6ec9495ee). Os comandos e as opções completas estão em Comandos do agente.

Guia de implantação assistida e de suporte para o time da Zoppy (Enablement implanta na V1; o CS encaminha os casos). O texto fala com quem está na máquina da loja, para poder ser lido junto com o lojista na chamada.

O Zoppy Agent é um programa pequeno que você instala numa máquina dentro da rede da loja. Ele deixa a Zoppy ler, só nos sistemas que você liberar, dados do ERP (API interna do TOTVS Protheus, Sankhya e afins, ou leitura direta do banco SQL Server, Oracle, Firebird, MySQL ou Postgres) sem abrir nenhuma porta para a internet e sem VPN.

Roteiro da implantação assistida

Antes da chamada: confirme com a loja a máquina (sempre ligada, enxerga o ERP), o motor e o nome do banco do ERP, e quem tem senha de administrador do banco para criar o usuário só leitura.
Usuário só leitura: o DBA da loja cria o usuário com os comandos de Usuário só leitura.
Código: um MASTER ou ADMIN da loja gera o código na tela (Conectores › Agente local › Instalar).
Instalação e pareamento: Windows, Linux ou Docker. Em staging, pareie com zoppy-agent pair --staging <código>.
Lista local: libere só o banco/API que o conector vai ler (Lista local) e teste com zoppy-agent allow check.
Conferência: zoppy-agent status mostra conectado, e o agente aparece como conectado na tela.
Conector: no chat do conector, o usuário e a senha do banco são informados como segredos do conector (nunca ficam no agente).

Se algo der errado, vá para Diagnóstico.

  Internet                         │  Rede da loja (atrás do firewall)
                                   │
  ┌──────────┐   conexão de SAÍDA  │   ┌─────────────┐      ┌──────────────────┐
  │  Zoppy   │ ◄═══════════════════╪═══│ Zoppy Agent │ ───► │ Protheus (REST)  │
  │ Connect  │   443, cifrada      │   │             │ ───► │ SQL Server (ERP) │
  └──────────┘                     │   └─────────────┘      └──────────────────┘
                                   │     lista local: só o que você liberou

O agente abre uma conexão de saída (HTTPS/WebSocket na porta 443) até a Zoppy e a mantém aberta.
A Zoppy manda os pedidos por essa conexão; o agente executa dentro da rede e devolve a resposta.
Antes de qualquer acesso, o agente confere a lista local. O que não estiver nela é recusado pelo próprio agente, mesmo que o pedido venha da Zoppy. A lista fica só nesta máquina: a Zoppy não consegue mudá-la.

Antes de instalar

Onde instalar: numa máquina sempre ligada que enxerga o ERP (o próprio servidor do ERP ou do banco serve bem). Notebook não. Se a máquina desligar, os conectores dela param, os administradores são avisados e a próxima execução traz o que faltou.
Sistemas: Windows Server 2016 ou mais novo / Windows 10 ou mais novo (64 bits), Linux 64 bits (x86_64 ou ARM64) com systemd, ou qualquer máquina com Docker. Mac não é suportado.
Rede: saída para agent-connect.zoppy.com.br (a conexão com a Zoppy) e downloads-agent-connect.zoppy.com.br (as atualizações) na porta 443. Nenhuma porta de entrada. Se a sua rede usa proxy, veja Proxy.
Banco de dados: crie um usuário só de leitura para a Zoppy (exemplos em Usuário só leitura). É pré-requisito: o agente também bloqueia escrita por conta própria, mas a primeira proteção é o usuário não ter permissão.
Código de pareamento: na tela da Zoppy, em Conectores › Agente local › Instalar, um MASTER ou ADMIN clica em Gerar código (vale 30 minutos e uma vez só; tentativas erradas demais do mesmo IP são bloqueadas por um tempo).
Ambiente: o padrão é produção (agent-connect.zoppy.com.br). Para o staging, pareie com --staging (agent-connect-staging.zoppy.com.br).

Instalação

Windows (.msi)

Baixe o zoppy-agent.msi pela tela da Zoppy (ou em https://downloads-agent-connect.zoppy.com.br/agent/stable/zoppy-agent.msi) e execute como administrador. O instalador não tem assinatura de código: se o Windows SmartScreen avisar, clique em Mais informações › Executar assim mesmo. Ele instala o serviço Zoppy Agent (início automático) em C:\Program Files\Zoppy Agent.
Abra o Prompt de Comando como administrador e pareie:
Janela do terminal
```
zoppy-agent pair K7QD-92XM
```
Instalação silenciosa já pareando (para quem distribui por GPO/SCCM):
Janela do terminal
```
msiexec /i zoppy-agent.msi /qn PAIRCODE=K7QD-92XM
```
Libere o que o agente pode alcançar (veja Lista local).

Arquivos no Windows: configuração em C:\ProgramData\ZoppyAgent\config.yaml; credencial e logs em C:\ProgramData\ZoppyAgent\data (só SYSTEM, Administradores e a conta do serviço leem). Se essas pastas já existiam com outro dono antes da instalação, o agente não inicia e avisa no log: reinstale ou apague a pasta.

Linux (.deb / .rpm)

# Debian/Ubuntu (em ARM64: zoppy-agent_arm64.deb)
curl -fLO https://downloads-agent-connect.zoppy.com.br/agent/stable/zoppy-agent_amd64.deb
sudo apt install ./zoppy-agent_amd64.deb
# RHEL/Rocky/Alma/Oracle Linux (em ARM64: zoppy-agent.aarch64.rpm)
sudo dnf install https://downloads-agent-connect.zoppy.com.br/agent/stable/zoppy-agent.x86_64.rpm

sudo zoppy-agent pair K7QD-92XM

O pacote cria o usuário de sistema zoppy-agent, instala o serviço zoppy-agent.service (systemd, isolado: sem acesso a /home, sistema de arquivos só leitura) e o timer de atualização zoppy-agent-update.timer.

Sem pacote (binário avulso):

curl -fLO https://downloads-agent-connect.zoppy.com.br/agent/stable/zoppy-agent-linux-amd64   # em ARM64: zoppy-agent-linux-arm64
sudo install -m 0755 zoppy-agent-linux-amd64 /usr/local/bin/zoppy-agent
sudo zoppy-agent service install
sudo zoppy-agent pair K7QD-92XM

Arquivos no Linux: configuração em /etc/zoppy-agent/config.yaml; credencial em /var/lib/zoppy-agent (só o usuário zoppy-agent lê); logs no journal (journalctl -u zoppy-agent).

Docker (Linux, NAS, quem já usa container)

docker run -d --name zoppy-agent --restart unless-stopped \
  -e ZOPPY_PAIR_CODE=K7QD-92XM \
  -v zoppy-agent-config:/etc/zoppy-agent \
  -v zoppy-agent-data:/var/lib/zoppy-agent \
  public.ecr.aws/zoppy/zoppy-agent:stable

docker exec -u 0 zoppy-agent zoppy-agent allow add sql --engine sqlserver --host SRVSQL01 --database PROTHEUS
docker exec zoppy-agent zoppy-agent status

A lista local (/etc/zoppy-agent) pertence ao root dentro do container: o agente só lê, e quem muda a lista é o docker exec -u 0. O código de pareamento só é usado na primeira vez; depois a credencial fica no volume zoppy-agent-data. Se o container não resolver os nomes da rede interna, use --network host ou --dns <seu DNS interno>. No Docker, a atualização é pela imagem (docker pull e recriar o container).

Downloads

Sempre a versão mais nova em https://downloads-agent-connect.zoppy.com.br/agent/stable/: zoppy-agent.msi, zoppy-agent_amd64.deb, zoppy-agent_arm64.deb, zoppy-agent.x86_64.rpm, zoppy-agent.aarch64.rpm, os binários zoppy-agent-windows-amd64.exe, zoppy-agent-linux-amd64 e zoppy-agent-linux-arm64, e o SHA256SUMS para conferir (sha256sum -c --ignore-missing SHA256SUMS). Uma versão específica fica em https://downloads-agent-connect.zoppy.com.br/agent/<versão>/ (ex.: .../agent/1.0.0/zoppy-agent.msi) e, no Docker, em public.ecr.aws/zoppy/zoppy-agent:<versão>.

Lista local (o que o agente alcança)

Sem lista, o agente recusa tudo. Libere só o necessário. Os comandos gravam no arquivo de configuração e o serviço relê sozinho (não precisa reiniciar). Rode como administrador/root.

# API interna (Protheus REST): só GET e HEAD, só caminhos /rest...
zoppy-agent allow add http http://protheus.matriz:8080/rest

# API que usa POST para consultar (Sankhya): libere o POST explicitamente
zoppy-agent allow add http https://sankhya.matriz/mge --method GET,POST

# Banco SQL Server (leitura)
zoppy-agent allow add sql --engine sqlserver --host SRVSQL01 --database PROTHEUS

# Oracle (database = service name) e Firebird (database = caminho ou alias)
zoppy-agent allow add sql --engine oracle --host 10.0.0.20 --port 1521 --database ORCL
zoppy-agent allow add sql --engine firebird --host srv-erp --database "C:\ERP\DADOS.FDB"

# MySQL/MariaDB e Postgres (database = nome do banco)
zoppy-agent allow add sql --engine mysql --host 10.0.0.30 --database erp --trust-server-certificate
zoppy-agent allow add sql --engine postgres --host srv-pg --database erp

zoppy-agent allow list                 # mostra a lista numerada
zoppy-agent allow remove http 1        # tira o item http 1
zoppy-agent allow check http http://protheus.matriz:8080/rest/pedidos   # testa sem acessar a rede

Regras da lista:

Host: nome (protheus.matriz), IP (10.0.0.5), curinga só no começo (*.empresa.local) ou faixa (10.0.0.0/24). Um nome liberado não libera o IP dele, e vice-versa; com faixa ou IP, o agente resolve o nome e só conecta se o endereço cair na faixa.
HTTP: esquema, host, porta e (opcional) prefixo de caminho. Métodos: só GET e HEAD por padrão; POST, PUT, PATCH e DELETE só se você listar. O agente não segue redirecionamentos e não usa proxy nas chamadas internas.
SQL: engine, host, porta (padrão 1433, 1521, 3050, 3306 ou 5432) e os bancos. Só SELECT (ou WITH ... SELECT), um comando por vez, dentro de transação só leitura (Oracle, Firebird, MySQL e Postgres, e sempre desfeita no fim) ou sempre desfeita (SQL Server). Qualquer outro comando é recusado, e também: dicas de bloqueio (TABLOCKX, HOLDLOCK, UPDLOCK…), sequências e geradores (NEXT VALUE FOR, NEXTVAL, GEN_ID), nomes com três ou quatro partes no SQL Server (OUTRO.dbo.TABELA, servidor vinculado: o banco liberado é o único lido), database links no Oracle (tabela@link), pacotes DBMS_/UTL_ e HTTPURITYPE, no MySQL INTO OUTFILE/DUMPFILE, LOAD_FILE, GET_LOCK, comentários executáveis (/*! */) e tabela de outro banco (outro.tabela; só information_schema é aceito), no Postgres COPY, pg_read_file e afins, lo_*, dblink, nextval/setval, set_config, query_to_xml e nomes com três partes (outro.public.tabela), bloqueios FOR SHARE/FOR KEY SHARE, e caracteres de controle. No MySQL, escreva aspas dentro de texto dobradas ('it''s'), não com barra invertida. Um valor de coluna maior que o limite do pedido encerra a resposta como truncada; uma linha acima de 512 KiB é recusada (too_large).
Conexão cifrada com o banco (padrão): no SQL Server, MySQL e Postgres o agente exige TLS e confere o certificado do servidor pelo nome do host; no Firebird exige criptografia do protocolo e só aceita autenticação SRP. Sem isso, alguém na rede entre o agente e o banco lê a senha (no SQL Server ela vai só embaralhada) e as linhas, e pode alterar as respostas. Exceções, por servidor, só se precisar:
- --ca-file C:\certs\ca-interna.pem (SQL Server, MySQL ou Postgres com certificado de CA interna: preferível);
- --trust-server-certificate (certificado autoassinado, o padrão do MySQL 8: aceita qualquer certificado, inclusive o de quem estiver no meio);
- --encrypt disable (sem criptografia: no SQL Server só o login vai cifrado, sem conferir o certificado; no Firebird, MySQL e Postgres aceita conexão em texto claro, comum em Postgres instalado sem SSL);
- --legacy-auth (Firebird anterior ao 3, que só tem Legacy_Auth).
O allow add e o allow list mostram quando uma exceção está ligada.
HTTPS com certificado interno: --ca-file C:\certs\ca-interna.pem (preferível) ou --insecure-skip-verify (aceita qualquer certificado daquele host). No Linux, guarde a CA em /etc/zoppy-agent/.

O arquivo é YAML e pode ser editado à mão (exemplo em packaging/config.example.yaml). Se ele ficar inválido, o agente recusa tudo até ser corrigido e avisa no log e no status.

Ver se está funcionando

zoppy-agent status

Agente local do Zoppy Connect
  Versão:            1.0.0 (contrato v1)
  Serviço:           active
  Agente:            SRV-MATRIZ · empresa Acme
  Conexão:           conectado
  Conectado desde:   31/10/2026 14:02:10
  Visto por último:  há 4 s

Lista local (/etc/zoppy-agent/config.yaml):
  http 1  http protheus.matriz porta 8080 caminho /rest · métodos GET, HEAD
  sql  1  sqlserver SRVSQL01:1433 · bancos PROTHEUS

zoppy-agent status --json dá a mesma informação para monitoramento. Na tela da Zoppy, cada agente aparece com estado, versão, visto por último, o que alcança e os conectores que o usam.

Logs: Linux journalctl -u zoppy-agent; Windows C:\ProgramData\ZoppyAgent\data\logs\agent.log; Docker docker logs zoppy-agent. Os logs registram pedido, destino, duração e resultado; nunca senhas, texto das consultas ou linhas de dados.

Atualização

O agente só instala versões assinadas digitalmente pela Zoppy: ele confere a assinatura do manifesto de versões com a chave pública embutida no próprio programa e o hash do arquivo baixado (e de novo o da cópia instalada). Versão sem assinatura válida, manifesto vencido ou de outro canal é recusado. O download fica numa pasta só do root/SYSTEM (/var/lib/zoppy-agent-update, C:\ProgramData\ZoppyAgent\data-update), fora do alcance da conta do serviço.

Windows: a tarefa agendada Zoppy Agent Update (como SYSTEM) verifica a cada 6 h e reinicia o serviço na versão nova.
Linux: o timer zoppy-agent-update.timer verifica a cada ~6 h.
Manual: zoppy-agent update --check (só verifica) ou zoppy-agent update.
Desligar a atualização automática: no config.yaml, updates: { disabled: true }.

Proxy

Se a saída para a internet passa por proxy, defina HTTPS_PROXY para o serviço ou, mais simples, no config.yaml:

proxy: http://proxy.empresa.local:3128

O proxy vale só para a conexão com a Zoppy; as chamadas internas nunca passam por ele.

Usuário só leitura no banco

SQL Server:

CREATE LOGIN zoppy_leitura WITH PASSWORD = '<senha forte>';
USE PROTHEUS;
CREATE USER zoppy_leitura FOR LOGIN zoppy_leitura;
ALTER ROLE db_datareader ADD MEMBER zoppy_leitura;

Oracle:

CREATE USER zoppy_leitura IDENTIFIED BY "<senha forte>";
GRANT CREATE SESSION TO zoppy_leitura;
GRANT SELECT ON erp.pedidos TO zoppy_leitura;   -- uma linha por tabela liberada

Firebird:

CREATE USER zoppy_leitura PASSWORD '<senha forte>';
GRANT SELECT ON PEDIDOS TO zoppy_leitura;        -- uma linha por tabela liberada

MySQL / MariaDB:

CREATE USER 'zoppy_leitura'@'%' IDENTIFIED BY '<senha forte>';
GRANT SELECT ON erp.* TO 'zoppy_leitura'@'%';   -- só o banco do ERP

Postgres:

CREATE USER zoppy_leitura PASSWORD '<senha forte>';
GRANT CONNECT ON DATABASE erp TO zoppy_leitura;
GRANT USAGE ON SCHEMA public TO zoppy_leitura;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO zoppy_leitura;
ALTER USER zoppy_leitura SET default_transaction_read_only = on;

Parâmetros nas consultas: cada motor usa o seu marcador (@p1 no SQL Server, :1 no Oracle, ? no Firebird e no MySQL, $1 no Postgres).

O usuário e a senha são informados na tela da Zoppy como segredos do conector. O agente recebe a senha só na hora da consulta e nunca a grava em disco.

Diagnóstico: agente fora do ar

Quando o agente não responde, a chamada do conector espera até 15 s e falha com connect.agent_offline; a execução falha e a próxima retoma de onde parou. Sem sinal por mais de 5 minutos, os administradores da empresa recebem um aviso, que se resolve sozinho quando o agente volta. Roteiro:

zoppy-agent status na máquina: o estado e o Motivo dizem o que houve.
- conectado: o problema não é o agente; veja a lista local e o banco.
- revogado na tela da Zoppy: gere um código novo e rode zoppy-agent pair --force <código>.
- credencial recusada: idem (a credencial foi trocada ou a máquina foi clonada).
- o serviço parece parado: zoppy-agent service start (Windows: serviço Zoppy Agent; Linux: systemctl start zoppy-agent).
- sem conexão / reconectando: a máquina não sai na 443 até agent-connect.zoppy.com.br. Teste com curl -I https://agent-connect.zoppy.com.br e veja Proxy.
Máquina desligada ou em suspensão: ligue e desative a suspensão (a máquina precisa ficar sempre ligada).
Recusas na consulta: not_allowed = falta liberar na lista local (zoppy-agent allow check sql ...); not_read_only = a consulta não é um SELECT único aceito; auth_failed = usuário/senha do banco nos segredos do conector; connect_failed = banco fora do ar, porta errada ou certificado (veja as exceções de conexão cifrada).
Logs (abaixo de Ver se está funcionando) mostram cada pedido, sem senha nem dados.

Desligar ou remover

Cortar o acesso na hora: na tela da Zoppy, Revogar o agente. A conexão cai imediatamente e o agente para de tentar.
Parar o serviço: zoppy-agent service stop (como administrador/root).
Apagar a credencial desta máquina: zoppy-agent unpair.
Desinstalar: Windows pelo Painel de Controle; Linux sudo apt remove zoppy-agent / sudo dnf remove zoppy-agent; Docker docker rm -f zoppy-agent. Configuração e credencial ficam em disco; apague as pastas se quiser.
Trocar a chave do agente (opcional; ele já troca sozinho a cada 90 dias): zoppy-agent rotate-key.

Dúvidas comuns

Preciso abrir porta no firewall ou ter VPN? Não. A conexão é só de saída, na 443, como um navegador.

O que a Zoppy vê da minha rede? Só as respostas dos pedidos que caem na lista local. O agente não varre a rede, não lista máquinas e recusa qualquer endereço fora da lista. A Zoppy vê a lista (para mostrar “o que alcança”), mas não consegue alterá-la.

A Zoppy pode apagar ou alterar algo no ERP? No banco, não: o usuário é só leitura, o agente só aceita SELECT e roda dentro de transação só leitura ou sempre desfeita. Nas APIs, só os métodos que você liberou (por padrão, apenas GET e HEAD).

E se a máquina desligar? Os conectores que usam este agente param, os administradores da empresa na Zoppy recebem aviso, e na volta a próxima execução traz o que faltou.

Posso instalar em mais de uma máquina? Sim, cada uma com seu código de pareamento; cada conector escolhe o agente que usa. Não copie a pasta de dados de uma máquina para outra: cada agente tem a própria chave.

Funciona em Linux sem systemd ou em NAS? Use a imagem Docker, ou rode zoppy-agent run no supervisor da máquina.