The work that should happen whether you are at the keyboard or not

Some work is only worth doing if it happens without being asked. The triage pass over yesterday's issues. The dependency check nobody remembers on a Tuesday. The report that is useful at seven in the morning and pointless at eleven.

None of it is hard for an agent. All of it is easy to forget, which is the same as not having it.

A schedule starts a session

The Gateway has a scheduler built into it. A job says which machine, which repository, when to fire, and what to say - and at that time it starts an agent session with that prompt, with nobody at the keyboard. You manage jobs on the Schedule page in the Cockpit, or from the command line, which is the surface an agent or a script reaches for.

Four things a job cannot be without: a name, a machine, a repository and a time zone. Then either a five-field cron expression for something recurring or a single timestamp for a one-off, and either the prompt the session starts with or the name of a work list to drain instead.

The four behaviours to know before you rely on one

A scheduler is only useful if you know exactly what it does when things are not ideal, so these are stated plainly rather than discovered later.

• A missed fire is a skipped beat, not a queue. If the machine is off when a job is due, the run is recorded as not started and the job advances to its next future occurrence. It does not replay every missed interval when the machine wakes up, and it does not run late.
• The run record holds the start, not the outcome. The history tells you whether a session started, on which machine and Director, and with which session id. What the agent then went on to do is not tracked there - to see that, open the session it started.
• Overlap protection covers the launch, not the work. It rejects a second fire while the first is still mid-start, and lets go as soon as that start attempt finishes. Tonight's run will fire even if last night's session is still working. If two of the same job must never run at once, write a prompt that tolerates a sibling, or space the schedule wider than the work.
• A seed prompt lands in a session with no memory. The session is brand new and has zero context, so the prompt has to be self-contained. Name the repository, the goal, and where the result should go. "Continue yesterday's work" means nothing to a session that was born ten seconds ago.

Writing a prompt for nobody

The difference between a scheduled run that earns its place and one you quietly disable after a fortnight is almost always the prompt. An interactive prompt can be vague because you are sitting there to correct it. An unattended one cannot.

So write it the way you would write instructions for someone covering your job while you are away. Say what to look at, what counts as finished, and what to do with the answer - post it, write it to a file, open an issue. A scheduled run that produces a result nobody reads is a scheduled run that gets switched off.

Where it runs

On the machine you named. When a job is due, the Gateway looks for a running Director there; if there is none, it asks that machine's launcher to start one. If the machine is off, the launch fails and the run is recorded as not started - which is the first behaviour above, and the reason an overnight job belongs on a machine that stays on.

Job definitions and their run history live in the Gateway's own database, so schedules survive restarts and reboots on both the hosted Gateway and one you run yourself.

The command list, the full set of job fields and the REST surface behind the Schedule page are here: scheduled runs with the Gateway cron.