Hermes Agent cron jobs turn an AI assistant into scheduled operations: a morning brief, repository audit, quiet service monitor, customer-support digest, or publishing run that starts without a person opening chat.
The schedule is the easy part. Reliable automation depends on five decisions: whether the job needs an LLM, which provider and tools it may use, which project directory it runs in, where the result is delivered, and what proves success.
Quick answer#
Use an agent cron job when each run needs judgment, research, writing, browser work, or tool use. Use script-only --no-agent mode when a deterministic script can produce the final alert itself. Cron runs in a fresh session, so make the prompt self-contained, set an absolute --workdir for repository jobs, choose an explicit delivery target, trigger one test run, and verify the actual message, file, commit, or live URL.
If this is your first Hermes workflow, complete the 15-minute setup smoke test before creating the schedule. Cron adds a fresh session, runtime uptime, timezone, provider, and delivery boundary; prove the underlying task once, then prove the scheduled outcome in the real destination.
For unattended spending safety, Hermes snapshots the provider/model selected when a job is created. If the global default later changes, an unpinned job fails closed instead of silently switching to the new model. The resolution order is per-job pin, then cron.model plus cron.model_provider, then the global default. Operators who deliberately want every unpinned job to follow later global changes can run hermes config set cron.model_drift_guard false, but that also removes the protection against an accidental switch to a paid model. Check the provider costs and rate-limit guide before changing this policy. For business-critical jobs that must survive a sleeping laptop, compare a 24/7 Hermes setup or the managed FlyHermes path.
What an AI agent cron job actually runs#
A Hermes cron job stores a schedule, prompt or script, delivery rule, and optional runtime controls. The gateway checks due jobs every minute and runs each due agent job in a fresh session. That isolation is deliberate: a scheduled run should not depend on whatever happened in an unrelated interactive chat.
A production job therefore needs:
- A supported schedule. Use a relative delay such as
30m, an interval such asevery 2h, a five-field cron expression such as0 9 * * 1-5, or an ISO timestamp. - A self-contained task. Include source paths, URLs, required output, constraints, and the success condition.
- A runtime boundary. Set the project workdir, skills, toolsets, and model/provider deliberately.
- A delivery target. Send to local output, the origin chat, a home channel, a specific chat/topic, or multiple configured channels.
- A proof of completion. Verify the report, alert, file, test, commit, or production URL rather than trusting a green schedule row.
Ask Hermes conversationally to create the job, use /cron in chat, or use the standalone CLI. The schedule string accepted by the CLI is more precise than prose:
hermes cron create "0 9 * * 1-5" \
"Review open pull requests, identify blockers, and send a brief with links." \
--name "Weekday PR brief" \
--deliver telegram \
--workdir /absolute/path/to/repo
Then inspect and test it:
hermes cron list
hermes cron run "Weekday PR brief"
hermes cron status
run queues the job for the next scheduler tick. Confirm the gateway is healthy and inspect the destination rather than assuming the command means delivery succeeded.
Choose the right execution mode#
Agent job: judgment is required#
Use a normal cron job when the output cannot be determined by a fixed script. Good examples include:
- Synthesizing a daily research brief from several sources.
- Prioritizing new GitHub issues by urgency.
- Reviewing support conversations and drafting next actions.
- Updating a content page, running QA, deploying it, and verifying production.
- Explaining why a monitored page change matters.
The job gets the toolsets configured for the cron platform. A per-job enabled_toolsets setting can narrow that list further. This reduces both risk and tool-schema overhead: a news summary may need web and file access, but not terminal, browser, and delegation.
Attach reusable skills instead of stuffing the full procedure into every prompt:
hermes cron create "0 8 * * *" \
"Find three relevant papers from the past day and save concise notes." \
--skill arxiv \
--skill obsidian \
--name "Paper digest"
Script-only job: zero model calls#
Use --no-agent when the script itself can produce the exact message. Scripts must live under ~/.hermes/scripts/; pass the filename, not an arbitrary absolute path.
hermes cron create "every 5m" \
--no-agent \
--script memory-watchdog.sh \
--deliver telegram \
--name "Memory watchdog"
Script-only semantics are useful for real monitoring:
- Non-empty stdout is delivered verbatim.
- Empty stdout is a silent successful tick.
- A non-zero exit or timeout produces an error alert.
- No model, provider fallback, or token spend is involved.
For a hybrid job, attach a pre-check script without --no-agent. The script can collect deterministic data for the prompt. If its last line is {"wakeAgent": false}, Hermes skips the agent for that tick. This is the cost-efficient pattern for frequent polling where an LLM is only useful after a change.
For broader monitoring design, see AI agent monitoring and webhooks.
Make the future prompt self-contained#
Cron sessions do not inherit the current conversation. “Do the usual report” is not a safe prompt. Name the evidence, paths, decision rule, output, and failure behavior.
A stronger publishing prompt looks like this:
Work in /absolute/path/to/site.
Inspect the current content graph and today's evidence before choosing one page.
Ship one material improvement, run the repository's formatting, link, lint, and build checks,
commit and push the intended files, then verify the canonical production URL at phone and desktop widths.
Success means the live page contains the expected copy, has no horizontal overflow, and the final report includes the URL and test output.
If deployment or verification fails, report the exact failing layer; do not call the run successful.
That is a scheduled-work contract, not a reminder. If the output should be easy to continue tomorrow, use the AI agent session handoff checklist in the final report.
Set workdir for repository jobs#
Cron jobs are detached from a repository by default. They do not automatically load a project's AGENTS.md, CLAUDE.md, or .cursorrules, and file/terminal tools may start from the gateway's directory.
Set an absolute existing workdir:
hermes cron create "every 1d" \
"Audit dependencies, run tests, and summarize only actionable changes." \
--workdir /Users/me/projects/acme \
--deliver local
With workdir set, Hermes injects supported project instruction files and points terminal, file, and code-execution tools at that directory. Workdir jobs run sequentially on a scheduler tick to prevent process-wide working-directory collisions. This is a reliability feature, but it also means several heavy repo jobs due at the same minute may wait for one another.
Pin provider behavior and control rate limits#
Provider failures are one of the most common reasons a schedule exists but no useful result arrives. Treat provider selection as part of the job definition.
At creation, Hermes snapshots the active global provider and model. If you later change the global default, an unpinned job does not silently follow it: the run is skipped and Hermes asks you to pin the provider/model explicitly. This prevents an unattended job from unexpectedly moving to a paid model.
Pin a job from the dashboard or with hermes cron create/edit --model … --provider …. For a fleet-wide default, set cron.model and cron.model_provider; unpinned jobs then use that route independently of interactive chat changes. A separate Hermes profile is another strong isolation boundary when scheduled work needs its own credentials and budget.
If a job is flooding failure messages while the chat provider is rate-limited, do not use /stop; manage it from a normal shell:
hermes cron list
hermes cron pause "Weekday PR brief"
# or permanently:
hermes cron remove "Weekday PR brief"
Configure credential pools or fallback providers only when you want that recovery behavior. Reduce toolsets, move deterministic checks into scripts, and lower frequency before adding expensive fallbacks. The provider costs and rate-limits guide explains API credits, OAuth limits, retries, and scheduled-job budgeting.
Deliver to the exact place#
CLI-created jobs default to local output, while jobs created from messaging platforms normally default to origin delivery. Origin is convenient for a test; it is fragile for a durable business workflow.
Pin an explicit target where possible:
telegram
telegram:123456789
telegram:-1001234567890:17585
discord
slack
local
Hermes also supports comma-separated fan-out such as telegram,discord and dynamic all delivery to configured home channels. The scheduler delivers the final response automatically; the cron prompt should not call a messaging tool to send the same answer again.
For Telegram topic mode, TELEGRAM_CRON_THREAD_ID can route normal cron delivery into a dedicated Cron topic. An explicit telegram:chat_id:thread_id target wins over that default. If routing fails, use the gateway troubleshooting guide and verify the exact chat/topic rather than rotating a working bot token.
Make a delivery continuable when follow-up matters#
Cron delivery is fire-and-forget by default. If you want to reply “do task two” and have Hermes understand the delivered brief, enable a continuable job with attach_to_session through the cronjob tool, or set cron.mirror_delivery: true globally.
Thread-capable platforms prefer a fresh thread for each run, keeping follow-up conversations isolated. Broadcast fan-out targets are not made continuable. Use this for daily decision briefs; leave it off for one-way alerts.
Keep quiet jobs quiet#
For agent jobs, a successful final response containing [SILENT] suppresses delivery while preserving local output for audit. Failed jobs still alert. A monitor prompt can say:
Check the service. If it is healthy, respond with exactly [SILENT].
Otherwise report the failing check, evidence, and first recovery command.
For deterministic checks, script-only mode is better: empty stdout already means silence and costs zero tokens.
Chain jobs without pretending they share memory#
Cron jobs are isolated, but context_from can prepend the most recent output from one or more upstream jobs to a downstream prompt. This supports collect → rank → publish pipelines without pretending separate sessions share conversational memory.
Use it when each stage has a clear artifact and can fail independently. Keep schedules far enough apart for the upstream job to finish, and make each stage idempotent. For valuable data, persist the canonical artifact to a file or database too; an output handoff should not be the only copy.
Production checklist#
Before relying on a scheduled agent:
- Run the underlying task once interactively.
- Use a supported schedule string and confirm the intended timezone.
- Make the prompt self-contained.
- Choose agent, hybrid pre-check, or script-only mode.
- Set an absolute workdir for project jobs.
- Attach only the required skills and toolsets.
- Confirm the provider/model snapshot and expected fallback policy.
- Pin a specific delivery destination.
- Trigger one manual run and inspect the real output.
- Check
hermes cron statusand gateway health. - Define how to pause the job during provider or delivery failures.
- For publishing, require tests, push/deploy, live URL, and rendered phone/desktop QA.
The Hermes Dashboard and Web UI is useful for inspecting cron, profile, tool, provider, and gateway state. It is not proof that the outcome happened. The proof is the delivered brief, saved file, passing test, alert, commit, or live page.
Self-hosted cron or managed uptime?#
Self-hosting gives you full control over providers, scripts, filesystem access, and gateway routing. It also makes you responsible for the machine staying awake, service restarts, updates, backups, credentials, monitoring, and delivery recovery.
If that control is the point, follow the self-hosted versus hosted AI agent guide. If scheduled work is business-critical and you do not want a VPS, Docker, and gateway maintenance project, FlyHermes is the managed path for browser/mobile access, connected channels, and uptime.
FAQ#
Do Hermes cron jobs remember the chat that created them?#
No. Agent jobs start in fresh sessions. Put durable procedures in skills and include paths, sources, constraints, output format, and success criteria in the job prompt.
Can a cron job run without an LLM?#
Yes. Use --no-agent --script filename for a script under ~/.hermes/scripts/. Non-empty stdout is delivered, empty stdout is silent, and failures alert.
Why did a cron job stop after I changed models?#
Hermes snapshots the provider/model when a job is created and fails closed after an unexpected global model change. Ask Hermes to pin the job's provider/model explicitly, then trigger a test run.
Can one job deliver to Telegram and Discord?#
Yes. Use a comma-separated target such as telegram,discord, or all for configured home channels. Use exact chat/topic/channel targets for important workflows.
Why did the job run in the wrong repository?#
Repository context is not automatic. Set an absolute --workdir; then verify the project instruction files and tool working directory during a manual run.
Can I reply to a cron report and continue the task?#
Only when continuable delivery is enabled with attach_to_session for the job or cron.mirror_delivery: true globally. Otherwise cron delivery is fire-and-forget.
What should count as success?#
The outcome, not the schedule: a message delivered to the intended topic, a saved artifact, a passing test, a verified quiet tick, a pushed commit, or a live URL that passed rendered QA.
Browser jobs need stronger success evidence#
A scheduled browser run should not report success merely because navigation started. Require the expected page state or created record, a console check when JavaScript matters, a screenshot path, bounded retries, and delivery into the intended channel. The browser automation troubleshooting guide covers expired sessions, 502s, Docker-localhost mistakes, and anti-bot boundaries.