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.