Skip to main content

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: FAILED

Validate the workflow

swamp workflow validate nightly-report

Validation 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 serve

The 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 4

Or set it in .swamp/serve.yaml:

max-concurrent-scheduled-runs: 4

The 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.000Z

Add --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 2h

If 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 lastMissed reports the skipped fires with reason paused.
  • swamp workflow schedule list shows the schedule as paused, 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-report

The 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-schedule

To 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=production

To 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-report

To remove the override and revert to the built-in trigger:

swamp workflow trigger remove nightly-report

Refer to the Workflows reference for the full flag set.