Instalação

O Agent é distribuído como um pacote .tar.gz — baixe a versão mais recente em Downloads. Há dois jeitos de rodá-lo: por Docker, que é o caminho pensado para produção, ou direto do código-fonte, útil em desenvolvimento e em máquinas onde você já tem Node. Os dois sobem o mesmo processo e leem a mesma configuração; o que muda é o empacotamento. Esta página cobre os dois e explica o detalhe de rede que faz o Agent seguro por padrão.

Antes de subir, você vai precisar de credenciais

O Agent não sobe com valores de exemplo: ele exige a URL da API, a sua API key de serviço, o kid da sua chave de assinatura e a chave privada em si. Como obter esse material é assunto de Provisionamento e credenciais; como apontá-lo para o Agent é a página de Configuração. Aqui tratamos só de colocar o processo no ar.

Pré-requisitos

Para Docker

Docker instalado na host do servidor de jogo. Você não precisa de Node nem de compilador: a imagem já traz o runtime, e a compilação do TypeScript acontece dentro dela.

Para código-fonte

Node 22 ou superior na host. O Agent é ESM e usa recursos recentes do Node; versões anteriores não servem.

Subindo o Agent

Docker (recomendado)

O Dockerfile do Agent é multi-stage: uma imagem compila o TypeScript, e a imagem final, baseada em node:22-alpine, carrega apenas o dist/ e o manifesto. Como o Agent não tem dependência de runtime, a imagem final não tem node_modules — não há árvore de terceiros para auditar nem para vazar. O processo roda como o usuário node, nunca como root.

Construa a imagem a partir do diretório do Agent:

docker build -t lootfy-agent .

E suba o container passando a sua configuração (por um arquivo de ambiente e o volume com a chave privada — ver Configuração):

docker run -d --name lootfy-agent \
  --network host \
  --env-file ./agent.env \
  -v /etc/lootfy/server-key.pem:/etc/lootfy/server-key.pem:ro \
  lootfy-agent

A partir do código

Com Node 22+ instalado, no diretório do Agent, instale as ferramentas de build, compile o TypeScript para dist/ e inicie:

npm install
npm run build
npm start

npm run build roda o tsc e gera o dist/; npm start executa node dist/main.js. Para desenvolvimento, npm run dev roda direto do TypeScript sem passo de build, e npm run typecheck confere os tipos sem gerar saída.

Ele também é um binário

O pacote declara o bin lootfy-agent → dist/main.js. Depois do build, um npm install -g (ou um link) deixa o comando lootfy-agent disponível diretamente.

--network host e a ausência de -p

Você deve ter reparado que o exemplo de Docker usa --network host e não usa -p para publicar portas. Isso é deliberado, e entender o porquê é entender o modelo de segurança do Agent.

O Dockerfile não tem instrução EXPOSE, e a documentação do próprio Agent pede que você nunca publique a porta de controle com -p. A porta de controle (127.0.0.1:8899) assina sob demanda: publicá-la com -p 8899:8899 a colocaria acessível para além da máquina, e quem a alcançasse deteria toda a autoridade da sua conta Lootfy. Não é um risco teórico — é entregar a caneta.

Nunca publique a porta de controle

docker run -p 8899:8899 ... é exatamente o que você não deve fazer. A porta de controle não tem autenticação; a única defesa dela é ficar em loopback. Publicá-la anula essa defesa.

Para que o seu servidor de jogo, rodando na mesma host, alcance a porta de controle em 127.0.0.1, o container precisa compartilhar a rede da host — é o que --network host faz. A alternativa, quando você não quer compartilhar a rede, é não usar a interface HTTP e falar com o Agent pelo spool: um diretório montado como volume, sem nenhuma porta publicada. Essa é, aliás, a rota recomendada para servidores TFS. As duas interfaces estão descritas em Interfaces locais.

O que esperar do boot

Ao subir, o Agent primeiro carrega e valida a configuração. Se algo obrigatório faltar ou estiver errado, ele não sobe: escreve o erro em texto puro no stderr — não em JSON, porque quem lê é uma pessoa no terminal — e encerra o processo. O código de saída distingue o tipo de falha: 2 para erro de configuração e 1 para qualquer outra falha de inicialização.

lootfy-agent não subiu.

  LOOTFY_BASE_URL is required and has no default. See the agent README.

Uma falha de boot recorrente e proposital: se você apontar a porta de controle para um endereço público (por exemplo 0.0.0.0), o Agent recusa subir em vez de avisar e continuar — porque um aviso em log é lido depois do incidente, não antes. O motivo e o alcance exato dessa checagem estão em Configuração e em Segurança operacional.

Subindo com sucesso, o Agent registra que a porta de controle está no ar, sobe o worker de spool caso você tenha configurado um diretório, e sobe a porta de webhook caso os três pré-requisitos dela estejam presentes. Ele responde a SIGINT e SIGTERM com um encerramento gracioso, fechando as portas e o worker antes de sair — então um docker stop ou um Ctrl+C não deixa pedidos pela metade.

Próximo: configuração Todas as variáveis de ambiente, os defaults e como ligar o webhook.