Hooks

Run any shell command after a successful service start, an unsuccessful service exit, a cron run killed at its timeout, or a cron boundary skipped because the previous run was still going.

Events

Hook	When
onstart	Service reaches readiness or a one-shot completes successfully
onerr	Service exits unsuccessfully before or after readiness, a cron run is killed at its cron.timeout, or a cron boundary is skipped because the previous run is still going

Configuration

services:
  postgres:
    command: "postgres -D /var/lib/postgres"
    hooks:
      onstart:
        command: "echo 'Postgres started'"
        timeout: "10s"
      onerr:
        command: "/usr/local/bin/report-crash postgres"

Hooks inherit service environment variables, plus these, which say why the hook ran. A variable that doesn't apply to the event is unset, never empty, and a service's own env can't set any of them.

Variable	Set for	Value
SYSG_HOOK_EVENT	every hook	onstart, service_exit, cron_exit, cron_timeout or cron_overlap
SYSG_EXIT_CODE	service_exit, cron_exit	The exit code, unset when there was none (killed by a signal, or never started)
SYSG_SCHEDULED_AT	cron_exit, cron_timeout, cron_overlap	The schedule boundary the run was for, RFC 3339 UTC
SYSG_RUNNING_SINCE	cron_overlap	When the run that is still going started, RFC 3339 UTC

Execution

• Run via sh -c
• Fire-and-forget (no retries)
• Timeout kills with SIGKILL
• Failures logged but don't affect service

Behavior

Scenario	Hooks
Start and readiness success	onstart
Successful one-shot completion	onstart
Spawn or readiness failure while running	None
Clean exit	None
Manual stop	None
Unsuccessful exit before or after readiness	onerr
Cron run killed at its cron.timeout	onerr
Cron boundary skipped while the previous run is still going	onerr
Successful automatic restart	onstart

Tips

• Keep commands short
• Use env vars for secrets
• Make repeated actions idempotent