runvouch

A green run means the scheduler worked, not that the task got done. RunVouch alerts within minutes when a scheduled agent is missing, failed, looping, over budget, drifting, or reported success without evidence.

pip install runvouch     # or: npm install -g runvouch  (zero-dependency client + rv CLI)
rv agent nightly-report --cadence 24h --cap-run-cost 2 --evidence
rv run nightly-report --evidence-file out/report.html -- claude -p "build tonight's report"

Verifiable runs

Every finished run gets a sha256 record, every UTC day a Merkle root chained to the previous day and stamped in Bitcoin with OpenTimestamps. The day files are public at https://api.runvouch.com/proof/ and templates/verify_proof.py (stdlib only) checks a proof without our code. On every plan, Free included.

rv proof RUN_ID --verify     # recomputes leaf + Merkle path against the public day file, exit 0 or 1

Mechanism and limits: https://runvouch.com/docs/proof · who needs it: https://runvouch.com/verifiable-agent-runs

Detectors

Alert	Meaning
MISSED	expected run never started (dead scheduler, expired auth, crash before first line)
FAILED	run ended non-zero / status=fail
NO_EVIDENCE	run said ok but required proof (file written, URL 200, assertion) is missing, green ≠ done
RETRY_STORM	same tool + identical input ≥ N times in one run (the invisible loop that costs $437)
BUDGET_RUN / BUDGET_DAY	cost or tokens over the cap you set
DRIFT	duration / output size off its 7-run baseline (robust MAD), silently doing something else
STALLED	started, no end and no heartbeat past max runtime

Alerts go to e-mail, Telegram, Slack, any JSON webhook, PagerDuty (Team) and the dashboard.

Layout

runvouch/server.py            FastAPI + SQLite, all detectors, dashboard at /
runvouch/cli.py               `aw`, stdlib-only client: rv agent / rv run -- CMD / rv status / rv alerts
integrations/claude-code-plugin Claude Code plugin: SessionStart/PostToolUse/Stop hooks → RunVouch
integrations/mcp                MCP server (stdio): runvouch_status/alerts/ack/runs/run_start/run_end
site/index.html                 landing page
tests/                          7 detector tests (pytest)
docs/SELF_HOSTING.md            run it yourself: Docker or venv, what differs from hosted

Self-hosting

One process, one SQLite file, Docker or a venv. Full guide in docs/SELF_HOSTING.md (ten minutes, what differs from the hosted service, how to move later).

cp .env.example .env && docker compose up -d          # or: pip install -r requirements.txt && ./run.sh
curl -X POST "localhost:8787/admin/accounts?name=me&plan=team" -H "X-Admin-Token: $RUNVOUCH_ADMIN_TOKEN"   # -> api_key

Use

export RUNVOUCH_KEY=rv_... RUNVOUCH_URL=http://localhost:8787
rv agent nightly-report --cadence 24h --cap-run-cost 2 --evidence
rv run nightly-report --evidence-file out/report.html -- claude -p "build tonight's report"
rv status ; rv alerts

Claude Code plugin: see integrations/claude-code-plugin/README.md. MCP: claude mcp add runvouch -e RUNVOUCH_KEY=... -- python3 integrations/mcp/runvouch_mcp.py

Test and contribute

.venv/bin/pip install -r requirements-dev.txt && .venv/bin/python -m pytest -q tests

See CONTRIBUTING.md.

Hosted vs self-host

Hosted at runvouch.com: free for 3 agents, $9 Solo, $29 Team, alerts, dashboard, backups, EU hosting. Self-host: this repo, MIT. Same code.

Compare

vs Healthchecks.io · vs Cronitor · vs Langfuse

License

MIT.