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

# Scheduling agents with cron

> Run an installed agent automatically on a cron schedule — how schedules fire, dry_run versus live, and what last-fired and next-fire mean.

You can give any installed agent a cron schedule so it runs automatically on a recurring cadence, with no webhook and no manual click. Set the schedule from the CLI and the platform fires the agent at each scheduled time.

## How it works

Every installation can carry a standard five-field cron expression. `*/5 * * * *` is every five minutes; `0 9 * * 1` is 09:00 every Monday. A background scheduler checks due schedules roughly once a minute and, when a schedule's time arrives, starts a run of that agent — the same kind of run a webhook or a manual trigger would start. A scheduled run is recorded as a system run, with no human user attached, and trigger type `cron`.

You manage schedules with three commands:

```bash theme={null}
jstm agent schedule show  <installation_id>
jstm agent schedule set   <installation_id> --cron "<expr>" [--env dry_run|live]
jstm agent schedule clear <installation_id>
```

## dry\_run and live

A scheduled run has a run mode, set with `--env`:

* `dry_run`, the default — the agent runs but side-effecting actions are held back. Use this to confirm the schedule and the agent behave as expected.
* `live` — the agent runs for real, with side effects.

`dry_run` is the default on purpose. Live is an explicit opt-in: you must pass `--env live` to schedule a real run.

## last-fired and next-fire

`schedule show` reports two timestamps.

**Last fired** is the last time this schedule actually triggered a run. It shows `—` until the schedule fires for the first time.

**Next fire** is the next time it will run. The server computes this as the first scheduled time strictly after now, so a frequent schedule never shows a time that has already passed.

## Times are UTC

<Warning>
  All cron schedules are evaluated in UTC in this version. There is no per-schedule timezone yet. `0 9 * * *` means 09:00 UTC, not 09:00 local. `schedule show` always labels the timezone as UTC to make this explicit.
</Warning>

## Good to know

**Missed runs during downtime aren't replayed one by one.** If the scheduler is down across several scheduled times, it fires the most recent missed one once when it comes back, then resumes normally. It does not fire a burst for every time it missed.

**Changing the schedule resets its clock.** When you set or change a schedule, the next run is its next future time. It will not immediately fire for a time in the past.

**`set --env` defaults to `dry_run` every time.** Because `set` always sends a run mode, re-running `set` to change only the expression without repeating `--env live` puts the schedule back to `dry_run`. Always include `--env live` when you set a live schedule.

**Clearing stops all future runs.** `schedule clear` removes the schedule. The agent stays installed and can still be run manually or by other triggers.

## See also

* [Schedule an agent](/guides/schedule-an-agent) — walkthrough.
* [`jstm agent schedule`](/cli/agent-schedule) — full reference.