Deploy Hermes - ntfy

Deploy and Host Hermes ntfy Agent on Railway

Hermes (Hermes ntfy Agent) is an AI agent framework designed to connect large language models to ntfy notification streams, leveraging OpenRouter for model inference while providing persistent agent memory, local caching, and flexible pub/sub topic management. This Railway template deploys hermes-ntfy from the OpenSource-Templates/Hermes repository, paired with a daily-backed persistent storage volume at /data.

About Hosting Hermes ntfy

Hosting Hermes ntfy on Railway deploys a single container service that runs the Hermes agent background subscriber daemon. It connects via SSE / HTTP streams to an ntfy server (NTFY_SERVER_URL, defaulting to https://ntfy.sh) on a specified topic (NTFY_TOPIC). AI model inference is delegated to OpenRouter via OPENROUTER_API_KEY. Persistent agent memory, context cache, and conversation state are safely retained inside a dedicated storage volume mounted at /data with daily automated backup scheduling.

Common Use Cases

• Push-based AI agent assistant: Send messages to a dedicated ntfy topic from any device, mobile app, or curl script, and receive intelligent responses directly back through ntfy push notifications.
• OpenRouter model access: Access top-tier open and proprietary language models (Claude, Llama, GPT-4o, Mistral) via OpenRouter API.
• Persistent agent memory: Retain conversation context, agent cache, and workspace memory across deployments in the /data volume.
• Self-hosted or public ntfy integration: Works seamlessly with public https://ntfy.sh or self-hosted ntfy server instances (NTFY_SERVER_URL), with optional authentication tokens (NTFY_TOKEN).
• Topic-based security: Protect access by subscribing to hard-to-guess topics and filtering authorized users (NTFY_ALLOWED_USERS).

Dependencies for Hermes ntfy Hosting

• Hermes Source: Repository OpenSource-Templates/Hermes (main branch)
• OpenRouter API Key: API token from OpenRouter (OPENROUTER_API_KEY)
• ntfy Topic Name: A unique, hard-to-guess topic string (e.g. hermes-yourname-x7k9) (NTFY_TOPIC)
• Authorized ntfy Users/Topics: Comma-separated user or topic IDs (NTFY_ALLOWED_USERS)
• One persistent volume mounted at /data with daily automated backups

Upstream: GitHub (OpenSource-Templates/Hermes) · ntfy Documentation

Implementation Details

Topology

Volumes (drives) — what to mount

Warning: Do not remove or detach the /data volume — deleting this volume will permanently wipe all stored agent memory, conversation cache, and workspace context during container redeployments.

Quick Start

1. Click the Deploy on Railway button above.
2. Sign in (or create a free Railway account).
3. Choose or configure an ntfy Topic:
   • Pick a unique, hard-to-guess topic name (e.g., hermes-alex-9k2x). On public ntfy.sh, anyone who knows the topic name can view messages unless a private/self-hosted ntfy instance or access token is used.
   • Optionally subscribe to this topic on your phone or browser using the ntfy web app or mobile apps.
4. Obtain your OpenRouter API Key:
   • Sign in to OpenRouter Keys and create a new API key.
5. Fill in the required variables during Railway template deployment:
   • OPENROUTER_API_KEY: Your OpenRouter API key.
   • NTFY_TOPIC: Your chosen ntfy topic name.
   • NTFY_ALLOWED_USERS: Usually set to the same string as NTFY_TOPIC (or a comma-separated list of allowed user/topic identifiers).
6. Click Deploy.
7. Monitor the deployment logs in Railway to confirm successful subscription to the ntfy server and connection to OpenRouter.

Configuration

Container-level choices defined in the template:

Security & Topic Management

• Topic Uniqueness (NTFY_TOPIC): Because public ntfy.sh topics are open by default, choose a long, cryptographically random topic name (e.g., hermes-user-8f3a1b2c) to prevent unauthorized users from discovering your interaction stream.
• Private ntfy Servers (NTFY_SERVER_URL & NTFY_TOKEN): For sensitive environments, point NTFY_SERVER_URL to a self-hosted ntfy instance and pass authentication tokens via NTFY_TOKEN.
• Agent Cache Tuning (AGENT_CACHE_MEMORY_HIGH_MB): Adjust AGENT_CACHE_MEMORY_HIGH_MB (default 750) based on your Railway service plan RAM allocation to prevent out-of-memory container restarts.

Updating Hermes ntfy

1. Open the hermes-ntfy service → Settings → Source.
2. Trigger a rebuild or update HERMES_IMAGE_VERSION variable to a specific release tag.
3. Click Redeploy.

All agent state and memory files inside /data remain safe across updates and container restarts.

Traps

Common pitfalls and failure modes:

• Public/Predictable NTFY_TOPIC Names — Using common topic names like hermes, test, or ai on public ntfy.sh will allow strangers to eavesdrop on conversations or publish prompts to your agent. Always use an unguessable topic string.
• Empty NTFY_ALLOWED_USERS Whitelist — If NTFY_ALLOWED_USERS does not match the incoming sender or topic identifier, the agent will filter out or ignore incoming messages.
• Self-Hosted ntfy Connection Failures — If using a custom NTFY_SERVER_URL, ensure the URL includes the protocol (e.g., https://ntfy.example.com) and that your server permits persistent SSE/WebSocket stream connections.
• Missing /data Volume Mount — If the persistent /data volume is detached, agent context, short-term memory, and conversation cache will reset every time Railway redeploys the container.

Why Deploy Hermes ntfy on Railway?

Railway provides automated background process execution with persistent volume backups and zero local infrastructure management. Hosting Hermes ntfy on Railway gives you an always-on, mobile-friendly AI assistant accessible via simple push notifications with automatic daily data backups.