Triggers
Create tasks on a cron schedule, once at a set time, or on demand, with each fire recorded on the task it creates.
On this page
A trigger creates a task of an agent on a schedule (cron, or once at a time) or when you fire it. Each fire creates exactly one task.
hexel harness trigger set nightly --agent auditor@prod --goal "Audit the repositories" \
--cron "0 2 * * *" --timezone Europe/London
hexel harness trigger set release-check --agent auditor@prod --goal "Check the release" \
--at 2026-12-01T09:00:00Z
hexel harness trigger set on-demand --agent auditor@prod --goal "Audit {{fire_id}}"
hexel harness trigger fire on-demand --text "Look at the payments service" --idempotency-key deploy-4512
hexel harness trigger list
hexel harness trigger delete nightlyDefine a trigger
PUT /harness/triggers/{name} creates (201) or replaces (200) a trigger:
| Field | Description |
|---|---|
agent | The agent its tasks run: name, name@channel or name@v<n>. |
goal | Its tasks' goal. {{routine}}, {{fire_id}} and {{scheduled_for}} are filled in when it fires. |
inputs | Optional. Its tasks' inputs. |
description | Optional. What it is for. |
schedule | Optional. {"cron": "0 2 * * *", "timezone": "Europe/London"} or {"run_once_at": "<RFC 3339 time>"}. Without it, the trigger fires only on demand. |
The person who sets a trigger owns the tasks it creates. Managing triggers needs harness:trigger:manage and harness:task:create, which Admins and Owners have by default.
Fire a trigger
POST /harness/triggers/{name}:fire takes {"text": "...", "data": {...}}, both optional, and answers 202 with {trigger, routine_id, fire_id}. With an Idempotency-Key, a repeated fire answers 200 with replayed: true and creates no second task.
Fire-time text and data reach the task as data under inputs.routine_fire, never in its goal.
Each fire's task gets a trigger.fired event {trigger, routine_id, fire_id}. Deleting a trigger stops its schedule first.
Triggers can also be managed as files with hexel harness apply.