Docs › systemd timer monitoring with RunVouch
systemd timer monitoring with RunVouch
systemd timer monitoring from outside the machine: a timer that fires a failing service shows up in systemctl --failed and nowhere else. A timer that never fires (unit disabled, machine asleep, Persistent missing) shows up nowhere at all.
How it runs on systemd timers
The timer starts a .service; wrap that service's ExecStart. Works for system units and systemctl --user units.
Store the key
Put RUNVOUCH_KEY=rv_... in a file with mode 600 and reference it with EnvironmentFile=; do not put the key in the unit file itself, which is world-readable.
Wrap the job
# ~/.config/systemd/user/nightly-report.service [Service] Type=oneshot EnvironmentFile=%h/.config/runvouch.env ExecStart=%h/.local/bin/rv run nightly-report --evidence-file %h/out/report.html -- %h/bin/report.sh # ~/.config/systemd/user/nightly-report.timer [Timer] OnCalendar=*-*-* 02:00 Persistent=true [Install] WantedBy=timers.target
rv fails open: if RunVouch is unreachable the job still runs and you get one warning line.
Register the cadence and caps
rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2
Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.
What goes silent on systemd timers
- Without
Persistent=truea timer that was due while the machine was off is simply skipped. OnFailure=can start a notifier unit, but only on non-zero exit; a script that exits 0 with no output is never a failure to systemd.- User timers stop when the user session ends unless
loginctl enable-lingeris set; MISSED tells you the same evening, not when you next log in.
What systemd timers does not tell you
systemctl list-timers shows the next and last trigger, and journalctl -u holds the output, but systemd sends nothing anywhere. OnFailure= can start a second unit, and only when the service exits non-zero. A oneshot that exits 0 after writing an empty file, a timer whose unit was masked during an upgrade, or a user timer that stopped when the session ended (no loginctl enable-linger) produces no signal you will see without logging in.
What RunVouch detects
| Alert | What it means here |
|---|---|
| MISSED | cadence plus grace passed and no run started |
| FAILED | non-zero exit or a reported failure, with the stderr excerpt |
| NO_EVIDENCE | the run said ok but the file, URL or assertion you required is missing |
| STALLED | a run started and never ended within max runtime |
| RETRY_STORM | the same tool called with identical input many times in one run |
| BUDGET_RUN / BUDGET_DAY | cost cap crossed; the agent is paused until you resume it |
| DRIFT | duration or output size far off its 7-run baseline |
Set up in two minutes
- Get a free key (3 agents, no card) and store it where this page says.
- wrap the job: copy the snippet above into the scheduled job.
- Register the cadence once:
rv agent nightly-report --cadence 24h --grace 30m --evidence, or let the first run create the agent and set the cadence on the dashboard. - Send one test alert:
curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY". The next missed, failed or empty run reaches the same channels.
Also running schedulers?
GitLab CI scheduled pipelines. Jenkins. Heroku Scheduler. Claude Code scheduled tasks. The full list of runtimes is on integrations, and the same agent can report from several of them: one job, one cadence, wherever it happens to run.
Need a key? Get a free key · Stuck? contact