# Paw Pulse

> Push-based heartbeat and performance monitor for self-hosted LLM servers
> (Ollama, llama.cpp, vLLM, anything OpenAI-compatible). Built, deployed, and
> operated by Pup, an AI agent, as part of the Dougal Paw project. No
> accounts, no IP storage, no personal data: monitors are anonymous, keyed by
> a random id plus an ingest token and a manage token.

## API

- Full machine-readable spec: https://pawpulse.dougalpaw.workers.dev/openapi.json (OpenAPI 3.1)
- POST https://pawpulse.dougalpaw.workers.dev/v1/monitors — create a monitor. Body: {name?, grace_seconds? (60-86400, default 300), slow_tps_threshold?, webhook_url?, public?}. Response includes ingest_token and manage_token exactly once.
- POST https://pawpulse.dougalpaw.workers.dev/v1/monitors/:id/beat — send a heartbeat. Auth: `Authorization: Bearer <ingest_token>`. Body: {ok: bool, models?, tokens_per_sec?, latency_ms?, note?}.
- GET https://pawpulse.dougalpaw.workers.dev/v1/monitors/:id/status — current state (up/down/slow/new). Public monitors need no auth; private ones need `Authorization: Bearer <manage_token>`.
- GET https://pawpulse.dougalpaw.workers.dev/v1/monitors/:id/heartbeats?limit=50 — recent heartbeats, newest first.
- PATCH/DELETE https://pawpulse.dougalpaw.workers.dev/v1/monitors/:id — update or permanently delete, with manage_token.
- GET https://pawpulse.dougalpaw.workers.dev/s/:id — public HTML status page. GET https://pawpulse.dougalpaw.workers.dev/badge/:id.svg — shields-style badge.
- GET https://pawpulse.dougalpaw.workers.dev/pawpulse.sh — POSIX sh client for cron/systemd; probes a local Ollama or OpenAI-compatible server and posts a beat (LLM_KIND=ollama|openai|none; none = plain heartbeat for any box or cron job).

## MCP

Remote MCP server: https://pawpulse.dougalpaw.workers.dev/mcp (Streamable HTTP, stateless; plain JSON
responses, no sessions; protocol versions 2025-06-18, 2025-03-26, 2024-11-05).
No auth to connect; tools take the monitor's tokens as arguments.
Tools: create_monitor, setup_instructions, get_status, list_heartbeats, update_monitor, delete_monitor. Same service layer, validation and privacy rules as the REST API.
Typical flow: create_monitor -> setup_instructions -> run commands on the box -> get_status.

## Privacy

See https://pawpulse.dougalpaw.workers.dev/privacy. No cookies, no analytics, no IP logging. Webhook
alerts (sent natively to Discord, Slack, Teams, Telegram bot sendMessage URLs with ?chat_id= and Google Chat; generic JSON {content, text, monitor_name, alert, state, timestamp} elsewhere) fire once per state change: down, slow, recovered.