> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Reactive automation inside a template: a source fires, actions run.

Triggers turn a computer into a reactive system. Each trigger pairs a **source** that produces events with one or more **actions** that run in response, plus optional **dedup** to suppress noise. They run continuously inside the computer, managed for you.

```yaml theme={null}
triggers:
  - name: heartbeat
    title: "Minute heartbeat"
    source:
      type: cron
      schedule: "* * * * *"
    actions:
      - type: command
        run: "echo beat >> /var/lib/orgo/heartbeat.log"
```

Each trigger requires a unique `name`, a `source`, and at least one entry in `actions`. `title` and `description` are labels for the dashboard, and `enabled` defaults to `true` when omitted. A template may declare up to 256 triggers.

## Sources

A source's `type` selects which fields apply.

| Type | Fires when | Key fields |
| - | - | - |
| `cron` | A schedule elapses | `schedule` (5-field cron) |
| `file` | A file at or under `path` is created, modified, or deleted | `path`, `events: [create, modify, delete]` (all three when omitted) |
| `http` | Polling a URL returns `expect_code`, or the request fails | `url`, `method` (default `GET`), `expect_code` (default `200`), `interval` (default `30s`) |
| `process` | A process with this exact name starts or stops | `process` |
| `metric` | A system metric stays past a threshold for `duration` | `metric`, `op`, `value`, `duration` (default `30s`) |
| `log` | A line of the service's log matches a regular expression | `service`, `match`, `parse: text\|json` |
| `event` | A custom event is emitted in the computer | `event` |
| `desktop` | A desktop event occurs | `event`: `window_focus`, `window_open`, `window_close`, or `clipboard` |

A `cron` schedule has no seconds field, and when it restricts both day-of-month and day-of-week, both must match. An `http` source fires on every poll that returns `expect_code`, so with the defaults a healthy URL fires every 30 seconds. A `metric` source fires again every `duration` while the condition holds. To emit a custom event, append a JSON line with a `name` field to `/var/lib/orgo/events.jsonl`, for example `{"name": "deploy.done"}`. A trigger whose `event` matches that name fires. The line that creates the file is not read, so create the file first, for example with `touch /var/lib/orgo/events.jsonl` in [`build.run`](/guides/templates/schema#build).

Metric sources cover `cpu_percent`, `ram_percent`, `disk_percent`, `net_in_mbps`, and `net_out_mbps`, compared with `>`, `>=`, `<`, `<=`, `==`, or `!=`.

<Warning>
  Validation also accepts the metrics `gpu_percent`, `gpu_memory_percent`, and `gpu_temp_celsius`, and the desktop events `screen_change`, `file_change`, `audio_stream_start`, `audio_stream_stop`, `process_start`, `process_stop`, `idle`, and `active`. A trigger on any of them never fires.
</Warning>

```yaml theme={null}
# Restart a service if memory stays high for two minutes
triggers:
  - name: mem-guard
    source:
      type: metric
      metric: ram_percent
      op: ">"
      value: 90
      duration: 2m
    actions:
      - type: service
        op: restart
        target: my-app-server
```

## Actions

A trigger runs one or more actions in order. The `type` selects the fields.

| Type | Does | Key fields |
| - | - | - |
| `webhook` | HTTP request out. Sets no `Content-Type` unless you add one in `headers` | `url`, `method` (default `POST`), `headers`, `body` |
| `command` | Run a shell command as root | `run`, `cwd`, `timeout` (default `5m`) |
| `service` | Control a service | `op: start\|stop\|restart`, `target` (a service declared under [`apps`](/guides/templates/schema#apps)) |
| `notify` | Write a notification line to the trigger log. No desktop notification is shown | `title`, `body`, `level: info\|warning\|critical` |
| `log` | Write to the trigger log, `/var/log/orgo/triggers.log` | `message` |
| `api` | Call the computer's Desktop API | `endpoint` (`METHOD /path`; the method defaults to `POST`) |

<Warning>
  The `api` action does not send the Desktop API's token, so a call to any route that requires authentication fails with `401`.
</Warning>

String fields such as `url`, `body`, `headers`, `run`, `title`, `message`, and `endpoint` expand four placeholders: `{{trigger}}` (the trigger name), `{{source}}` (the source type), `{{time}}` (RFC 3339), and `{{data.KEY}}` (a field of the event, such as `{{data.path}}` for a file source). Write them without inner spaces; `{{ data.path }}` is left as is.

```yaml theme={null}
# Post to Slack when a file lands in the inbox
triggers:
  - name: new-upload
    source:
      type: file
      path: /data/inbox
      events: [create]
    actions:
      - type: webhook
        url: https://hooks.slack.com/services/...
        method: POST
        headers:
          Content-Type: application/json
        body: '{"text": "new file: {{data.path}}"}'
```

## Dedup

Bursty sources can fire constantly. Add at most one dedup strategy per trigger.

| Strategy | Effect |
| - | - |
| `debounce` | Drop events that arrive within this window of the last fire. It does not wait for a burst to settle, so it behaves like `cooldown`. |
| `cooldown` | Enforce a minimum gap between fires. |
| `rate_limit` | Cap fires within a sliding window, e.g. `10/1m`. Events over the cap are dropped. |

Independent of `dedup`, a trigger fires at most 120 times a minute.

```yaml theme={null}
triggers:
  - name: config-reload
    source:
      type: file
      path: /etc/my-app/config.yaml
      events: [modify]
    dedup:
      debounce: 2s
    actions:
      - type: service
        op: restart
        target: my-app-server
```

## Triggers vs. health checks

They complement each other:

* A [health check](/guides/templates/schema#apps) is a per-app **watchdog**. It probes one URL, port, command, or process and can restart a service when the probe keeps failing (`on_fail: restart_service:…`).
* A trigger is **general automation**: any source to any action, across the whole computer.

Reach for a health check to keep a service alive; reach for a trigger to react to files, schedules, metrics, or desktop activity.

## Next steps

<CardGroup cols={2}>
  <Card title="Schema reference" icon="file-code" href="/guides/templates/schema">
    Every source and action field.
  </Card>

  <Card title="Examples" icon="book-open" href="/guides/templates/examples">
    Triggers in real templates.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.