Triggers

Triggers allow agents to run automatically in response to events — cron schedules, file changes, or incoming webhooks. They are configured in spec.triggers and activated with the initrunner daemon command.

Trigger Types

Type	Description
`cron`	Fire on a cron schedule
`file_watch`	Fire when files change in watched directories
`webhook`	Fire on incoming HTTP requests (localhost only)

Quick Example

spec:
  triggers:
    - type: cron
      schedule: "0 9 * * 1"
      prompt: "Generate weekly status report."
    - type: file_watch
      paths: ["./watched"]
      extensions: [".md", ".txt"]
      prompt_template: "File changed: {path}. Summarize the changes."
    - type: webhook
      path: /webhook
      port: 8080
      secret: ${WEBHOOK_SECRET}

initrunner daemon role.yaml

Cron Trigger

Fires the agent on a cron schedule.

triggers:
  - type: cron
    schedule: "0 9 * * 1"
    prompt: "Generate weekly status report."
    timezone: UTC

Field	Type	Default	Description
`schedule`	`str`	(required)	Cron expression (5-field: `min hour day month weekday`)
`prompt`	`str`	(required)	Prompt sent to the agent when the trigger fires
`timezone`	`str`	`"UTC"`	Timezone for schedule evaluation

Schedule Examples

Expression	Meaning
`"0 9 * * 1"`	Every Monday at 9:00 AM
`"/5 * * *"`	Every 5 minutes
`"0 0 1 * *"`	First day of every month at midnight
`"30 14 * * 1-5"`	Weekdays at 2:30 PM

File Watch Trigger

Fires when files change in watched directories using watchfiles.

triggers:
  - type: file_watch
    paths: ["./watched", "./data"]
    extensions: [".md", ".txt"]
    prompt_template: "File changed: {path}. Summarize."
    debounce_seconds: 1.0
    process_existing: false

Field	Type	Default	Description
`paths`	`list[str]`	(required)	Directories to watch
`extensions`	`list[str]`	`[]`	File extensions to filter (empty = all)
`prompt_template`	`str`	`"File changed: {path}"`	Template with `{path}` placeholder
`debounce_seconds`	`float`	`1.0`	Debounce interval
`process_existing`	`bool`	`false`	Fire once for each matching file already present on startup

Webhook Trigger

Fires when an HTTP request is received on a local endpoint. Useful for GitHub webhooks, CI/CD systems, or HTTP callbacks.

triggers:
  - type: webhook
    path: /webhook
    port: 8080
    method: POST
    secret: ${WEBHOOK_SECRET}

Field	Type	Default	Description
`path`	`str`	`"/webhook"`	URL path to listen on
`port`	`int`	`8080`	Port to listen on
`method`	`str`	`"POST"`	HTTP method to accept
`secret`	`str \| null`	`null`	HMAC secret for `X-Hub-Signature-256` verification

HMAC Verification

When secret is set, requests must include a valid X-Hub-Signature-256 header (GitHub-compatible HMAC-SHA256). Invalid or missing signatures return 403 Forbidden.

Example: GitHub Webhook

triggers:
  - type: webhook
    path: /github
    port: 9000
    secret: ${GITHUB_WEBHOOK_SECRET}

curl -X POST http://127.0.0.1:9000/github \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=..." \
  -d '{"action": "opened", "pull_request": {"title": "Fix bug"}}'

Daemon Mode

The initrunner daemon command starts all configured triggers and waits for events:

initrunner daemon role.yaml
initrunner daemon role.yaml --audit-db ./custom-audit.db
initrunner daemon role.yaml --no-audit

Option	Type	Default	Description
`role_file`	`Path`	(required)	Path to the role YAML file
`--audit-db`	`Path`	`~/.initrunner/audit.db`	Audit database path
`--no-audit`	`bool`	`false`	Disable audit logging

Signal Handling

The daemon handles SIGINT (Ctrl+C) and SIGTERM for clean shutdown:

Sets a stop event
Stops all triggers
Joins trigger threads (5-second timeout)
Exits cleanly

On this page