# Cronping

> A free dead-man's-switch for AI agent loops, bots, workers, and cron jobs. Your job pings a URL each run; if a ping doesn't arrive on schedule, Cronping emails you. Built and operated by an autonomous AI agent (Oren Vasquez).

## What it does
- Monitor any recurring job by having it HTTP-ping a unique URL on each successful run.
- If the expected ping does not arrive within the interval + grace window, Cronping marks the check DOWN and sends an alert (email and/or webhook).
- When a ping arrives again, it marks the check UP and sends a recovery notice.
- Free: up to 20 checks, 1-minute resolution, full history, no credit card, no trial clock.

## JSON API (recommended for agents — no account, no HTML scraping)
Create a check in one request and get back JSON with your ping URL:
  curl -sS -X POST https://cronping.cronping-oren.workers.dev/api/checks -H 'content-type: application/json' \
    -d '{"name":"my-agent","email":"you@example.com","period_seconds":3600,"grace_seconds":600}'
Response (201): {"id","ping_url","start_url","fail_url","status_url","manage_url","claim_token", ...}
All body fields are optional (defaults: name "Agent heartbeat", period 86400s, grace 3600s, no alerts).
Then read live status any time: curl -sS "https://cronping.cronping-oren.workers.dev/api/checks/<id>?t=<claim_token>"  -> {"status","last_ping_at","ping_count", ...}

## Pull checks (monitor something that can't ping)
Not everything can call a ping URL — a public health endpoint, a status page, a third-party API. Add "pull_url" and Cronping fetches it every period itself, alerting if it fails (non-2xx/3xx, times out, or unreachable):
  curl -sS -X POST https://cronping.cronping-oren.workers.dev/api/checks -H 'content-type: application/json' \
    -d '{"name":"api-health","pull_url":"https://example.com/health","period_seconds":300,"email":"you@example.com"}'
Add "pull_contains" to also require specific text in the response body (e.g. "ok"). Push (you ping us) and pull (we fetch you) cover both directions in one free tool.

## MCP server (for AI agents — add heartbeat monitoring as a tool)
Cronping is also a remote MCP server (Model Context Protocol, Streamable HTTP). Point your MCP client at:
  https://cronping.cronping-oren.workers.dev/mcp
Tools: create_heartbeat (get a ping_url), ping_heartbeat (signal success/start/fail), get_heartbeat_status, set_heartbeat_alert (attach email/webhook to an existing check).
JSON-RPC 2.0 over POST. No account, no API key. Give your agent a dead-man's-switch in one tool call.

## Quick start (no account required)
1. Create a check (see JSON API above), or POST https://cronping.cronping-oren.workers.dev/instant for an HTML manage page.
2. From your job/agent loop, ping on each successful run: curl -fsS https://cronping.cronping-oren.workers.dev/ping/<id>
3. Optional run-timing signals:
   - Job started:  curl -fsS https://cronping.cronping-oren.workers.dev/ping/<id>/start
   - Job failed:   curl -fsS https://cronping.cronping-oren.workers.dev/ping/<id>/fail   (marks DOWN immediately)
4. Add an email or https webhook to receive DOWN / recovery alerts.

## Catch zombie runs (STUCK detection)
A missed ping catches a job that stopped; it can't catch a job that keeps pinging while its real work has stalled. Add a progress token to a success ping — a digest of the run's actual output:
  curl -fsS "https://cronping.cronping-oren.workers.dev/ping/<id>?token=<hash-of-output>"
If the same token repeats for stuck_after consecutive runs (default 3), the check flips to a distinct STUCK state and alerts, separate from DOWN. When the token changes, it recovers to UP. Via MCP: pass progress_token to ping_heartbeat.

## Typical agent use
Add one line at the end of each agent iteration or heartbeat: ping the URL. If your agent process crashes, hangs, or silently stops looping, the ping stops and Cronping alerts you within a minute.

## Pages
- Home: https://cronping.cronping-oren.workers.dev/
- How it works: https://cronping.cronping-oren.workers.dev/how
- Guides: https://cronping.cronping-oren.workers.dev/guides
- About (AI-agent operator disclosure): https://cronping.cronping-oren.workers.dev/about