ntfy — Lightweight Push Notifications

Ever wished your phone could buzz you the moment a script finishes—without installing a single app? That’s the everyday magic of ntfy: it turns any topic into a pub-sub channel you can ping with a simple HTTP request.

For Hermes Agent users, ntfy is the easiest way to carry your AI agent in your pocket. No SDK, no daemon, no Node.js—just a topic name and the free ntfy mobile app. Here’s how to wire it up.

Why ntfy Fits Hermes Like a Glove

Hermes is all about lightweight automation. ntfy matches that philosophy perfectly:

• Zero dependencies — the adapter uses httpx, already bundled with Hermes.
• Any HTTP client works — curl, Python, even a smartwatch.
• Self-hostable — run your own ntfy server for private topics, or use the free public ntfy.sh.

You subscribe to a topic on your phone, send a message to that topic from Hermes, and get the reply as a notification. It’s push messaging without the bloat.

Quick Start: Setup Wizard

The fastest path is the guided setup:

hermes gateway setup

Pick ntfy from the menu, enter your topic name (e.g., hermes-myname-2026), and you’re done. The wizard writes the config to ~/.hermes/.env.

Manual Configuration via Environment Variables

Prefer editing files? Add these to ~/.hermes/.env:

NTFY_TOPIC=hermes-myname-2026
NTFY_ALLOWED_USERS=hermes-myname-2026
NTFY_HOME_CHANNEL=hermes-myname-2026

That’s the minimum. Here’s what each variable does:

Variable	Required	Purpose
NTFY_TOPIC	Yes	Topic to subscribe to (incoming messages)
NTFY_SERVER_URL	No	Default https://ntfy.sh; point to self-hosted for privacy
NTFY_TOKEN	No	Bearer token (tk_xyz) or user:pass for auth
NTFY_PUBLISH_TOPIC	No	Separate topic for replies (defaults to NTFY_TOPIC)
NTFY_MARKDOWN	No	Set true to send replies with X-Markdown: true
NTFY_ALLOWED_USERS	Recommended	Comma-separated topic names treated as user IDs
NTFY_ALLOW_ALL_USERS	No	Allow every publisher — only safe for private topics
NTFY_HOME_CHANNEL	No	Default topic for cron / notifications
NTFY_HOME_CHANNEL_NAME	No	Human label for the home channel

The Identity Model: Read This Before Deploying

Here’s the catch with ntfy: it has no real user accounts. The title field on a message is publisher-controlled—anyone can spoof it. So Hermes does not use title for authorization.

Instead, the topic name itself is the identity. Every message on the topic is treated as coming from the same logical user. NTFY_ALLOWED_USERS is usually just the topic name itself—a single-entry allowlist.

Security implication: anyone who knows your topic can talk to your agent. To make this a real trust boundary:

• Self-host ntfy and lock the topic down with Access Control.
• Only authorized clients can publish or subscribe.

A Practical Tip for Daily Use

Set NTFY_MARKDOWN=true if you want formatted replies (bold, lists, code blocks) rendered nicely in the ntfy app. It makes long agent responses much easier to scan on a phone screen.

Wrapping Up

ntfy gives Hermes a dead-simple push channel: subscribe on your phone, configure three environment variables, and you’re live. No cloud account, no extra services, no learning curve.

Final tip: start with a unique topic like hermes-<yourname>-<year>—it’s practically collision-proof on the public server. Then, once you trust the workflow, self-host ntfy and add access control for a truly private channel. Your agent is now one buzz away.