better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/mattermost.md

@@ -0,0 +1,340 @@
+---
+sidebar_position: 8
+title: "Mattermost"
+description: "Set up Hermes Agent as a Mattermost bot"
+---
+
+# Mattermost Setup
+
+Hermes Agent integrates with Mattermost as a bot, letting you chat with your AI assistant through direct messages or team channels. Mattermost is a self-hosted, open-source Slack alternative — you run it on your own infrastructure, keeping full control of your data. The bot connects via Mattermost's REST API (v4) and WebSocket for real-time events, processes messages through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, file attachments, images, and slash commands.
+
+No external Mattermost library is required — the adapter uses `aiohttp`, which is already a Hermes dependency.
+
+Before setup, here's the part most people want to know: how Hermes behaves once it's in your Mattermost instance.
+
+## How Hermes Behaves
+
+| Context | Behavior |
+|---------|----------|
+| **DMs** | Hermes responds to every message. No `@mention` needed. Each DM has its own session. |
+| **Public/private channels** | Hermes responds when you `@mention` it. Without a mention, Hermes ignores the message. |
+| **Threads** | If `MATTERMOST_REPLY_MODE=thread`, Hermes replies in a thread under your message. Thread context stays isolated from the parent channel. |
+| **Shared channels with multiple users** | By default, Hermes isolates session history per user inside the channel. Two people talking in the same channel do not share one transcript unless you explicitly disable that. |
+
+:::tip
+If you want Hermes to reply as threaded conversations (nested under your original message), set `MATTERMOST_REPLY_MODE=thread`. The default is `off`, which sends flat messages in the channel.
+:::
+
+### Session Model in Mattermost
+
+By default:
+
+- each DM gets its own session
+- each thread gets its own session namespace
+- each user in a shared channel gets their own session inside that channel
+
+This is controlled by `config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+Set it to `false` only if you explicitly want one shared conversation for the entire channel:
+
+```yaml
+group_sessions_per_user: false
+```
+
+Shared sessions can be useful for a collaborative channel, but they also mean:
+
+- users share context growth and token costs
+- one person's long tool-heavy task can bloat everyone else's context
+- one person's in-flight run can interrupt another person's follow-up in the same channel
+
+This guide walks you through the full setup process — from creating your bot on Mattermost to sending your first message.
+
+## Step 1: Enable Bot Accounts
+
+Bot accounts must be enabled on your Mattermost server before you can create one.
+
+1. Log in to Mattermost as a **System Admin**.
+2. Go to **System Console** → **Integrations** → **Bot Accounts**.
+3. Set **Enable Bot Account Creation** to **true**.
+4. Click **Save**.
+
+:::info
+If you don't have System Admin access, ask your Mattermost administrator to enable bot accounts and create one for you.
+:::
+
+## Step 2: Create a Bot Account
+
+1. In Mattermost, click the **☰** menu (top-left) → **Integrations** → **Bot Accounts**.
+2. Click **Add Bot Account**.
+3. Fill in the details:
+   - **Username**: e.g., `hermes`
+   - **Display Name**: e.g., `Hermes Agent`
+   - **Description**: optional
+   - **Role**: `Member` is sufficient
+4. Click **Create Bot Account**.
+5. Mattermost will display the **bot token**. **Copy it immediately.**
+
+:::warning[Token shown only once]
+The bot token is only displayed once when you create the bot account. If you lose it, you'll need to regenerate it from the bot account settings. Never share your token publicly or commit it to Git — anyone with this token has full control of the bot.
+:::
+
+Store the token somewhere safe (a password manager, for example). You'll need it in Step 5.
+
+:::tip
+You can also use a **personal access token** instead of a bot account. Go to **Profile** → **Security** → **Personal Access Tokens** → **Create Token**. This is useful if you want Hermes to post as your own user rather than a separate bot user.
+:::
+
+## Step 3: Add the Bot to Channels
+
+The bot needs to be a member of any channel where you want it to respond:
+
+1. Open the channel where you want the bot.
+2. Click the channel name → **Add Members**.
+3. Search for your bot username (e.g., `hermes`) and add it.
+
+For DMs, simply open a direct message with the bot — it will be able to respond immediately.
+
+## Step 4: Find Your Mattermost User ID
+
+Hermes Agent uses your Mattermost User ID to control who can interact with the bot. To find it:
+
+1. Click your **avatar** (top-left corner) → **Profile**.
+2. Your User ID is displayed in the profile dialog — click it to copy.
+
+Your User ID is a 26-character alphanumeric string like `3uo8dkh1p7g1mfk49ear5fzs5c`.
+
+:::warning
+Your User ID is **not** your username. The username is what appears after `@` (e.g., `@alice`). The User ID is a long alphanumeric identifier that Mattermost uses internally.
+:::
+
+**Alternative**: You can also get your User ID via the API:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://your-mattermost-server/api/v4/users/me | jq .id
+```
+
+:::tip
+To get a **Channel ID**: click the channel name → **View Info**. The Channel ID is shown in the info panel. You'll need this if you want to set a home channel manually.
+:::
+
+## Step 5: Configure Hermes Agent
+
+### Option A: Interactive Setup (Recommended)
+
+Run the guided setup command:
+
+```bash
+hermes gateway setup
+```
+
+Select **Mattermost** when prompted, then paste your server URL, bot token, and user ID when asked.
+
+### Option B: Manual Configuration
+
+Add the following to your `~/.hermes/.env` file:
+
+```bash
+# Required
+MATTERMOST_URL=https://mm.example.com
+MATTERMOST_TOKEN=***
+MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
+
+# Multiple allowed users (comma-separated)
+# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e
+
+# Optional: reply mode (thread or off, default: off)
+# MATTERMOST_REPLY_MODE=thread
+
+# Optional: respond without @mention (default: true = require mention)
+# MATTERMOST_REQUIRE_MENTION=false
+
+# Optional: channels where bot responds without @mention (comma-separated channel IDs)
+# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2
+```
+
+Optional behavior settings in `~/.hermes/config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+- `group_sessions_per_user: true` keeps each participant's context isolated inside shared channels and threads
+
+### Start the Gateway
+
+Once configured, start the Mattermost gateway:
+
+```bash
+hermes gateway
+```
+
+The bot should connect to your Mattermost server within a few seconds. Send it a message — either a DM or in a channel where it's been added — to test.
+
+:::tip
+You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details.
+:::
+
+## Home Channel
+
+You can designate a "home channel" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it:
+
+### Using the Slash Command
+
+Type `/sethome` in any Mattermost channel where the bot is present. That channel becomes the home channel.
+
+### Manual Configuration
+
+Add this to your `~/.hermes/.env`:
+
+```bash
+MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn
+```
+
+Replace the ID with the actual channel ID (click the channel name → View Info → copy the ID).
+
+## Reply Mode
+
+The `MATTERMOST_REPLY_MODE` setting controls how Hermes posts responses:
+
+| Mode | Behavior |
+|------|----------|
+| `off` (default) | Hermes posts flat messages in the channel, like a normal user. |
+| `thread` | Hermes replies in a thread under your original message. Keeps channels clean when there's lots of back-and-forth. |
+
+Set it in your `~/.hermes/.env`:
+
+```bash
+MATTERMOST_REPLY_MODE=thread
+```
+
+## Mention Behavior
+
+By default, the bot only responds in channels when `@mentioned`. You can change this:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MATTERMOST_REQUIRE_MENTION` | `true` | Set to `false` to respond to all messages in channels (DMs always work). |
+| `MATTERMOST_FREE_RESPONSE_CHANNELS` | _(none)_ | Comma-separated channel IDs where the bot responds without `@mention`, even when require_mention is true. |
+
+To find a channel ID in Mattermost: open the channel, click the channel name header, and look for the ID in the URL or channel details.
+
+When the bot is `@mentioned`, the mention is automatically stripped from the message before processing.
+
+## Channel allowlist (`allowed_channels`)
+
+Restrict the bot to a fixed set of Mattermost channels. When set, the bot **only** responds in channels whose ID appears in the list — messages from any other channel are silently ignored, even if the bot is `@mentioned`.
+
+**DMs are exempt** from this filter, so authorized users can always reach the bot in a direct message.
+
+```yaml
+mattermost:
+  allowed_channels:
+    - "abc123def456ghi789jkl012mno"   # #ops
+    - "xyz987uvw654rst321opq098nml"   # #incident-response
+```
+
+Or via env var (comma-separated):
+
+```bash
+MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"
+```
+
+Behavior:
+
+- Empty / unset → no restriction (fully backward compatible).
+- Non-empty → channel ID must be on the list, or the message is dropped before any other gating (mention requirement, `MATTERMOST_FREE_RESPONSE_CHANNELS`, etc.) runs.
+- Find a channel ID via the Mattermost UI → channel header → "View Info", or read it from the channel URL.
+
+See also: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split).
+
+## Troubleshooting
+
+### Bot is not responding to messages
+
+**Cause**: The bot is not a member of the channel, or `MATTERMOST_ALLOWED_USERS` doesn't include your User ID.
+
+**Fix**: Add the bot to the channel (channel name → Add Members → search for the bot). Verify your User ID is in `MATTERMOST_ALLOWED_USERS`. Restart the gateway.
+
+### 403 Forbidden errors
+
+**Cause**: The bot token is invalid, or the bot doesn't have permission to post in the channel.
+
+**Fix**: Check that `MATTERMOST_TOKEN` in your `.env` file is correct. Make sure the bot account hasn't been deactivated. Verify the bot has been added to the channel. If using a personal access token, ensure your account has the required permissions.
+
+### WebSocket disconnects / reconnection loops
+
+**Cause**: Network instability, Mattermost server restarts, or firewall/proxy issues with WebSocket connections.
+
+**Fix**: The adapter automatically reconnects with exponential backoff (2s → 60s). Check your server's WebSocket configuration — reverse proxies (nginx, Apache) need WebSocket upgrade headers configured. Verify no firewall is blocking WebSocket connections on your Mattermost server.
+
+For nginx, ensure your config includes:
+
+```nginx
+location /api/v4/websocket {
+    proxy_pass http://mattermost-backend;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 600s;
+}
+```
+
+### "Failed to authenticate" on startup
+
+**Cause**: The token or server URL is incorrect.
+
+**Fix**: Verify `MATTERMOST_URL` points to your Mattermost server (include `https://`, no trailing slash). Check that `MATTERMOST_TOKEN` is valid — try it with curl:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://your-server/api/v4/users/me
+```
+
+If this returns your bot's user info, the token is valid. If it returns an error, regenerate the token.
+
+### Bot is offline
+
+**Cause**: The Hermes gateway isn't running, or it failed to connect.
+
+**Fix**: Check that `hermes gateway` is running. Look at the terminal output for error messages. Common issues: wrong URL, expired token, Mattermost server unreachable.
+
+### "User not allowed" / Bot ignores you
+
+**Cause**: Your User ID isn't in `MATTERMOST_ALLOWED_USERS`.
+
+**Fix**: Add your User ID to `MATTERMOST_ALLOWED_USERS` in `~/.hermes/.env` and restart the gateway. Remember: the User ID is a 26-character alphanumeric string, not your `@username`.
+
+## Per-Channel Prompts
+
+Assign ephemeral system prompts to specific Mattermost channels. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately.
+
+```yaml
+mattermost:
+  channel_prompts:
+    "channel_id_abc123": |
+      You are a research assistant. Focus on academic sources,
+      citations, and concise synthesis.
+    "channel_id_def456": |
+      Code review mode. Be precise about edge cases and
+      performance implications.
+```
+
+Keys are Mattermost channel IDs (find them in the channel URL or via the API). All messages in the matching channel get the prompt injected as an ephemeral system instruction.
+
+## Security
+
+:::warning
+Always set `MATTERMOST_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.
+:::
+
+For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md).
+
+## Notes
+
+- **Self-hosted friendly**: Works with any self-hosted Mattermost instance. No Mattermost Cloud account or subscription required.
+- **No extra dependencies**: The adapter uses `aiohttp` for HTTP and WebSocket, which is already included with Hermes Agent.
+- **Team Edition compatible**: Works with both Mattermost Team Edition (free) and Enterprise Edition.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/msgraph-webhook.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 23
+title: "Microsoft Graph Webhook Listener"
+description: "Receive Microsoft Graph change notifications (meetings, calendar, chat, etc.) in Hermes"
+---
+
+# Microsoft Graph Webhook Listener
+
+The `msgraph_webhook` gateway platform is an inbound event listener. It's how Hermes receives **change notifications** from Microsoft Graph — "a Teams meeting ended," "a new message landed in this chat," "this calendar event was updated." Different from the `teams` platform (which is a chat bot users type to) — this one is M365 telling Hermes something happened, not a person.
+
+Right now the primary consumer is the Teams meeting summary pipeline: Graph notifies when a meeting produces a transcript, the pipeline fetches it, and Hermes posts a summary back into Teams. Other Graph resources (`/chats/.../messages`, `/users/.../events`) use the same listener — the pipeline consumers land with their own PRs.
+
+## Prerequisites
+
+- Microsoft Graph application credentials — [Register a Microsoft Graph Application](/guides/microsoft-graph-app-registration)
+- A **public HTTPS URL** that Microsoft Graph can reach (Graph does not call private endpoints). A dev tunnel works for testing; production needs a real domain with a valid certificate.
+- A strong shared secret to use as the `clientState` value. Generate with `openssl rand -hex 32` and put it in `~/.hermes/.env` as `MSGRAPH_WEBHOOK_CLIENT_STATE`.
+
+## Quick Start
+
+Minimum `~/.hermes/config.yaml`:
+
+```yaml
+platforms:
+  msgraph_webhook:
+    enabled: true
+    extra:
+      host: 127.0.0.1
+      port: 8646
+      client_state: "replace-with-a-strong-secret"
+      accepted_resources:
+        - "communications/onlineMeetings"
+```
+
+Or via env vars in `~/.hermes/.env` (auto-merged on startup):
+
+```bash
+MSGRAPH_WEBHOOK_ENABLED=true
+MSGRAPH_WEBHOOK_PORT=8646
+MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openssl-rand-hex-32>
+MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
+```
+
+Note: the bind host is read from `extra.host` in `config.yaml` (see the example above); there is no `MSGRAPH_WEBHOOK_HOST` env-var override.
+
+Start the gateway: `hermes gateway run`. The listener exposes:
+
+- `POST /msgraph/webhook` — change notifications from Graph
+- `GET /msgraph/webhook?validationToken=...` — Graph subscription validation handshake
+- `GET /health` — readiness probe with accepted/duplicate counters
+
+Expose the listener publicly (reverse proxy, dev tunnel, ingress). Your notification URL for Graph subscriptions is your public HTTPS origin followed by `/msgraph/webhook`:
+
+```
+https://ops.example.com/msgraph/webhook
+```
+
+## Configuration
+
+All settings go under `platforms.msgraph_webhook.extra`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `host` | unset (dual-stack: all interfaces, IPv4+IPv6) | Bind address for the HTTP listener. Non-loopback binds require `allowed_source_cidrs`; loopback (`127.0.0.1` / `::1`) is the easiest dev-tunnel / reverse-proxy setup. |
+| `port` | `8646` | Bind port. |
+| `webhook_path` | `/msgraph/webhook` | URL path Graph POSTs to. |
+| `health_path` | `/health` | Readiness endpoint. |
+| `client_state` | — | Shared secret Graph echoes in every notification. Compared with `hmac.compare_digest` — generate with `openssl rand -hex 32`. |
+| `accepted_resources` | `[]` (accept all) | Allowlist of Graph resource paths/patterns. Trailing `*` acts as prefix match. Leading `/` is tolerated. Example: `["communications/onlineMeetings", "chats/*/messages"]`. |
+| `max_seen_receipts` | `5000` | Dedupe cache size for notification IDs. Oldest entries evicted when the cap is hit. |
+| `allowed_source_cidrs` | `[]` | Required for non-loopback binds. Leave empty only when the listener is bound to loopback and fronted by a local tunnel / reverse proxy. |
+
+Most settings also have an equivalent env var (`MSGRAPH_WEBHOOK_*`) that merges into the config at gateway startup (the exception is `host`, which is config-only — see the note above) — see the [environment variables reference](/reference/environment-variables#microsoft-graph-teams-meetings).
+
+## Security Hardening
+
+### clientState is the primary auth check
+
+Every Graph notification includes the `clientState` string your subscription registered with. The listener rejects any notification whose `clientState` doesn't match, using timing-safe comparison. This is Microsoft's documented mechanism — treat the value as a strong shared secret.
+
+If `client_state` is unset, the listener refuses to start.
+
+### Source-IP allowlisting (production deployments)
+
+For production, restrict the listener to Microsoft's published Graph webhook source IP ranges. Microsoft documents the egress ranges under the [Office 365 IP Address and URL Web service](https://learn.microsoft.com/en-us/microsoft-365/enterprise/urls-and-ip-address-ranges). Configure them as:
+
+```yaml
+platforms:
+  msgraph_webhook:
+    enabled: true
+    extra:
+      host: 0.0.0.0
+      client_state: "..."
+      allowed_source_cidrs:
+        - "52.96.0.0/14"
+        - "52.104.0.0/14"
+        # ...add the current Microsoft 365 "Common" + "Teams" category egress ranges
+```
+
+Or as an env var:
+
+```bash
+MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"
+```
+
+Binding a non-loopback host such as `0.0.0.0`, `::`, or a LAN IP without `allowed_source_cidrs` is refused at startup. If you're using a dev tunnel or reverse proxy on the same machine, bind Hermes to `127.0.0.1` or `::1` and leave the allowlist empty there. Invalid CIDR strings log a warning and are ignored. **Review the Microsoft IP list quarterly** — it changes.
+
+### HTTPS termination
+
+The listener speaks plain HTTP. Terminate TLS at your reverse proxy (Caddy, Nginx, Cloudflare Tunnel, AWS ALB) and proxy to the listener over the local network. Graph refuses to deliver to non-HTTPS endpoints, so there's no path for unencrypted traffic to reach you from Graph itself.
+
+### Response hygiene
+
+On success the listener returns `202 Accepted` with an empty body — internal counters stay out of the wire response. Operators can observe counts via `/health`, which is guarded by the same source-IP rules as the webhook path.
+
+Status code table:
+
+| Outcome | Status |
+|---------|--------|
+| Notification(s) accepted or deduped | 202 |
+| Validation handshake (GET with `validationToken`) | 200 (echoes the token) |
+| Every item in batch failed clientState | 403 |
+| Malformed JSON / missing `value` array / unknown resource | 400 |
+| Source IP not in allowlist | 403 |
+| Bare GET without `validationToken` | 400 |
+
+## Troubleshooting
+
+| Problem | What to check |
+|---------|---------------|
+| Graph subscription validation fails | Public URL is reachable, `/msgraph/webhook` path matches, GET with `validationToken` echoes the token verbatim as `text/plain` within 10 seconds. |
+| Notifications POST but nothing ingests | `client_state` matches what you registered the subscription with. Re-run `openssl rand -hex 32` and create a new subscription if the value drifted. Check `accepted_resources` includes the resource path Graph is sending. |
+| Every notification 403s | `clientState` mismatch (forged, or subscription registered with a different value). Re-create the subscription with `hermes teams-pipeline subscribe --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE" ...` (ships with the pipeline runtime PR). |
+| Listener refuses to start on `0.0.0.0` | Set `allowed_source_cidrs` to Microsoft's current webhook egress ranges, or bind Hermes to `127.0.0.1` / `::1` behind your tunnel or reverse proxy. |
+| Listener starts but `curl http://localhost:8646/health` hangs | Port binding collision. Check `ss -tlnp \| grep 8646` and change `port:` if needed. |
+| Real Graph requests from Microsoft get 403'd | Source IP allowlist is too narrow. Widen the list to include the current Microsoft egress ranges. If you're still validating the tunnel path, bind Hermes to loopback and let the tunnel handle public exposure. |
+
+## Related Docs
+
+- [Register a Microsoft Graph Application](/guides/microsoft-graph-app-registration) — Azure app registration prereq
+- [Environment Variables → Microsoft Graph](/reference/environment-variables#microsoft-graph-teams-meetings) — full env var list
+- [Microsoft Teams bot setup](/user-guide/messaging/teams) — the different platform that lets users chat with Hermes in Teams

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/ntfy.md

@@ -0,0 +1,157 @@
+# ntfy
+
+[ntfy](https://ntfy.sh/) is a simple HTTP-based pub-sub notification service. It works with the free public server at `ntfy.sh` or any self-hosted instance, and supports any client that can make HTTP requests — phones, browsers, scripts, watches.
+
+ntfy makes a great lightweight push channel for Hermes: subscribe to a topic from the [ntfy mobile app](https://ntfy.sh/docs/subscribe/phone/), send messages to the topic to talk to the agent, get the response back on your phone.
+
+> Run `hermes gateway setup` and pick **ntfy** for a guided walk-through.
+
+## Prerequisites
+
+- A topic name (any unique string — `hermes-myname-2026` works fine)
+- The [ntfy mobile app](https://ntfy.sh/docs/subscribe/phone/) installed and subscribed to that topic
+- Optional: a self-hosted ntfy server, or an `ntfy.sh` account token for private/reserved topics
+
+That's it. No SDK, no daemon, no Node.js. The adapter uses `httpx` which is already a Hermes dependency.
+
+## Configure Hermes
+
+### Via setup wizard
+
+```bash
+hermes gateway setup
+```
+
+Select **ntfy** and follow the prompts.
+
+### Via environment variables
+
+Add these to `~/.hermes/.env`:
+
+```
+NTFY_TOPIC=hermes-myname-2026
+NTFY_ALLOWED_USERS=hermes-myname-2026
+NTFY_HOME_CHANNEL=hermes-myname-2026
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `NTFY_TOPIC` | Yes | Topic to subscribe to (incoming messages) |
+| `NTFY_SERVER_URL` | Optional | Server URL (default: `https://ntfy.sh`) — point to a self-hosted ntfy for privacy |
+| `NTFY_TOKEN` | Optional | Bearer token (e.g. `tk_xyz`) or `user:pass` for Basic auth |
+| `NTFY_PUBLISH_TOPIC` | Optional | Different topic for outgoing replies (defaults to `NTFY_TOPIC`) |
+| `NTFY_MARKDOWN` | Optional | Set `true` to send replies with `X-Markdown: true` header |
+| `NTFY_ALLOWED_USERS` | Recommended | Comma-separated topic names allowed (treated as user IDs; see below) |
+| `NTFY_ALLOW_ALL_USERS` | Optional | Set `true` to allow every publisher — only safe for private topics with read tokens |
+| `NTFY_HOME_CHANNEL` | Optional | Default topic for cron / notification delivery |
+| `NTFY_HOME_CHANNEL_NAME` | Optional | Human label for the home channel |
+
+## Identity model — read this before deploying
+
+ntfy has no native authenticated user identity. The `title` field on a published message is **publisher-controlled** and can be anything the sender wants. The Hermes adapter does NOT use `title` for authorization — it would let any publisher who knows the topic spoof an allowed user.
+
+Instead, **the topic name itself is the identity**. Every message published to the topic is treated as coming from the same logical user (the topic). `NTFY_ALLOWED_USERS` is therefore typically just the topic name itself — a single-entry allowlist that gates the whole channel.
+
+This means **anyone who knows the topic can talk to the agent**. To make that a real trust boundary:
+
+- **Self-host ntfy** and lock the topic down with [Access Control](https://docs.ntfy.sh/config/#access-control). Only authorized clients with the read/write token can publish.
+- Or **use a private topic on ntfy.sh** ([reserved topics](https://docs.ntfy.sh/publish/#reserved-topics) require an account) and protect it with a `NTFY_TOKEN`.
+- Or **pick a long, unguessable topic name** (`hermes-7d4f9c8b-2026`) and treat it as the shared secret. This is the lightest setup but the topic name leaks via any logs or screenshots.
+
+In all cases, do not put sensitive data through ntfy unless the underlying topic is access-controlled.
+
+## Quick start — talk to your agent from your phone
+
+1. Pick a topic name: `hermes-myname-2026`
+2. On your phone: install the [ntfy app](https://ntfy.sh/docs/subscribe/phone/), tap **+**, enter `hermes-myname-2026`
+3. On the host:
+   ```bash
+   echo 'NTFY_TOPIC=hermes-myname-2026' >> ~/.hermes/.env
+   echo 'NTFY_ALLOWED_USERS=hermes-myname-2026' >> ~/.hermes/.env
+   hermes gateway restart
+   ```
+4. From the ntfy app, send a message to the topic. The agent's reply lands as a push notification.
+
+## Using ntfy with cron jobs
+
+Once `NTFY_HOME_CHANNEL` is set, cron jobs can deliver to ntfy:
+
+```python
+cronjob(
+    action="create",
+    schedule="every 1h",
+    deliver="ntfy",          # uses NTFY_HOME_CHANNEL
+    prompt="Check for alerts and summarise."
+)
+```
+
+Or target a specific topic explicitly via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
+
+```bash
+hermes send ntfy:alerts-channel "Done!"
+```
+
+This works even when the cron runs out-of-process from the gateway — the plugin registers a `standalone_sender_fn` that opens its own HTTP connection.
+
+## Self-hosting ntfy
+
+If you want full control:
+
+```bash
+# Docker
+docker run -p 80:80 -it binwiederhier/ntfy serve
+
+# Native
+go install heckel.io/ntfy/v2@latest
+ntfy serve
+```
+
+Then point Hermes at it:
+
+```
+NTFY_SERVER_URL=https://ntfy.mydomain.com
+NTFY_TOPIC=hermes
+NTFY_TOKEN=tk_abc123  # if you've set up access control
+```
+
+Self-hosting gives you topic access control, message persistence policies, attachments, and emoji tags. See the [ntfy server docs](https://docs.ntfy.sh/install/).
+
+## Markdown formatting
+
+ntfy clients render markdown when the publisher sets the `X-Markdown: true` header. To enable for outgoing Hermes replies:
+
+```
+NTFY_MARKDOWN=true
+```
+
+Or in `config.yaml`:
+
+```yaml
+platforms:
+  ntfy:
+    extra:
+      markdown: true
+```
+
+The mobile app supports a subset of CommonMark — bold, italic, lists, links, fenced code blocks. See [ntfy's markdown docs](https://docs.ntfy.sh/publish/#markdown-formatting) for the exact set.
+
+## Outgoing-only setup (notifications without inbound)
+
+If you only want Hermes to *push* notifications to ntfy (cron summaries, alerts) and never accept messages back, set both `NTFY_TOPIC` and `NTFY_PUBLISH_TOPIC` to the same value and skip `NTFY_ALLOWED_USERS` entirely. With no allowlist, the agent never responds to inbound messages — your phone gets the pushes, but the conversation is one-way.
+
+## Limits
+
+- **Message size**: ntfy caps message bodies at 4096 chars. Hermes truncates with a warning when this is exceeded.
+- **No typing indicators**: the protocol doesn't expose one; `send_typing` is a no-op.
+- **No threads or attachments**: ntfy is plain push notifications. Long replies stay in the message body, no thread fanout.
+- **No native user identity**: see the identity-model section above.
+
+## Troubleshooting
+
+**Auth failure / 401** — `NTFY_TOKEN` is wrong, or the token doesn't have publish/subscribe rights on this topic. The adapter halts its reconnect loop on 401 and the gateway runtime status will show `fatal: ntfy_unauthorized`. Fix the token and restart the gateway.
+
+**Topic not found / 404** — `NTFY_TOPIC` doesn't exist on the configured server. For ntfy.sh, topics are auto-created on first publish, so a 404 means you're pointed at a self-hosted server that doesn't have the topic provisioned. The adapter halts its reconnect loop with `fatal: ntfy_topic_not_found`.
+
+**Connected but no messages** — Check that `NTFY_ALLOWED_USERS` includes the topic name itself. With ntfy's identity model, the topic IS the user; leaving the allowlist empty rejects everything.
+
+**Reconnects every 60s** — The stream keepalive default is 55s; ntfy may have intermittent network issues. The adapter applies exponential backoff (2 → 5 → 10 → 30 → 60s) and resets to 0 once a stream stays alive ≥60s.