> ## 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.

# Schedule an agent

> Put an installed agent on a recurring cron schedule, verify it, switch it to live, and clear it.

This guide puts an installed agent on a recurring schedule, verifies it, promotes it to live, and later clears it. You need the agent's installation id, from `jstm agent installations`. All times are UTC.

<Steps>
  <Step title="Find the installation">
    ```bash theme={null}
    jstm agent installations
    ```

    The table includes **Schedule** and **Next fire** columns, so you can see which installations are already scheduled. Copy the installation id you want.
  </Step>

  <Step title="Set a schedule, starting in dry_run">
    Start in `dry_run` so nothing side-effecting happens while you confirm the cadence:

    ```bash theme={null}
    jstm agent schedule set 8c41f2b9-77de-4a30-b0c5-2e1f6a9d4b77 --cron "*/5 * * * *"
    ```

    `--cron` takes a standard five-field cron expression, evaluated in UTC. `--env` defaults to `dry_run`, so you can omit it here.

    The expression is checked before anything is sent. A typo like `--cron "not-a-cron"` fails immediately with a non-zero exit and no change made.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    jstm agent schedule show 8c41f2b9-77de-4a30-b0c5-2e1f6a9d4b77
    ```

    ```text theme={null}
            Cron Schedule
     Schedule     */5 * * * *
     Environment  dry_run
     Last fired   —
     Next fire    2026-07-10T12:05:00+00:00
     Timezone     UTC
    ```

    **Next fire** tells you exactly when the first run will happen. **Last fired** stays `—` until it runs once. Add `--json` for machine-readable output.
  </Step>

  <Step title="Promote to live">
    When you're happy with the dry runs, switch the run mode to `live`:

    ```bash theme={null}
    jstm agent schedule set 8c41f2b9-77de-4a30-b0c5-2e1f6a9d4b77 --cron "*/5 * * * *" --env live
    ```

    <Warning>
      Always repeat both `--cron` and `--env live`. `set` sends the run mode every time and defaults it to `dry_run`, so running `set` again with only `--cron` silently drops the schedule back to `dry_run`.
    </Warning>
  </Step>

  <Step title="Clear the schedule">
    To stop scheduled runs while leaving the agent installed:

    ```bash theme={null}
    jstm agent schedule clear 8c41f2b9-77de-4a30-b0c5-2e1f6a9d4b77
    ```
  </Step>
</Steps>

## Common cron expressions

All expressions are evaluated in UTC.

| Expression    | Runs                                    |
| ------------- | --------------------------------------- |
| `*/5 * * * *` | Every five minutes                      |
| `0 * * * *`   | Every hour, on the hour                 |
| `0 9 * * *`   | 09:00 UTC daily                         |
| `0 9 * * 1`   | 09:00 UTC every Monday                  |
| `0 0 1 * *`   | Midnight UTC on the first of each month |

## Notes

* UTC only. There is no per-schedule timezone yet.
* If the platform is down across several scheduled times, it fires the most recent missed one once on recovery, not a burst.
* Changing the schedule resets the clock to the next future time. It won't back-fire.

## See also

* [Scheduling agents with cron](/features/scheduling) — how schedules behave.
* [`jstm agent schedule`](/cli/agent-schedule) — full reference.