Schedulers

A scheduler is a cron-driven prompt meant to run headless on your machines — author a schedule on the Console's Schedulers page (Building blocks → Schedulers) and it publishes with your config, meant for a node running openeng headless to fire with nobody at the keyboard once the engine's scheduler ships.

What it is, and when to use it

Use a scheduler for anything periodic: a nightly repo audit, a morning digest, log triage at 6 am. The Console authors the definition; a machine of yours runs the headless engine:

openeng headless                       # checks the key, then reports its drivers
openeng headless --driver schedulers   # only the scheduler driver (work-pull | schedulers | auto)

openeng headless needs an OpenEng key on the machine: --key=<key> or OPENENG_KEY, an API key from the Console (API keys & sandboxes). Without one it refuses to start. It runs two drivers by default (auto): cloud work-pull and schedulers; today it prints that selection and exits. Jobs come straight from your published config; the Console never runs a schedule itself.

The editor, section by section

Identity

• Name — labels runs in engine logs (the id is the fallback).
• Enabled — disabled schedulers stay authored but are skipped at publish; the engine never fires them.

Schedule — the cron builder

The schedule is a 5-field cron expression: min hour dom mon dow. The builder gives you four ways to write one, all kept in sync:

• Presets — Hourly · Daily 06:00 · Weekdays 06:00 · Weekly (Mon) · Monthly (1st).
• Five field editors — one input per field.
• The raw expression — type it directly.
• A live plain-language preview plus the next 5 occurrences rendered in your chosen preview timezone.

The dialect is deliberately strict, and the Console validates exactly what the engine parses:

Timezone honesty

The timezone selector is preview-only — it affects the next-5 preview, nothing else. Once it fires schedules, the engine will use the node's local time. If your server is in UTC and you want 06:00 IST, author the UTC equivalent (00:30) — the badge in the editor reminds you every time.

Target — what runs

Two tabs; whichever you choose, the prompt string is what the node runs (the engine has no reference fields on schedulers):

• Prompt — write the prompt directly.
• Agent + prompt — pick an agent; the agent reference is stored as a sibling field honestly labeled not yet consumed by the engine — the prompt body is what runs, so mention the goal for the agent in it.

Run

• Mode — goal (autonomous multi-step run — the headless default), chat (single conversational turn), or coding (code-editing run).
• Working directory — optional; where the run starts, as a node-local path.

What the engine receives

A read-only section at the foot of the editor shows the exact keys a node parses from this schedule — id, name, cron, prompt, mode and workdir — marks cron and prompt as required while they're missing, shows disabled: true for a disabled scheduler, and names any sibling the engine ignores today (such as agentId). The preview timezone is stored too, but the engine ignores it.

Saving, and why the editor is strict

Like every console editor, the scheduler editor saves explicitly: the header's Save button is the only path to the server (the old Save now label is simply Save). The engine silently drops a scheduler without both a valid cron expression and a non-empty prompt, so while either is missing the document holds at invalid and Save is disabled with the reason — what's saved is always runnable. Until you Save, edits live in the browser's local draft mirror ("Restore unsaved draft?" on reopen). The What the engine receives section shows the exact emitted document: only the keys the engine parses, plus the honestly-labeled siblings. List rows carry trailing Edit / Delete actions, delete behind a confirmation; the list also shows each schedule in plain language and a usage meter against your plan's limit.

Plan & tier notes

Schedulers are a Pro feature: Pro includes 1 scheduler, Enterprise is unlimited (an Enterprise account can have its own count set). The meter counts enabled schedulers — disable extras instead of deleting them. Free shows the locked page; the server enforces the limit at publish, and New scheduler is disabled at the limit with the reason. Pro and Enterprise launch in Q4 2026 and can't be purchased yet (Plans & billing). openeng headless itself needs an OpenEng key on the machine (--key or OPENENG_KEY).

Troubleshooting

The job didn't fire. Expected today: the published engine doesn't fire scheduled jobs yet (see the warning at the top). Once it does, check timezone first — the engine will fire node-local, and the preview timezone is only a preview. Then check the dom/dow AND rule above.

openeng headless exits straight away. Also expected today: it checks the key, prints the drivers it selected (driver=…, with work-pull and schedulers on or off), and stops.

"cannot start: no OpenEng key". Pass --key=<key> or set OPENENG_KEY to an API key from the Console.

The schedule isn't in the published config. The scheduler was saved disabled, or it isn't part of the config that was published; check the config's version in the Console.

My cron expression is rejected but looks valid. It's probably valid in another dialect — the platform accepts exactly 5 numeric fields with * , - /. Translate @daily to 0 0 * * *, names to numbers, and drop any seconds field.