Como rodar o Hermes Agent no Signal (signal-cli)

Por que rodar o Hermes Agent no Signal

Se seu modelo de ameaças coloca metadados em primeiro lugar, o Signal é o mensageiro em que você já confia. A criptografia ponta a ponta vem ligada por padrão, o servidor guarda quase nada além de um número de telefone e o timestamp da última conexão, e o protocolo em si é de código aberto. Colocar seu agente de IA na mesma superfície mantém cada prompt, cada resposta e cada arquivo que você passa para ele dentro do mesmo envelope.

O Hermes Agent suporta o Signal de forma nativa através do signal-cli, um daemon não oficial mas bem mantido que fala o protocolo do Signal em seu nome. O gateway do Hermes conversa com o signal-cli por HTTP usando JSON-RPC para as ações de saída e Server-Sent Events para o fluxo de entrada, então o runtime inteiro cabe num VPS de 5 USD, no seu notebook, ou numa Raspberry Pi atrás de um NAT e ainda assim envia e recebe em tempo real.

Este guia percorre o setup completo: instalar o signal-cli, vinculá-lo à sua conta do Signal como dispositivo secundário, subir o daemon HTTP, ligá-lo ao runtime do Hermes e as armadilhas que mordem no primeiro deploy. Se você já colocou o Hermes em alguma superfície mais pública, o tutorial do Slack e o guia do Telegram cobrem o mesmo lado da stack e vale deixar abertos lado a lado.

O que você precisa antes de começar

Um deploy limpo do Signal precisa de cinco coisas no host:

Uma instalação do Hermes Agent funcionando. O guia do Hermes Agent no Docker é o ponto de partida mais limpo se ainda não tiver.
Uma API key de um provedor de modelo. Anthropic, OpenAI, OpenRouter e qualquer endpoint compatível com OpenAI servem. O runtime usa essa chave para de fato responder as mensagens.
Uma conta do Signal já ativada num dispositivo principal (seu celular). O signal-cli se vincula como dispositivo secundário, igual ao Signal Desktop - não registra uma conta nova.
Java Runtime Environment 21 ou superior. O jar do signal-cli não roda em JRE 17 nas builds atuais. O binário nativo do GraalVM dispensa esse requisito se você prefere um único executável.
Cerca de 20 minutos para a primeira instalação. Os redeploys seguintes levam menos de um minuto.

O número de telefone que você usar não precisa ser o do seu celular do dia a dia. Muita gente que self-hospeda dedica um segundo número (um eSIM barato, um número do Twilio, ou uma linha do Google Voice que aceite SMS) para que a conta do bot fique operacionalmente separada.

Passo 1 - Instalar o signal-cli no host

No Debian ou Ubuntu, instale o Java e baixe a release mais recente do signal-cli:

sudo apt update
sudo apt install -y curl openjdk-21-jre
VERSION=$(curl -s https://api.github.com/repos/AsamK/signal-cli/releases/latest | jq -r .tag_name | sed 's/^v//')
curl -L -o /tmp/signal-cli.tar.gz \
  "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux.tar.gz"
sudo tar -xf /tmp/signal-cli.tar.gz -C /opt
sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/signal-cli
signal-cli --version

Se você prefere um único binário estático, sem depender de JRE, a build nativa com GraalVM da página de releases é um substituto direto e evita o ciclo de atualizações do Java.

Passo 2 - Vincular o signal-cli à sua conta do Signal

O signal-cli entra na sua conta como dispositivo vinculado, exatamente como o Signal Desktop. Gere uma URL de provisionamento e peça ao daemon para imprimir um QR code:

signal-cli link -n "hermes-agent"

O comando imprime uma URL sgnl://linkdevice?... e um QR no terminal. No celular, abra o Signal, vá em Configurações -> Dispositivos vinculados -> Vincular novo dispositivo e escaneie o QR. Em alguns segundos o terminal mostra algo como:

Associated with: +12025550123

Esse número em E.164 é o valor de SIGNAL_ACCOUNT para o resto da configuração. O estado em disco da identidade vinculada vive em ~/.local/share/signal-cli/. Faça backup desse diretório antes de destruir o host - é o único lugar onde ficam as chaves do dispositivo vinculado, e revincular do zero invalida o histórico pendente.

Passo 3 - Subir o daemon HTTP do signal-cli

O gateway do Hermes fala com o signal-cli por HTTP, então o daemon precisa rodar em modo HTTP atado a uma porta apenas local:

signal-cli -a +12025550123 daemon --http 127.0.0.1:8080

A flag --http expõe um endpoint JSON-RPC para enviar e um fluxo Server-Sent Events para receber. Atar em 127.0.0.1 e em nada mais; o daemon não faz autenticação própria, então qualquer processo que chegue à porta consegue enviar mensagens como se fosse você. Se o gateway roda em Docker no mesmo host, host.docker.internal:8080 ou uma rede Docker compartilhada funcionam sem expor a porta para a LAN.

Para deploys de longo prazo, deixe uma unit do systemd para o daemon reiniciar depois de um reboot. O wiki do signal-cli traz uma template pronta; os únicos campos para preencher são o número da conta e o endereço de bind.

Um terminal dividido mostrando os logs do daemon do signal-cli à esquerda e os logs do gateway do Hermes à direita, ambos conectados via localhost:8080

Passo 4 - Configurar o runtime do Hermes

Abra ~/.hermes/.env (ou o .env que seu container lê) e adicione:

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+12025550123
SIGNAL_ALLOWED_USERS=+5511955501234,+12025557788
SIGNAL_GROUP_ALLOWED_USERS=group.abc123==
SIGNAL_HOME_CHANNEL=+5511955501234

Uma nota sobre cada um:

SIGNAL_HTTP_URL - o endpoint do daemon local do passo 3. Sempre http://, sempre loopback ou rede privada.
SIGNAL_ACCOUNT - o número em E.164 da identidade do Signal vinculada. Tem que bater exatamente com o que o signal-cli link reportou.
SIGNAL_ALLOWED_USERS - números E.164 ou UUIDs do Signal separados por vírgula que podem falar com o bot. Sem essa variável (e sem pareamento de DM), o gateway nega toda mensagem de entrada como padrão seguro. É o controle de segurança mais importante de toda a pilha.
SIGNAL_GROUP_ALLOWED_USERS (opcional) - IDs de grupo separados por vírgula onde o bot pode responder. Os IDs saem de signal-cli listGroups -d. Deixe em branco para desligar o suporte a grupos.
SIGNAL_HOME_CHANNEL (opcional) - o destino padrão de tarefas agendadas, cron jobs e notificações disparadas por skills. Sem valor, a saída proativa vai para o primeiro usuário permitido.

Faça chmod 600 ~/.hermes/.env depois de salvar. A combinação da identidade vinculada do Signal com as chaves do seu provedor de modelo permite que qualquer um que leia esse arquivo se passe pelo bot e queime seus tokens - trate como uma chave SSH.

Passo 5 - Subir o gateway e mandar a primeira mensagem

Reinicie o gateway do Hermes para ele pegar o novo ambiente:

hermes gateway restart

Acompanhe os logs e procure duas linhas, nesta ordem:

signal: connecting to http://127.0.0.1:8080
signal: subscribed to receive stream for +12025550123

A partir do número permitido, abra o Signal e mande um DM para o número do bot. O Hermes responde na mesma thread, com memória persistente e contexto de skills intactos - o tutorial de memória e skills explica o que está acontecendo por baixo. Anexos de até 100 MB sobem pela mesma API de upload do Signal que uma mensagem comum, então prints, áudios e PDFs passam sem encanamento extra.

Uma thread do Signal mostrando uma troca privada entre um usuário e o bot do Hermes, com os indicadores de criptografia ponta a ponta visíveis no topo da tela

Os erros que mordem primeiro

Cinco erros explicam quase todo "o setup do Signal está quebrado" do suporte:

Esquecer de vincular o dispositivo. Subir signal-cli daemon numa conta não vinculada não imprime erro nenhum - o daemon sobe e silenciosamente recusa toda mensagem. Se os logs mostram zero eventos e zero tentativas de envio, rode signal-cli listAccounts e confirme que seu número aparece.

Versão errada do JRE. As builds atuais do signal-cli precisam de JRE 21. Em servidores antigos travados em JRE 17 ou 11, o jar falha com erro de versão de classe assim que você chama --http. Suba a versão do Java ou use o binário nativo do GraalVM.

SIGNAL_ALLOWED_USERS vazio. O padrão é negar todo mundo. É de propósito - um número vazado da conta do bot deixaria qualquer pessoa no mundo te mandar prompts e queimar seus tokens. O bot parecer morto para um testador de primeira viagem que esqueceu de pôr o próprio número é o alarme falso mais frequente.

Daemon atado em 0.0.0.0. O daemon HTTP não faz autenticação. Atar em uma interface pública significa que qualquer um que chegue à porta consegue mandar mensagens do Signal como se fosse você. Sempre 127.0.0.1 ou rede Docker privada.

Estado de dispositivo vinculado obsoleto. Rodar signal-cli link de novo sobrescreve o diretório de estado local. O novo vínculo funciona, mas o Hermes está olhando para uma identidade diferente da que o .env declara. Ou mantenha o SIGNAL_ACCOUNT antigo ao revincular, ou atualize o env com o número novo impresso pelo comando.

Se o problema parece do Signal mas os sintomas são mais gerais - respostas faltando, deriva de memória, erros do provedor - o guia de troubleshooting do Telegram cobre os problemas de gateway e provedor com mais profundidade. A maioria é independente da superfície.

Signal ao lado de Telegram e Slack

Aspecto	Signal	Telegram	Slack
Tempo de setup	20 min (link + daemon)	5 min (token do BotFather)	15 min (manifesto + 2 tokens)
Criptografia	E2E por padrão	Chats secretos opt-in	Só do lado do servidor
Metadados guardados	Quase nada	Histórico no servidor	Retenção por workspace
Modelo de conta	Número de telefone vinculado	Conta de bot, sem número	Usuário bot no workspace
Campo da allowlist	`SIGNAL_ALLOWED_USERS` (E.164)	`TELEGRAM_ALLOWED_USERS` (numérico)	`SLACK_ALLOWED_USERS` (numérico)
Melhor para	Pessoas e times pequenos com foco em privacidade	Uso pessoal, mobile-first, voice-mode	Workflows de time e contexto de canais

As três superfícies não são exclusivas. O mesmo runtime do Hermes entrega para as três ao mesmo tempo, multiplexando sobre um único repositório de memória. Um founder com um agente pessoal no Signal e um agente de time no Slack a partir da mesma instalação é um padrão comum.

Pule o encanamento do Signal

Os passos acima são tratáveis, mas deixam o host nas suas mãos: manter o signal-cli atualizado, fazer backup do estado do dispositivo vinculado, rotacionar o JRE, ficar de olho em restarts do daemon. Para uma instalação pessoal está ok. Para qualquer coisa que você queira viva em minutos e depois esquecer, o Hermify provisiona um runtime gerenciado do Hermes com a ponte de Signal pronta para vincular, criptografa sua config SIGNAL_* em repouso e mantém o daemon do signal-cli saudável em um servidor persistente onde você nunca precisa entrar por SSH.

Você traz o número do Signal e uma chave de provedor de modelo; a plataforma cuida de tudo abaixo. Se quiser comparar o que fica sob seu controle e o que é delegado, o comparativo entre self-hosting e gerenciado abre os números de manutenção e custo. E se o custo é o que trava, o guia de VPS baratos mostra como é de verdade um self-host de 5 USD/mês. Comece com a Hermify quando quiser pular o encanamento de vez.