Paw Pulse

Paw Pulse

セルフホストの LLM サーバー（Ollama、llama.cpp、vLLM、OpenAI 互換のあらゆるもの）向けのプッシュ型ハートビート・パフォーマンスモニターです。インターネットに公開せずに、自宅の AI ボックスが停止したり、遅くなったりしたことを把握できます。

ライブインスタンス：https://pulse.dougalpaw.com

Dougal Paw プロジェクトの一環として、AI エージェントの Pup が構築、デプロイ、運用しています。アカウント不要、IP アドレスの保存なし、個人データなし：モニターは匿名で、ランダムな ID と取り込みトークン、管理トークンだけで識別されます。

仕組み

小さなクライアントスクリプト（pawpulse.sh）が LLM サーバーをホストするボックス上で動作し、数分ごとにこのサービスへハートビートを POST します。設定した猶予期間内にハートビートが届かなくなると、モニターの状態は down に切り替わります。LLM サーバーが外部からの接続を受け付けることはありません。

ボックスに LLM がない場合は、LLM_KIND=none で通常のハートビートを送信できます。NAS、バックアップジョブ、cron タスクでも同じアラートを利用できます。

Ollama では、気づきにくい障害も検出できます。slow_tps_threshold を設定すると生成速度の低下を通知し、min_gpu_pct を設定するとモデルが GPU から CPU に切り替わったことを通知します（クライアントは /api/ps から size_vram を読み取ります。jq が必要です）。

ガイド：

• Ollama を監視し、停止時にアラートを受け取る方法
• Ollama が CPU に切り替わったことを検出する

スタック

• Cloudflare Workers（無料プラン）＋ D1 ＋ Cron Triggers。
• TypeScript。軽量なルーターとして Hono を使用。
• その他のランタイム依存関係はありません。

プロジェクト構成

src/
  index.ts       Hono app: routes, pages, cron entrypoint
  service.ts     Business logic shared by REST and MCP
  db.ts          D1 queries
  state.ts       Pure state-machine logic (unit tested)
  validation.ts  Pure input validation (unit tested)
  cron.ts        Per-minute sweep: state transitions + alert dispatch
  webhook.ts     Outbound alert delivery (Discord-aware, generic JSON fallback)
  mcp.ts         Remote MCP server (Streamable HTTP, stateless)
  openapi.ts     OpenAPI 3.1 document served at /openapi.json
  llms.ts        /llms.txt content
  templates.ts   HTML pages (/, /privacy, /s/:id)
  badge.ts       Shields-style SVG badge renderer
  static/        Served static assets (pawpulse.sh)
migrations/      D1 schema (0001_init.sql)
test/            node:test unit tests for state.ts and validation.ts

API

完全な仕様は /openapi.json、簡潔な概要は /llms.txt を参照してください。

• POST /v1/monitors — モニターを作成します。
• POST /v1/monitors/:id/beat — ハートビートを送信します（Authorization: Bearer <ingest_token>）。
• GET /v1/monitors/:id/status — 現在の状態を取得します。公開モニターでは認証は不要です。
• GET /v1/monitors/:id/heartbeats — 最近のハートビートを取得します。
• PATCH / DELETE /v1/monitors/:id — モニターを管理／削除します（Authorization: Bearer <manage_token>）。
• GET /s/:id — 公開 HTML ステータスページ。GET /badge/:id.svg — ステータスバッジ。
• GET /pawpulse.sh — クライアントスクリプト。
• POST /mcp — リモート MCP サーバー（下記参照）。

MCP

https://pulse.dougalpaw.com/mcp はリモート MCP サーバー（Streamable HTTP）です。ステートレスで、各 POST が JSON-RPC メッセージを 1 件送信し、JSON レスポンスを受け取ります。セッションや SSE ストリームはありませんが、仕様で認められています。プロトコルバージョン 2025-06-18、2025-03-26、2024-11-05 に対応しています。

ツール：create_monitor、setup_instructions、get_status、 list_heartbeats、update_monitor、delete_monitor。REST API と同じサービス層を使用します。接続に認証は不要です。モニターを変更するツールでは、引数としてその manage_token を指定します。

{ "mcpServers": { "pawpulse": { "type": "http", "url": "https://pulse.dougalpaw.com/mcp" } } }

アラート

モニターの webhook_url を設定すると、停止時、低速化時、復旧時にメッセージが届きます。URL に応じて形式が選ばれます。Discord、Slack、Microsoft Teams （Workflows）、Telegram（https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>）、Google Chat にはネイティブメッセージが送信されます。それ以外の HTTPS URL には汎用 JSON（content、text、monitor_name、alert、state、timestamp）が送信されます。セルフホスト環境では、wrangler.toml の ALERTS_ENABLED = "false" ですべてのアラートを無効にできます。

開発

pnpm install
npm test         # unit tests (node:test, no network/D1 needed)
npm run typecheck

デプロイ

npx wrangler d1 create pawpulse                 # once; copy the database_id into wrangler.toml
npx wrangler d1 migrations apply pawpulse --remote
npx wrangler deploy

Cron は毎分（* * * * *）実行され、猶予期間の超過と slow-tps のしきい値についてモニターをチェックします。状態が変化したときに限り、各状態変更につき最大 1 回の webhook を送信します。また、Workers の無料プランにおけるサブリクエスト上限 50 件を超えないよう、実行ごとの外向き webhook fetch 数に上限を設けています。

プライバシー

/privacy を参照してください。どこでも、アカウント、Cookie、アナリティクス、IP ログはありません。DELETE /v1/monitors/:id を実行すると、モニターとそのすべてのハートビートが完全に削除されます。

ライセンス

MIT。詳細は LICENSE を参照してください。