# Cron triggers

import { Aside } from "@astrojs/starlight/components"

Agents on Ren normally run when a human sends a message or when an external event arrives. But some work is predictable (a weekly status digest, a nightly code review, a daily Slack summary) and doesn't need a person to kick it off. **Cron triggers** let you schedule an [agent](/docs/deep-dives/concepts/agents/agents/) session on a recurring timetable, defined by a standard cron expression.

## How cron triggers work

A cron trigger ties together four things:

- **Which agent** to run, within a [project](/docs/deep-dives/concepts/compute/projects/).
- **What to say**: the message that seeds the session, just as if you'd typed it.
- **When to fire**: a cron expression and an optional timezone.
- **Who sent it**: an author, so the triggered session has clear permissions and an audit trail.

When the expression next matches the current time, Ren creates a session with that message. The agent runs to completion, and the next firing waits for the following match.

## Cron expression syntax

Cron triggers use the standard five-field cron format:

```
minute  hour  day-of-month  month  day-of-week
```

| Field        | Allowed values        |
| ------------ | --------------------- |
| Minute       | 0 to 59               |
| Hour         | 0 to 23               |
| Day of month | 1 to 31               |
| Month        | 1 to 12 or JAN to DEC |
| Day of week  | 0 to 6 or SUN to SAT  |

Some common patterns:

- `0 9 * * MON`: every Monday at 09:00
- `0 0 * * *`: midnight every day
- `30 8 1 * *`: 08:30 on the first of every month
- `0 */6 * * *`: every six hours

The `timezone` field determines which clock the expression is evaluated against. If you set it to `America/New_York`, `0 9 * * MON` fires at 9 AM Eastern, even when daylight saving shifts the UTC offset.

## Lifecycle

Scheduling is durable: if the platform has a brief outage, missed firings are retried rather than dropped silently.

- **Enabled**: the trigger fires on its schedule.
- **Disabled**: firing pauses, but the configuration is kept so you can re-enable it later.
- **Archived**: the trigger is removed and no further sessions are created.

Changes to the schedule or timezone take effect right away; editing the message applies on the next firing.

## Cron triggers vs. running agents on demand

Running an agent on demand (through the UI, the CLI, or the API) is the right choice when the work is ad-hoc or user-initiated. Cron triggers fill a different niche:

- **Recurring, unattended work.** The agent runs whether or not anyone is online.
- **Consistent timing.** The schedule is deterministic; the session fires at the same wall-clock time every cycle.
- **Decoupled from human action.** No one needs to remember to start the session.

The trade-off is that cron triggers are inherently less flexible than on-demand runs. If the schedule or input needs to change, you must update the trigger itself. You can't improvise at firing time.

## What you can do with cron triggers

Common patterns include:

- **Periodic digests**: an agent that reads recent activity and posts a summary to Slack every Monday morning.
- **Automated reviews**: an agent that reviews pull requests opened in the last 24 hours each night.
- **Data pipelines**: an agent that fetches external data, transforms it, and writes results on a fixed cadence.
- **Health checks**: an agent that probes an internal service and alerts on failures, running every few minutes.

For the step-by-step process of creating and managing cron triggers, see the [schedule a cron trigger](/docs/guides/automate/schedule-cron-trigger/) guide.