RUN WORKFLOWS ON A SCHEDULE
Prerequisites: Swamp installed, a repository with a workflow, swamp serve
running. See
Create and Run a Workflow
if you need to create one first.
Add a trigger block to the workflow
Open your workflow YAML and add a trigger block with a schedule field
containing a cron expression:
name: nightly-report
trigger:
schedule: "0 0 * * *"
jobs:
- name: main
steps:
- name: generate
task:
type: behavior
behavior: my-reporter
methodName: execute
inputs:
run: "echo Running nightly report"
dependsOn: []Catch up a missed fire
By default, serve does not fire a schedule it missed while it was down; it
records the miss and waits for the next cron tick. To have serve fire the most
recent missed slot when it comes back, add trigger.catchUp:
trigger:
schedule: "0 9 1 * *"
catchUp:
policy: latest
maxDelay: 6h| Field | Value |
|---|---|
policy |
none (the default) or latest |
maxDelay |
Required with latest, refused with none. A number and a unit (m, h, d or w), greater than zero and at most 31d |
trigger.catchUp requires trigger.schedule. With latest, serve fires only
the most recent missed slot, once, and only if that slot is at most maxDelay
old. It never replays a backlog of missed slots.
- A slot at which the schedule was paused is not caught up. A pause that was set and lifted entirely while serve was down leaves no record, so a slot in that window is caught up.
- The first start after upgrading to a version with catch-up only starts tracking the schedule; nothing before it is called missed.
- The catch-up runs on the leader, after pending runs are replayed at startup, and again when a follower is promoted to leader.
Every run a cron fire starts carries the run tag swamp.trigger.scheduledFor
with the slot it was fired for. A catch-up run also carries
swamp.trigger.catchUp: "true", so a workflow that should not run late can read
run.tags and decline.
swamp workflow validate reports an invalid catchUp:
$ swamp workflow validate nightly-report
Validating: nightly-report
✗ Schema validation
→ trigger.catchUp.maxDelay: policy 'latest' requires maxDelay, e.g. 6h (file: .../workflows/workflow-nightly-report.yaml)
Summary: 0 passed, 1 failed
Result: FAILEDValidate the workflow
swamp workflow validate nightly-reportValidation confirms the trigger schema is valid along with the usual job and step checks.
Start swamp serve
Scheduled triggers only execute when the server is running:
swamp serveThe server picks up all workflows with trigger.schedule and registers them on
startup. Each scheduled run is recorded in
usage telemetry with
triggerSource: schedule. To turn that off, start the server with
SWAMP_NO_TELEMETRY=1.
Run schedules concurrently
By default, serve runs one scheduled workflow at a time, in the order the schedules fired. A fire that arrives while another scheduled run is in progress waits in a queue. To let different workflows run at the same time, raise the limit:
swamp serve --max-concurrent-scheduled-runs 4Or set it in .swamp/serve.yaml:
max-concurrent-scheduled-runs: 4The environment variable SWAMP_MAX_CONCURRENT_SCHEDULED_RUNS sets the same
default. To change the value on a running server, edit serve.yaml and run
swamp serve reload. A raised limit starts queued scheduled runs at once; a
lowered one stops no run in flight. A value set by the flag or the environment
variable stays pinned until restart.
This limit is separate from --max-concurrent-runs, which limits runs started
through the API. Raising one does not change the other.
A workflow never overlaps itself, whatever the limit:
- A fire that arrives while the same workflow is still running is skipped, and serve logs a warning.
- A fire that arrives while the same workflow is queued, not yet running, waits behind it.
Two different workflows that use the same behavior still take turns on that behavior, through the per-behavior lock.
Check queue delay
With the dashboard enabled, the
Schedules view shows waiting fires next to each schedule, for example
2 queued · waiting 12m, and the Overview shows the total queued.
To read the same state from a script, query
GET /api/v1/health
with a server token (see
Monitor Server Health to
mint one). It shows each token only the workflows that token may read:
curl -s http://127.0.0.1:9090/api/v1/health \
-H "Authorization: Bearer health-monitor.secret"Each schedule's queue state is in the response's scheduling object:
{
"scheduling": {
"enabled": true,
"schedules": [
{
"workflowId": "a40ea282-6d3c-482c-b7de-e2ccb62c936f",
"workflowName": "nightly-report",
"cronExpression": "0 0 * * *",
"nextRun": "2026-10-29T00:00:00.000Z",
"running": true,
"queued": 0,
"oldestQueuedAt": null,
"lastQueueDelayMs": 14,
"catchUp": { "policy": "latest", "maxDelay": "6h" },
"lastMissed": null
}
],
"timeZone": "Europe/London"
}
}| Field | Meaning |
|---|---|
queued |
Fires waiting to start |
oldestQueuedAt |
When the oldest waiting fire fired, or null if nothing is waiting |
lastQueueDelayMs |
Milliseconds between fire and start for the last run that started, or null |
catchUp |
The schedule's effective catch-up policy, or null if none is set |
lastMissed |
The most recent lost fire, or null; see Check for missed fires |
An oldestQueuedAt that keeps getting older, or a lastQueueDelayMs that keeps
growing, means scheduled runs are arriving faster than serve starts them. Raise
--max-concurrent-scheduled-runs, or spread the schedules out.
The unauthenticated /health endpoint is a liveness check: it answers
{"status": "ok", "version": "1"} and lists no schedules.
A higher limit shortens the wait in the queue, not the run itself. Each run still syncs with the datastore around its steps, and with a remote datastore such as S3 that sync can take longer than the work.
Check for missed fires
Serve records the most recent fire it lost as the schedule's lastMissed, shown
in GET /api/v1/health, the dashboard and swamp workflow schedule list:
"lastMissed": {
"fireTime": "2026-11-01T09:00:00.000Z",
"count": 1,
"reason": "serve_down",
"caughtUp": true,
"detectedAt": "2026-11-01T11:42:07.512Z"
}| Field | Meaning |
|---|---|
fireTime |
The latest lost slot |
count |
Lost fires in a row with the same reason. Capped at 1000; saturated: true is added when the cap was hit |
reason |
serve_down (serve was not running), paused (the schedule was paused) or overlap (the previous run was still in progress) |
caughtUp |
Whether a catch-up run was queued for fireTime. It does not mean the run executed |
detectedAt |
When serve recorded the miss |
lastMissed is current state, not history. The next fire that starts a run
clears it, and changing the cron expression drops it, since the schedule is then
measured afresh. In swamp workflow schedule list it appears as a Missed
line, for example:
nightly-report - active
Cron: 0 0 * * *
Next fire: 2026-11-02T00:00:00.000Z
Missed: 1 fire(s) (serve was down), latest 2026-11-01T00:00:00.000Z (caught up)The serve audit log (swamp audit log --server) keeps every miss.
workflow.schedule.missed records fires missed while serve was down; fires lost
to a pause or an overlap are recorded as workflow.schedule.skipped. The
workflow.schedule.fire entry for a catch-up run carries catchUp: true.
List schedules
To see every scheduled workflow, its cron expression, next fire and whether it is paused:
$ swamp workflow schedule list
nightly-report - active
Cron: 0 0 * * *
Next fire: 2026-10-17T00:00:00.000Z
weekly-cleanup - active
Cron: 0 8 * * 1 (serve.yaml override)
Next fire: 2026-10-19T08:00:00.000ZAdd --server <url> to list the schedules the running serve has registered, and
--json for a script. A schedule that lost a fire also shows a Missed line;
see Check for missed fires.
Pause a schedule
To stop a workflow's cron fires without editing its YAML or serve.yaml:
$ swamp workflow schedule pause nightly-report --reason "stalling serve"
Paused schedule: nightly-report (0 0 * * *)
Reason: stalling serve
Paused by: user:ops
Until: resumed
Scheduled fires are skipped; manual and webhook runs still run.To have the pause end on its own, add --until with a duration such as 2h, or
an ISO-8601 time with Z or an offset:
swamp workflow schedule pause nightly-report --until 2hIf serve runs against a shared datastore, or you work in a checkout that writes
through serve, add --server <url>. A custom datastore that is not v3 accepts
pauses only through serve.
While the pause is in force:
- Serve skips each cron fire, including a fire that was already queued when you
paused, and logs
Skipped scheduled workflow nightly-report: paused (stalling serve). - The schedule's
lastMissedreports the skipped fires with reasonpaused. swamp workflow schedule listshows the schedule aspaused, with(skipped while paused)after its next fire.
The pause is kept in serve's control-plane store, not in the workflow or
serve.yaml, and serve reads it before every fire. It takes effect at the next
fire without a reload, and it survives swamp serve reload and a serve restart.
Resume a schedule
$ swamp workflow schedule resume nightly-report
Resumed schedule: nightly-reportThe next cron fire runs. Fires skipped while the schedule was paused are not
run, even with trigger.catchUp: serve settled each skipped slot as it passed.
At startup, a slot missed while serve was down is not caught up if the schedule
was paused at that slot; see Catch up a missed fire.
If the workflow was deleted or lost its schedule while paused, schedule list
shows the pause as paused (orphaned) with the command to remove it, which
takes the workflow ID.
See the Workflows reference for every flag, the JSON output and the errors.
Disable scheduling
To start the server without executing any scheduled workflows:
swamp serve --no-scheduleTo turn scheduling off on a running server, set schedule: false in
.swamp/serve.yaml and run swamp serve reload. New fires stop; queued
scheduled runs stay pending and runs in flight finish. Setting it back to true
and reloading starts the scheduler again and catches up missed fires. See
Scheduling and timed services.
Common cron patterns
| Pattern | Schedule |
|---|---|
0 * * * * |
Every hour |
0 0 * * * |
Daily at midnight |
0 9 * * 1-5 |
Weekdays at 9:00 AM |
*/15 * * * * |
Every 15 minutes |
0 0 * * 0 |
Weekly on Sunday at midnight |
Pass inputs to scheduled runs
If the workflow defines an inputs schema, supply default values in the trigger
block:
trigger:
schedule: "0 0 * * *"
inputs:
env: "production"Override a schedule without editing the workflow
To change the schedule of a workflow — yours or one from an extension — without
modifying its YAML file, use swamp workflow trigger set:
swamp workflow trigger set nightly-report --schedule "0 3 * * *"The override is written to serve.yaml and takes precedence over the workflow's
built-in trigger. To include inputs:
swamp workflow trigger set nightly-report --schedule "0 3 * * *" --input env=productionTo set a catch-up policy on the override, add --catch-up and, with latest,
--catch-up-max-delay:
$ swamp workflow trigger set nightly-report --schedule "0 3 * * *" --catch-up latest --catch-up-max-delay 6h
Set trigger override for "nightly-report": schedule "0 3 * * *"
catch-up: "latest (max delay 6h)"--catch-up latest requires --catch-up-max-delay, and --catch-up-max-delay
requires --catch-up latest:
$ swamp workflow trigger set nightly-report --schedule "0 3 * * *" --catch-up latest
Error: --catch-up latest requires --catch-up-max-delay (e.g. 6h)trigger set writes the whole override, so a call without --catch-up removes
a catch-up policy an earlier call set. With --server, a serve that does not
support catch-up refuses --catch-up before saving anything:
Error: The server (swamp <version>) does not support --catch-up, so it would save the override without its catch-up. Upgrade swamp serve, or run without --server.To verify the effective schedule:
swamp workflow trigger get nightly-reportTo remove the override and revert to the built-in trigger:
swamp workflow trigger remove nightly-reportRefer to the Workflows reference for the full flag set.