ntfy

O ntfy é um serviço simples de notificação pub-sub baseado em HTTP. Funciona com o servidor público gratuito em ntfy.sh ou com qualquer instância auto-hospedada, e aceita qualquer cliente capaz de fazer requisições HTTP — celulares, navegadores, scripts, relógios.

O ntfy é um ótimo canal de push leve para o Hermes: assine um tópico pelo aplicativo móvel do ntfy, mande mensagens para o tópico para conversar com o agente e receba a resposta de volta no celular.

Rode hermes gateway setup e escolha ntfy para um passo a passo guiado.

Pré-requisitos

• Um nome de tópico (qualquer string única — hermes-meunome-2026 serve)
• O aplicativo móvel do ntfy instalado e inscrito nesse tópico
• Opcional: um servidor ntfy auto-hospedado, ou um token de conta do ntfy.sh para tópicos privados/reservados

Só isso. Sem SDK, sem daemon, sem Node.js. O adaptador usa httpx, que já é uma dependência do Hermes.

Configure o Hermes

Pelo assistente de configuração

hermes gateway setup

Escolha ntfy e siga as instruções na tela.

Por variáveis de ambiente

Acrescente estas linhas ao ~/.hermes/.env:

NTFY_TOPIC=hermes-meunome-2026
NTFY_ALLOWED_USERS=hermes-meunome-2026
NTFY_HOME_CHANNEL=hermes-meunome-2026

Variável	Obrigatória	Descrição
NTFY_TOPIC	Sim	Tópico a assinar (mensagens de entrada)
NTFY_SERVER_URL	Opcional	URL do servidor (padrão: https://ntfy.sh) — aponte para um ntfy auto-hospedado para ter privacidade
NTFY_TOKEN	Opcional	Token bearer (por exemplo, tk_xyz) ou user:pass para autenticação Basic
NTFY_PUBLISH_TOPIC	Opcional	Tópico diferente para as respostas de saída (por padrão, o mesmo de NTFY_TOPIC)
NTFY_MARKDOWN	Opcional	Coloque true para enviar as respostas com o cabeçalho X-Markdown: true
NTFY_ALLOWED_USERS	Recomendada	Nomes de tópico permitidos, separados por vírgula (tratados como IDs de usuário; veja abaixo)
NTFY_ALLOW_ALL_USERS	Opcional	Coloque true para liberar todo publicador — só é seguro em tópicos privados com token de leitura
NTFY_HOME_CHANNEL	Opcional	Tópico padrão para entrega de cron e de notificações
NTFY_HOME_CHANNEL_NAME	Opcional	Rótulo legível para o canal principal

Modelo de identidade — leia antes de implantar

O ntfy não tem identidade nativa de usuário autenticado. O campo title de uma mensagem publicada é controlado por quem publica e pode conter qualquer coisa que o remetente quiser. O adaptador do Hermes NÃO usa o title para autorização — isso deixaria qualquer publicador que conheça o tópico se passar por um usuário permitido.

Em vez disso, o nome do tópico é a identidade. Toda mensagem publicada no tópico é tratada como vinda do mesmo usuário lógico (o tópico). Por isso, o NTFY_ALLOWED_USERS costuma ser só o próprio nome do tópico — uma lista de permissão de uma entrada só, que controla o canal inteiro.

Isso significa que qualquer pessoa que saiba o tópico consegue falar com o agente. Para transformar isso numa fronteira de confiança de verdade:

• Auto-hospede o ntfy e tranque o tópico com o controle de acesso. Só clientes autorizados, com o token de leitura/escrita, conseguem publicar.
• Ou use um tópico privado no ntfy.sh (tópicos reservados exigem conta) e proteja-o com um NTFY_TOKEN.
• Ou escolha um nome de tópico longo e impossível de adivinhar (hermes-7d4f9c8b-2026) e trate-o como segredo compartilhado. É a configuração mais leve, mas o nome do tópico vaza em qualquer log ou captura de tela.

Em todos os casos, não faça dados sensíveis passarem pelo ntfy a menos que o tópico por trás tenha controle de acesso.

Início rápido — fale com o seu agente pelo celular

1. Escolha um nome de tópico: hermes-meunome-2026
2. No celular: instale o aplicativo do ntfy, toque em + e digite hermes-meunome-2026
3. Na máquina que hospeda o agente:

   echo 'NTFY_TOPIC=hermes-meunome-2026' >> ~/.hermes/.env
   echo 'NTFY_ALLOWED_USERS=hermes-meunome-2026' >> ~/.hermes/.env
   hermes gateway restart

4. Pelo aplicativo do ntfy, mande uma mensagem para o tópico. A resposta do agente chega como notificação push.

Usar o ntfy com tarefas de cron

Depois que o NTFY_HOME_CHANNEL estiver definido, as tarefas de cron podem entregar no ntfy:

cronjob(
    action="create",
    schedule="every 1h",
    deliver="ntfy",          # usa NTFY_HOME_CHANNEL
    prompt="Verifique se há alertas e resuma."
)

Ou aponte explicitamente para um tópico específico pelo campo deliver: da tarefa de cron, ou de dentro de um script de shell com a CLI hermes send:

hermes send ntfy:alerts-channel "Pronto!"

Isso funciona mesmo quando o cron roda fora do processo do gateway — o plugin registra uma standalone_sender_fn que abre a própria conexão HTTP.

Auto-hospedar o ntfy

Se você quiser controle total:

# Docker
docker run -p 80:80 -it binwiederhier/ntfy serve

# Nativo
go install heckel.io/ntfy/v2@latest
ntfy serve

Depois aponte o Hermes para o seu servidor:

NTFY_SERVER_URL=https://ntfy.meudominio.com
NTFY_TOPIC=hermes
NTFY_TOKEN=tk_abc123  # se você tiver configurado controle de acesso

Auto-hospedar dá a você controle de acesso por tópico, políticas de persistência de mensagem, anexos e etiquetas de emoji. Veja a documentação do servidor ntfy.

Formatação markdown

Os clientes do ntfy renderizam markdown quando quem publica define o cabeçalho X-Markdown: true. Para ligar isso nas respostas de saída do Hermes:

NTFY_MARKDOWN=true

Ou no config.yaml:

platforms:
  ntfy:
    extra:
      markdown: true

O aplicativo móvel aceita um subconjunto do CommonMark — negrito, itálico, listas, links, blocos de código cercados. Veja a documentação de markdown do ntfy para o conjunto exato.

Configuração só de saída (notificações sem entrada)

Se você só quer que o Hermes empurre notificações para o ntfy (resumos de cron, alertas) e nunca aceite mensagens de volta, coloque o mesmo valor em NTFY_TOPIC e em NTFY_PUBLISH_TOPIC e não configure NTFY_ALLOWED_USERS. Sem lista de permissão, o agente nunca responde a mensagens de entrada — o celular recebe os pushes, mas a conversa é de mão única.

Limites

• Tamanho da mensagem: o ntfy limita o corpo da mensagem a 4096 caracteres. O Hermes trunca com um aviso quando isso é ultrapassado.
• Sem indicadores de digitação: o protocolo não expõe nenhum; o send_typing não faz nada.
• Sem tópicos de conversa nem anexos: o ntfy é notificação push pura. Respostas longas ficam no corpo da mensagem, sem desdobramento em thread.
• Sem identidade nativa de usuário: veja a seção sobre o modelo de identidade acima.

Resolução de problemas

Falha de autenticação / 401 — o NTFY_TOKEN está errado, ou o token não tem direito de publicar/assinar nesse tópico. O adaptador interrompe o laço de reconexão no 401 e o status de runtime do gateway vai mostrar fatal: ntfy_unauthorized. Corrija o token e reinicie o gateway.

Tópico não encontrado / 404 — o NTFY_TOPIC não existe no servidor configurado. No ntfy.sh, os tópicos são criados automaticamente na primeira publicação, então um 404 quer dizer que você está apontando para um servidor auto-hospedado que não tem o tópico provisionado. O adaptador interrompe o laço de reconexão com fatal: ntfy_topic_not_found.

Conectado, mas sem mensagens — confira se o NTFY_ALLOWED_USERS inclui o próprio nome do tópico. No modelo de identidade do ntfy, o tópico É o usuário; deixar a lista de permissão vazia rejeita tudo.

Reconexão a cada 60s — o keepalive padrão do fluxo é de 55s; o ntfy pode ter problemas intermitentes de rede. O adaptador aplica recuo exponencial (2 → 5 → 10 → 30 → 60s) e volta a 0 assim que um fluxo se mantém vivo por ≥60s.

---