How It Works

Cron

Schedule recurring tasks with cron expressions.

Configuration

services:
  backup:
    command: "sh /scripts/backup.sh"
    cron:
      expression: "0 0 * * * *"  # Every hour
      timezone: "America/New_York"  # Optional
      timeout: "45m"  # Optional

Field	Required	Meaning
`expression`	yes	When to run, in the 6-field format below
`timezone`	no	IANA timezone the expression is read in. Defaults to the system timezone
`timeout`	no	Longest one run may take, as a duration (`500ms`, `30s`, `45m`, `2h`). Must be greater than zero

Timeouts

A run has no time limit unless you set timeout. A job that takes three hours gets three hours.

When a run goes past its timeout, systemg sends SIGTERM to the run's whole process tree, waits briefly, then sends SIGKILL to anything left. The run is recorded as timed out after <timeout> in sysg inspect -s <unit>, and the unit's onerr hook fires with SYSG_HOOK_EVENT=cron_timeout. A timeout counts as a failed run for status and health, but it's recorded separately from a non-zero exit, so you can tell the two apart.

Without a timeout, a run that hangs keeps running. Each schedule boundary it blocks is recorded as an overlap, so it shows up in status, but nothing kills it. Set timeout when a stuck run holding memory or CPU matters to you.

Format

6-field cron: second minute hour day month weekday

0 * * * * *      # Every minute
0 0 0 * * *      # Daily at midnight
0 0 9 * * 1      # Mondays at 9am
0 */30 * * * *   # Every 30 minutes
0 0 12 1,15 * *  # 1st and 15th at noon

Notes

Cron jobs are short-lived (run and exit)
restart_policy is ignored for cron units; each run is scheduled, not supervised
Overlap detection prevents duplicate runs. If a run is still going at the next boundary, that boundary is skipped and recorded as an overlap
Cron units are scheduled by the supervisor, not run as persistent services. Unlike services, they cannot be started or restarted directly with sysg start -s <unit> or sysg restart -s <unit> — both return SG0101. To (re)schedule a cron unit, reload or restart its project so the supervisor re-reads the manifest. A project restart does not run the unit immediately.

Info

A cron row marked Failed or Failing means its most recent run failed. The scheduler remains active and will run it again at the next scheduled time. A later successful run replaces that health verdict; use sysg inspect -s <unit> for run history and sysg logs -s <unit> for output.

Examples

services:
  # Database backup daily at 2am
  db-backup:
    command: "pg_dump mydb > /backups/mydb-$(date +%Y%m%d).sql"
    cron:
      expression: "0 0 2 * * *"

  # Health check every 5 minutes
  health-check:
    command: "curl --fail http://myservice/health"
    cron:
      expression: "0 */5 * * * *"

Status

Scheduled cron jobs:
● backup
  Schedule: 0 0 * * * * (every hour)
  Next run: 13:00:00 (in 10 mins)
  Last run: 12:00:00 (success)

← Projects Hooks →