> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação no Windows

> Instale e desinstale o Agente Fire no Windows 10/11 para imprimir a partir do POS.

O Agente Fire é um agente local que permite que qualquer navegador (FIRE POS, XMART, etc.) imprima em impressoras térmicas de ponto de venda por WebSocket. Depois de instalado, ele roda em segundo plano e inicia automaticamente com o Windows.

Instale uma vez em cada dispositivo Windows que tenha uma impressora conectada.

## Pré-requisitos

| Requisito           | Detalhe                                                                             |
| ------------------- | ----------------------------------------------------------------------------------- |
| Sistema operacional | Windows 10 ou Windows 11, **64 bits**                                               |
| Permissões          | Conta com direitos de **Administrador** (apenas durante a instalação/desinstalação) |
| PowerShell          | 5.1 ou superior (incluído no Windows 10/11) — apenas para verificar o agente        |
| Node.js             | **Não** é necessário. O agente é distribuído como um `.exe` independente            |
| Impressora          | O driver da impressora térmica já deve estar instalado no Windows                   |

<Note>
  O agente escuta apenas em `127.0.0.1` (localhost), então **não precisa abrir portas nem criar regras no Firewall do Windows**.
</Note>

## Arquivos necessários

Conforme a tarefa, você vai precisar de um destes arquivos:

| Arquivo                  | Para que serve                                                                   |
| ------------------------ | -------------------------------------------------------------------------------- |
| `fireAgentSetup.exe`     | **Instalador gráfico.** Instala o agente com um assistente.                      |
| `fireAgentUninstall.exe` | **Desinstalador independente.** Remove o agente mesmo sem o instalador original. |

<Card title="Baixar Agente Fire (Windows)" icon="download" href="https://drive.google.com/uc?export=download&id=1OiqSbD5flcsc6cV2ZjxxkHy-cmxwH5d1">
  Instalador do Windows para impressão térmica local.
</Card>

## Instalação passo a passo

<Steps>
  <Step title="Execute o instalador como administrador">
    1. Localize `fireAgentSetup.exe`.
    2. Clique com o **botão direito** e selecione **Executar como administrador**.
    3. Se aparecer o aviso de **Controle de Conta de Usuário (UAC)**, clique em **Sim**.

    <Tip>
      Se o Windows SmartScreen mostrar "O Windows protegeu o seu PC", clique em **Mais informações → Executar assim mesmo**.
    </Tip>
  </Step>

  <Step title="Tela de boas-vindas">
    O assistente mostra a mensagem de boas-vindas do **Fire Agent 1.1.0**. Clique em **Next** (Avançar).

    <Frame>
      <img src="https://mintcdn.com/firepos/LYYmInDIqI15OPj4/images/manuals/fire-agent/installer-01-welcome.png?fit=max&auto=format&n=LYYmInDIqI15OPj4&q=85&s=4df64f3e08f6e2a43291b4bbf3f7c8e0" alt="Assistente de instalação do Agente Fire — tela de boas-vindas" width="623" height="485" data-path="images/manuals/fire-agent/installer-01-welcome.png" />
    </Frame>
  </Step>

  <Step title="Pasta de instalação">
    Confirme a pasta de instalação (`C:\Program Files\FireAgent` por padrão). Recomenda-se manter o caminho padrão. Clique em **Install** (Instalar).

    <Frame>
      <img src="https://mintcdn.com/firepos/LYYmInDIqI15OPj4/images/manuals/fire-agent/installer-02-location.png?fit=max&auto=format&n=LYYmInDIqI15OPj4&q=85&s=e3b60db58b30fca3b3cd4589c7e9b605" alt="Assistente de instalação do Agente Fire — pasta de instalação" width="623" height="485" data-path="images/manuals/fire-agent/installer-02-location.png" />
    </Frame>
  </Step>

  <Step title="Instalação automática">
    O assistente realiza, sem intervenção do usuário:

    1. Para qualquer instância anterior do agente.
    2. Copia `fire-agent.exe` para a pasta de instalação.
    3. Salva o token `FIRE_AGENT_TOKEN` como **variável de ambiente do sistema**.
    4. Registra a **inicialização automática** com o Windows para todos os usuários.
    5. Registra o aplicativo em **Adicionar ou remover programas**.
    6. Cria o desinstalador dentro da pasta de instalação.

    <Frame>
      <img src="https://mintcdn.com/firepos/LYYmInDIqI15OPj4/images/manuals/fire-agent/installer-03-installing.png?fit=max&auto=format&n=LYYmInDIqI15OPj4&q=85&s=b68b24d1036e3f1801a5d1ba47904ec1" alt="Assistente de instalação do Agente Fire — barra de progresso" width="623" height="485" data-path="images/manuals/fire-agent/installer-03-installing.png" />
    </Frame>

    Aguarde a barra de progresso terminar e clique em **Next** (Avançar).
  </Step>

  <Step title="Concluir">
    A última tela confirma a instalação e o **token configurado**. Para iniciar o agente imediatamente, deixe marcada a opção **Start Fire Agent now** e clique em **Finish** (Concluir).

    <Frame>
      <img src="https://mintcdn.com/firepos/LYYmInDIqI15OPj4/images/manuals/fire-agent/installer-04-finish.png?fit=max&auto=format&n=LYYmInDIqI15OPj4&q=85&s=8c92b448a4c3e78a475851ad504e7ade" alt="Assistente de instalação do Agente Fire — instalação concluída" width="623" height="485" data-path="images/manuals/fire-agent/installer-04-finish.png" />
    </Frame>
  </Step>

  <Step title="Primeiro início (certificado SSL)">
    No primeiro início, o agente gera um **certificado SSL autoassinado** em `%APPDATA%\FireAgent\ssl\` (em JavaScript puro, sem PowerShell) e o instala como confiável no repositório do usuário atual com `certutil.exe`. Isso permite que páginas HTTPS se conectem a `wss://localhost:9101` sem avisos, sem pedir permissões de administrador e de forma compatível com equipamentos com GPO.
  </Step>
</Steps>

<Check>
  O Agente Fire fica instalado e inicia automaticamente sempre que um usuário faz login no Windows. Aparece como um ícone na bandeja do sistema (perto do relógio).
</Check>

## Verifique se o agente está rodando

Abra este endereço no navegador ou use o PowerShell:

```powershell theme={null}
Invoke-RestMethod http://localhost:9100/health
```

Resposta esperada:

```json theme={null}
{ "status": "ok", "version": "1.1.0", "uptime": 12, "platform": "win32" }
```

Para listar as impressoras detectadas:

```powershell theme={null}
Invoke-RestMethod http://localhost:9100/printers
```

Você também pode clicar no ícone do Fire Agent na bandeja do sistema para abrir o painel informativo. Para testes de impressão, consulte [Web do agente](/pt/manuals/fire-agent/web-tools).

### Portas utilizadas

| Porta  | Endereço                   | Protocolo   | Uso                                                |
| ------ | -------------------------- | ----------- | -------------------------------------------------- |
| `9100` | `127.0.0.1` (apenas local) | HTTP / WS   | WebSocket em texto puro e endpoints REST           |
| `9101` | `127.0.0.1` (apenas local) | HTTPS / WSS | WebSocket criptografado (certificado autoassinado) |

## Desinstalação

Há três métodos. Todos removem o agente por completo (arquivos, configuração, certificado, inicialização automática e registro).

### Método 1 — Adicionar ou remover programas (recomendado)

1. Abra as **Configurações** (`Windows` + `I`).
2. Vá em **Aplicativos → Aplicativos instalados**.
3. Encontre **Fire Agent**, abra o menu (⋯) → **Desinstalar** e confirme.
4. Se aparecer o aviso do UAC, clique em **Sim** e siga o assistente.

### Método 2 — Desinstalador independente (`fireAgentUninstall.exe`)

Útil quando o instalador original não está mais disponível.

1. Clique com o **botão direito → Executar como administrador**.
2. Confirme na caixa de diálogo e siga o assistente (**Avançar → Desinstalar → Concluir**).

### Método 3 — Desinstalação silenciosa (scripts ou implantações em massa)

No PowerShell ou CMD como administrador:

```powershell theme={null}
.\fireAgentUninstall.exe /S
```

O parâmetro `/S` executa a desinstalação sem mostrar janelas nem pedir confirmação.

<Note>
  Qualquer um dos três métodos para o `fire-agent.exe`, remove a inicialização automática, a variável `FIRE_AGENT_TOKEN` e o certificado SSL, apaga os arquivos de `C:\Program Files\FireAgent\` e `%APPDATA%\FireAgent\`, e remove a entrada de Adicionar ou remover programas.
</Note>

## Solução de problemas

| Sintoma                                               | Causa provável                                                   | Solução                                                                                                                                                                         |
| ----------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `http://localhost:9100/health` não responde           | O agente não está rodando                                        | Inicie `fire-agent.exe` em `C:\Program Files\FireAgent\` ou reinicie o equipamento                                                                                              |
| O antivírus colocou o `.exe` em quarentena            | Falso positivo com executáveis do Node empacotados               | Restaure o arquivo ou adicione uma exclusão para `C:\Program Files\FireAgent` e `%APPDATA%\FireAgent`, e reinstale                                                              |
| Erro `401 Unauthorized` na conexão WebSocket          | Token incorreto                                                  | Verifique `FIRE_AGENT_TOKEN` nas variáveis de ambiente do sistema                                                                                                               |
| A impressora não aparece na lista                     | O driver não está instalado no Windows                           | Instale o driver da impressora pelas configurações do Windows                                                                                                                   |
| Uma página HTTPS não conecta a `wss://localhost:9101` | `certutil` foi bloqueado e o navegador não confia no certificado | Importe `%APPDATA%\FireAgent\ssl\cert.cer` em **Autoridades de Certificação Raiz Confiáveis** (`certmgr.msc`), ou abra `https://localhost:9101/health` uma vez e aceite o aviso |
| Firefox mostra aviso de certificado                   | O Firefox usa o próprio repositório de certificados              | Ative `security.enterprise_roots.enabled` em `about:config`, ou importe o `.cer` em **Firefox → Configurações → Privacidade e Segurança → Certificados**                        |

## Anexo: o que o instalador altera no sistema

Referência para administradores de sistemas.

### Arquivos

| Caminho                                     | Conteúdo                                      |
| ------------------------------------------- | --------------------------------------------- |
| `C:\Program Files\FireAgent\fire-agent.exe` | Executável do agente                          |
| `C:\Program Files\FireAgent\uninstall.exe`  | Desinstalador criado pelo instalador          |
| `%APPDATA%\FireAgent\config.json`           | Configuração persistente                      |
| `%APPDATA%\FireAgent\ssl\`                  | Certificado SSL autoassinado (chave + `.cer`) |

### Registro do Windows

| Chave                                          | Propósito                                       |
| ---------------------------------------------- | ----------------------------------------------- |
| `HKLM\...\CurrentVersion\Run\FireAgent`        | Inicialização automática para todos os usuários |
| `HKLM\SYSTEM\...\Environment\FIRE_AGENT_TOKEN` | Variável de ambiente do sistema                 |
| `HKLM\...\CurrentVersion\Uninstall\FireAgent`  | Entrada em Adicionar ou remover programas       |

### Variáveis de ambiente suportadas (avançado)

| Variável                | Padrão                 | Descrição                                                      |
| ----------------------- | ---------------------- | -------------------------------------------------------------- |
| `FIRE_AGENT_TOKEN`      | `fire-agent-dev-token` | Token compartilhado com o POS. **Altere em produção.**         |
| `FIRE_AGENT_PORT`       | `9100`                 | Porta HTTP / WS                                                |
| `FIRE_AGENT_SSL_PORT`   | `9101`                 | Porta HTTPS / WSS                                              |
| `FIRE_AGENT_UPDATE_URL` | *(vazio — desativado)* | URL consultada na inicialização para buscar versões mais novas |