Cron jobs

A job runs a command on a schedule, on the servers you target. Every run is recorded with its output, exit code and duration.

Define a job

jobs:
  nightly-report:
    schedule: "0 3 * * *"
    timezone: Europe/Berlin
    target: role=worker
    run_on: one            # one healthy server, or "each"
    service: worker        # optional: run inside this service's image
    command: node scripts/report.js
    timeout: 15m
    retries: 3
    overlap: skip
    notify: [slack:#ops]

Field	Description	Default
schedule	Five-field cron expression, or @hourly, @daily, @weekly, @monthly	required
timezone	IANA timezone, DST-aware	workspace timezone
target	Where it can run, see targets	required
run_on	one healthy server or each matching server	one
service	Run inside the image of this service, with its environment	run on the host
command	The command to run	required
timeout	Kill the run after this long	1h
retries	Extra attempts after a failure, with growing backoff	0
overlap	skip, queue or allow when the previous run is still going	skip
notify	Where failures, missed runs and slow runs go	the job owner by email

Host commands run as the fwoop user. To run as another user, set user:; the agent needs a sudoers rule for it.

Import existing crontabs

The agent can read the crontabs on a server and suggest a job for each entry:

$ fwoop jobs import --server web-01
Found 4 entries in /etc/crontab and 1 in crontab -u deploy
? Adopt "0 3 * * * /opt/app/report.sh" as nightly-report? Yes
✓ Adopted 3 jobs; the original lines are commented out

Runs and history

$ fwoop jobs history nightly-report
#412  succeeded  2m 44s  retried once  today 03:00
#411  succeeded  2m 31s                yesterday 03:00
$ fwoop jobs run nightly-report        # run now, outside the schedule

When things go wrong

• Failed: the command exited non-zero after all retries.
• Missed: no matching server was online at the scheduled time. Set catch_up: true to run once it’s back.
• Slow: a run took more than twice its usual duration.

Each sends a notification to notify. Agents keep their schedules locally, so jobs still run if the control plane is unreachable; results sync when it’s back.