Skip to content
Nocturn

Triggers and schedules

A trigger is what starts an agent. Two exist today; the rest of this page is honest about which.

By hand

Section titled “By hand”

From the TUI, /fire runs an agent now, with an optional one-off task:

/agents                                   # list them
/fire morning-briefing
/fire morning-briefing only check the inbox

The run happens in the background and streams into your terminal marked with its run id. This is the quickest way to test an agent before letting it run on its own.

On a schedule

Section titled “On a schedule”

Add a when: line and the agent fires itself:

---
name: morning-briefing
when: "0 7 * * *"   # every day at 07:00
---

Standard five-field cron: minute, hour, day of month, month, day of week.

The scheduler computes each agent’s next due time from the wall clock and sleeps until the earliest — it does not wake every minute to test every schedule, because a sampling loop misses everything between samples and stops sampling entirely while the machine sleeps.

Three behaviours worth knowing, because they decide whether you can rely on a schedule:

Situation What happens
The machine slept through a firing On wake the agent is simply overdue. It still runs if it is inside the catch-up grace window; well past that it is logged and skipped — a 03:00 report fired at 09:00 is worse than none.
Several firings were missed in one gap It fires once, not once per missed slot.
Nocturn was closed over a firing It does not fire at startup. Due times are computed forward from now, so downtime is simply missed.

So a schedule is a “while it is running” promise, not a durable job queue. Keep nocturn serve running if a schedule matters.

An unsatisfiable spec (0 0 30 2 * — February 30th) terminates the search instead of looping forever, and the agent simply never becomes due.

See Agents for what a scheduled run does when it hits something that needs your approval — the short version is that autonomy decides, and the default denies rather than proceeds.

By webhook Planned

Section titled “By webhook ”

Letting an external system start an agent by calling a URL — a new order, a form submission, a CI failure. It would sit alongside cron as a second kind of trigger. It does not exist; do not build a workflow around it today.