Triggers
Select events, filter context, and guard run admission.
An enabled trigger binds one harness, one sandbox, an agentId, and an initialPrompt.
GitHub or webhook events can start runs only after filters and admission guards pass.
Schema
Triggers JSON Schema · Guard JSON Schema
| Field | Contract |
|---|---|
key, name | Unique local key and display name |
provider | github or webhook |
harness, sandbox | Existing local declaration keys |
agentId | Non-empty kebab-case runtime agent ID |
initialPrompt | Non-empty instruction; at most 64 KiB |
enabled | Defaults to true; explicitly disable during setup |
guards | At most 10; each guard type appears at most once; defaults to [] |
Filters
Filters inspect the incoming event, not prior runs. All configured filter conditions must pass.
For GitHub, select eventType and actions, then use only the fields supported by that event.
For webhooks, select events and a nested payloadFilter.
Unsupported combinations fail validation. Empty filters generally add no restriction,
but comment events need a comment selector or matchAllComments.
Guards
Guards inspect prior admissions or active runs. They are evaluated with run reservation. They are not content filters, and they do not change the agent prompt.
type | Effect | Parameters |
|---|---|---|
max_occurrences | Limit admissions | limit 1–100 (default 3); optional windowSeconds |
cooldown | Require a gap between admissions | Required positive seconds |
max_concurrent | Limit active runs | Required limit 1–100 |
deduplicate | Skip previously admitted identities | Optional windowSeconds |
All guards accept enabled (default true) and a scope.
Time windows are positive integer seconds, at most 31536000.
Without a window, occurrence/deduplication guards consider all matching admission history.
| Scope | Identity |
|---|---|
repository | Repository, within this trigger's admission history |
subject | Issue or pull request |
commit | Commit SHA |
event | Event type, action, and event ID |
delivery | Delivery ID; deduplicate only |
deduplicate supports delivery/subject/commit/event, not repository.
Other guard types support repository/subject/commit/event, not delivery.
The event must also supply the selected identity. A missing identity skips admission;
it does not silently broaden the guard scope.
guards:
- type: max_concurrent
scope: repository
limit: 1
- type: deduplicate
scope: delivery