Instalação

Downloads em www.brasilnfe.com.br/agente. Os links diretos, a versão atual, o tamanho e o SHA-256 de cada instalador também estão disponíveis em JSON público: GET https://api.brasilnfe.com.br/services/Agent/Releases. Cada arquivo é servido por https://api.brasilnfe.com.br/services/Agent/Download?alvo=ALVO.

Requisitos

Windows

1. Baixe o instalador (windows-x64, arquivo Brasil NFe Agente_<versão>_x64-setup.exe) e execute. O instalador é em português e leva segundos.
2. O programa fica em %LOCALAPPDATA%\Brasil NFe Agente\ e abre com a tela de boas-vindas. Fechar ou minimizar a janela não encerra: o Agente vai para a bandeja do sistema e continua assinando. Use o ícone da bandeja para reabrir ou sair.
3. Em Configurações (ícone de engrenagem) ative Iniciar com o sistema para o Agente subir no login, sem ninguém abrir.

Aviso "Editor desconhecido" do Windows SmartScreen. Pode aparecer enquanto a assinatura de código Authenticode do instalador está em andamento. Confira o SHA-256 do arquivo baixado com o valor exibido na página de download (Get-FileHash .\Brasil*.exe no PowerShell) e prossiga em "Mais informações › Executar assim mesmo". As atualizações automáticas são verificadas por assinatura digital pelo próprio Agente.

Linha de comando no Windows. O mesmo brasilnfe-agent.exe do instalador tem a CLI inteira; com > arquivo ou | a saída vai direto para o destino. Detalhe do cmd.exe: o prompt volta antes da saída terminar; use start /wait quando precisar esperar. O instalador não adiciona a pasta ao PATH.

Code
& "$env:LOCALAPPDATA\Brasil NFe Agente\brasilnfe-agent.exe" nfce status
# cmd.exe, esperando o fim:
start /wait "" "%LOCALAPPDATA%\Brasil NFe Agente\brasilnfe-agent.exe" nfce status

Linux com interface gráfica

Code
chmod +x "Brasil NFe Agente_0.1.0_amd64.AppImage"
./"Brasil NFe Agente_0.1.0_amd64.AppImage"            # abre a interface
./"Brasil NFe Agente_0.1.0_amd64.AppImage" nfce status # CLI, mesmo arquivo

Linux headless (servidor, VPS, container)

O binário linux-x64-headless é o mesmo Agente sem a interface, feito para rodar em praticamente qualquer Linux x86_64 (Ubuntu 20.04 em diante). É um arquivo único: copie, dê permissão de execução e use os mesmos subcomandos.

Code
chmod +x brasilnfe-agent
sudo mv brasilnfe-agent /usr/local/bin/brasilnfe-agent

# parear uma empresa (pede a senha do PFX no prompt, sem eco)
brasilnfe-agent pair bna_... --pfx /caminho/certificado.pfx

# conferir e rodar (ctrl-c encerra)
brasilnfe-agent list
brasilnfe-agent run

Na VPS não há cofre de senhas do sistema, então a senha do PFX fica em um arquivo da pasta de dados com permissão restrita ao usuário (0600). Rode o pair com o mesmo usuário que vai rodar o serviço: os dados ficam no home desse usuário.

Serviço systemd (inicia no boot e reinicia sozinho)

/etc/systemd/system/brasilnfe-agent.service (troque usuario):

Code
[Unit]
Description=Brasil NFe Agente (headless)
After=network-online.target
Wants=network-online.target

[Service]
User=usuario
ExecStart=/usr/local/bin/brasilnfe-agent run
Restart=always
RestartSec=5
Environment=RUST_LOG=brasilnfe_agent_lib=info
# Proxy corporativo, se houver:
# Environment=HTTPS_PROXY=http://usuario:[email protected]:3128
# Environment=NO_PROXY=localhost,127.0.0.1,.interno.local

[Install]
WantedBy=multi-user.target

Code
sudo systemctl daemon-reload
sudo systemctl enable --now brasilnfe-agent
journalctl -u brasilnfe-agent -f      # logs

Com o .deb/.rpm instalado num servidor sem tela, o ExecStart é /usr/bin/brasil-nfe-agente run. A atualização automática do binário headless substitui o arquivo e reinicia; sob systemd isso é transparente.

Pareamento (resumo)

1. No painel do Brasil NFe, Configurações › aba Agente › Gerar código de pareamento. O código começa com bna_ e deve ser tratado como senha.
2. No Agente:
   • Interface: "Adicionar empresa", cole o código, escolha Certificado instalado (Windows), A1 (arquivo .pfx) ou A3 (token PKCS#11), informe senha/PIN, Validar certificado e Salvar e conectar.
   • CLI: brasilnfe-agent pair CODIGO --pfx ARQUIVO (A1), --module LIB [--slot N] (A3) ou --thumbprint SHA1 (loja do Windows), depois run.
3. O Agente confere se o certificado pertence ao CNPJ do código e recusa certificado de outra empresa.

Uma empresa = um certificado; um Agente = N empresas (N códigos). Tudo sobre isso em Pareamento e certificado.

Servidor de loja atendendo vários caixas

Uma empresa fica conectada a um Agente por vez (o servidor derruba a conexão anterior quando outra instância pareia com o mesmo código). Para uma loja com vários PDVs do mesmo CNPJ, o desenho é:

1. Instale o Agente em um computador da loja que fique ligado (servidor local, com ou sem tela).

2. Faça a API local escutar na rede: pela tela (NFC-e › Configuração › "Escutar em: toda a rede local") ou por comando:

   Code
   brasilnfe-agent nfce config --bind 0.0.0.0 --porta 9155

3. Libere a porta no firewall da máquina para a rede interna e aponte cada PDV para http://IP-DO-SERVIDOR:9155.

4. Se os PDVs rodam no navegador, autorize a origem deles uma vez: nfce config --origem https://pdv.suaempresa.com.br.

Cada nota recebe o próximo número da série do Agente, independentemente de qual caixa a pediu; a emissão é serializada (uma nota por vez), então dois caixas nunca recebem o mesmo número.

Redes com vários CNPJs: pareie cada empresa no Agente da respectiva loja (ou todas no mesmo, se preferir), e o PDV informa a empresa pelo header X-Empresa-CNPJ.

Segunda instância na mesma máquina

BRASILNFE_DATA_DIR aponta o Agente para outra pasta de dados, isolando pareamentos, notas e configuração. Serve para testes e para um segundo Agente na mesma máquina (por exemplo, outra empresa com outra porta de API local: nfce config --porta 9156).

Proxy HTTP corporativo

A conexão mTLS com a SEFAZ respeita as variáveis padrão (as mesmas do curl): HTTPS_PROXY (ou HTTP_PROXY) com http://usuario:senha@proxy:porta e NO_PROXY para destinos que saem direto. Só proxy http:// com túnel CONNECT; o TLS continua ponta a ponta com a SEFAZ e o proxy não vê o conteúdo. O Agente não lê o proxy configurado no Windows (WinINet): use as variáveis de ambiente. Sem elas, a conexão é direta.

Onde ficam os dados

Interface gráfica e headless leem os mesmos arquivos: parear num modo e rodar no outro funciona sem conversão.

Atualização automática

O Agente consulta o Brasil NFe ao subir e a cada 6 horas. Se há versão mais nova para o seu alvo, ele baixa, confere o hash e a assinatura digital do pacote e aplica:

• Windows: roda o instalador em modo silencioso e reabre o Agente.
• Linux headless e AppImage: substitui o próprio binário e reinicia (transparente sob systemd).
• .deb/.rpm: só avisa; atualize pelo gerenciador de pacotes.

Para desligar a aplicação automática (ele passa só a avisar): interruptor Atualização automática nas configurações ou BRASILNFE_AUTO_UPDATE=0 no ambiente. Para forçar: update check (consulta) e update apply (baixa, verifica e aplica), na CLI, na tela ou no console do painel.

Desinstalar ou remover uma empresa

• Remover um pareamento: na tela, o "x" da empresa; na CLI, brasilnfe-agent unpair CODIGO. Remove o pareamento e o segredo do cofre; as notas off-line já emitidas continuam no banco local até serem enviadas (elas sobem quando a empresa for pareada de novo).
• Revogar pelo painel (Configurações › Agente › Revogar): derruba o Agente na hora e invalida o código; assinatura e NFC-e off-line param até novo pareamento.
• Desinstalar: Windows, "Aplicativos instalados"; Linux, apt remove brasil-nfe-agente / dnf remove ou apague o AppImage/binário. A pasta de dados não é apagada automaticamente; se houver notas off-line pendentes, envie-as antes (ver NFC-e off-line).