Understand Hermes Cron Scheduler Internals

Hermes cron separates when a job fires from what happens when it fires. That distinction matters when debugging missed schedules, duplicate execution, scale-to-zero gateways, skill injection, or delivery failures. The trigger provider selects due work; the shared execution path creates a fresh agent session, runs the job, delivers the result, and updates state.

Scheduling and storage

Jobs support relative delays, recurring intervals, five-field cron expressions, and exact ISO timestamps. Their records are stored atomically in the Hermes cron jobs file with schedule, state, next and last run times, repeat count, optional skills, optional script, delivery target, and optional model/provider override.

The built-in scheduler ticks periodically, acquires a lock, finds due scheduled jobs, marks each running, dispatches execution, computes its next run or completion, and writes state back. Script execution is dispatched outside the tick lock so a long collector should not prevent other due jobs from firing.

Runtime checklist

Confirm the job is enabled and in scheduled state.
Check next_run_at, timezone assumptions, and the parsed schedule kind.
Identify the active trigger provider: built-in or managed Chronos.
Remember that each run starts with no conversation history.
Attach required skills in explicit order.
Make script output public-safe for injection into the prompt.
Configure script and agent inactivity timeouts separately.
Verify the delivery target independently of task execution.
Confirm repeat counts and completed state after a successful run.
Preserve the recursion guard that disables cron creation inside cron jobs.

Trigger providers and scale to zero

The default in-process provider ticks while the gateway is running. A managed provider such as Chronos can arm a one-shot for each job’s actual next fire, wake a scaled-to-zero gateway through an authenticated callback, claim the job with compare-and-set semantics, run the shared execution path, and re-arm the next occurrence.

If a configured trigger provider is missing or unavailable, Hermes falls back to the built-in provider with a warning rather than leaving cron without a trigger. That fallback still requires a running process; operators should not mistake fallback availability for scale-to-zero scheduling.

Common pitfalls

Expecting a cron run to remember prior conversation context.
Writing a prompt that needs clarification even though no user is present.
Debugging delivery before confirming whether execution succeeded.
Holding the scheduler lock during a long script or network call.
Treating an inactivity timeout as a hard wall-clock duration.
Assuming CLI-only cron commands provide the same always-on trigger as a running gateway.
Creating cron jobs recursively from inside a cron job.
Configuring a managed provider without verifying callback authentication and claim behavior.

Verification steps

Create a harmless one-shot job and inspect its parsed schedule and next run time.
Run it manually and confirm a fresh session, attached skills, task result, and delivery status.
Verify the job transitions to completed or calculates the correct next occurrence.
Run two due fixtures concurrently and confirm scheduler locking prevents overlapping claims.
Test a bounded pre-run script and distinguish script timeout from agent inactivity timeout.
If using Chronos, verify callback authentication, at-most-once claim, execution, and re-arm behavior.
Restart the gateway and confirm stored jobs reload without duplicate firing.

Official documentation

https://hermes-agent.nousresearch.com/docs/developer-guide/cron-internals