> ## Documentation Index > Fetch the complete documentation index at: https://docs.turen.io/llms.txt > Use this file to discover all available pages before exploring further. # Automations > Run durable scheduled and event-driven agent workflows Automations are durable workflows that run on their own in TurenOS sessions and deliver results back to you. Each automation has one trigger and 1–12 ordered steps. Use an automation for recurring, scheduled, or event-driven work — a one-off task belongs in the current session instead. ## Triggers An automation has exactly one trigger: an interval, a cron schedule, or a local event. Provide exactly one of `interval_seconds`, `cron_expression`, or `event_trigger` when creating it. ### Interval `interval_seconds` sets how often the automation runs, in whole seconds. The minimum is 60 seconds. ### Cron `cron_expression` uses five fields — minute, hour, day of month, month, weekday — for example `*/5 * * * *` or `0 9 * * MON-FRI`. Month and weekday names are accepted (`JAN`–`DEC`, `SUN`–`SAT`). Cron fire times are timezone-aware. Pass an IANA `timezone` such as `America/New_York`; it defaults to `UTC`. ### Event triggers Event triggers are local only — no network triggers are supported. There are two kinds: * **file-change**: fires when a file under the automation's directory changes. `paths` lists 1–20 relative glob patterns (for example `src/**/*.ts`). Patterns must be relative to the automation directory: no absolute paths, no `..` segments. Rapid bursts are coalesced with `debounceMs`, which defaults to 1000 ms and caps at 60000 ms. * **session-end**: fires when a local session in the automation's directory ends. Optionally filter by `outcomes` (`success` and/or `failure`), `sessionID`, or `agent`. Omit a filter to match any value. An automation's own runs never re-trigger it. Event firing (`fireEvent`) is core-only: it is driven by the local scheduler watching the filesystem and session events. It is not exposed on the HTTP API. ## Steps Each step is an agent turn or a skill invocation with a name and a task. A step can name a `skill` (the task becomes its instructions) or omit it for a plain agent turn. Later steps can reference earlier steps with `{{ steps..output }}` and `{{ steps..artifacts }}`; only earlier steps may be referenced. Step IDs are derived from step names (lowercased, runs of non-alphanumerics become underscores) and must match `^[A-Za-z][A-Za-z0-9_-]*$`. Every step also sees trigger context: `{{ trigger.type }}`, `{{ trigger.scheduledAt }}`, and `{{ trigger.payload. }}` (for example the changed `file` on a file-change trigger, or the `sessionID` and `outcome` on a session-end trigger). Each step inherits the automation's agent and model unless it overrides them with its own `agent` or `model`. ### Conditional steps with `when` `when` is an optional condition string evaluated before the step runs, after bindings are resolved. When it resolves to a falsy value — `false`, `0`, `no`, `off`, `skip`, `null`, `undefined`, or empty — the step is skipped and the run moves on. Omit `when` to always run the step. Conditions are limited to 2000 characters. ### Failure policy with `onFailure` `on_failure` decides what a step failure does to the run: * `stop` (default): the step failure fails the run. * `continue`: the error is recorded on the step output and the run proceeds to the next step. ## Runs lifecycle Each firing creates a run that moves through these statuses: | Status | Meaning | | ----------- | ------------------------------------------------------------------------------------- | | `claimed` | Created and leased to a scheduler worker, waiting to start. | | `running` | Executing steps in its own session. | | `succeeded` | All steps completed (steps skipped by `when` or continued after failure still count). | | `failed` | A step failed with `stop`, or the run errored. | | `cancelled` | Cancelled while `claimed` or `running`. | | `skipped` | Never executed because another run of the same automation was already active. | | `stale` | Was `running` but lost its lease and was swept up by the claimer. | You can watch this in the app: the automation view shows each automation's schedule and health, with a visual workflow map and trigger inspector for building steps. Automation builder with workflow map and schedule trigger inspector Selecting a run shows its steps, outputs, and status alongside recent-run history and health. Automation run detail with recent runs, health, and output ### Overlap: skip Automations never run concurrently with themselves. The overlap policy is always `skip`: if a firing happens while a previous run is still `claimed` or `running` under a live lease, the new run is recorded as `skipped` instead of executing. ## Caps and expiry * At most **50** automations may be active at once, with at most **10** per project directory. * Automations stop running after **seven days**: expiry must be in the future and at most seven days out. Expired automations keep their history but no longer fire. * Automations can be `active`, `paused`, `expired`, renamed, rescheduled, or deleted. Deleting requires cancelling any active run first. ## Agent tools Agents manage automations with three tools: * `automation_list` — list this machine's automations. Call it before creating or changing one so you know what already exists. * `automation_create` — create one automation with a trigger plus 1–12 ordered steps. Report the returned id and expiry to the user. * `automation_update` — rename an automation, change its interval, cron, or event trigger, change its inherited agent/model, replace its whole step list, or pause, resume, or delete it. Returns `null` when the automation was deleted. Creating or updating an automation requires permission, and runs inherit normal tool permissions — keep automation directories, integrations, and commands narrowly scoped. ## Blueprints Start from one of these shapes and adapt the trigger and steps: **Scheduled checkup** — interval trigger (for example every 3600 seconds) with two steps: gather state, then summarize and deliver. ```text theme={null} Automation: Hourly deploy watch Trigger: every 3600 seconds Step 1 "collect": check the deployment feed and record current status Step 2 "report": summarize {{ steps.collect.output }} into a short status update ``` **Weekday report** — cron trigger (`0 9 * * MON-FRI`, timezone set to your locale) with a research step followed by a report step. ```text theme={null} Automation: Weekday repo digest Trigger: cron 0 9 * * MON-FRI Step 1 "changes": list notable repository changes since the last run Step 2 "digest": turn {{ steps.changes.output }} into a morning digest ``` **File watcher** — file-change trigger on `src/**/*.ts` with a single verification step. ```text theme={null} Automation: Typecheck on change Trigger: file-change on src/**/*.ts Step 1 "verify": typecheck the project and report errors in {{ trigger.payload.file }} ``` **Session follow-up** — session-end trigger filtered to `failure` outcomes, with a triage step that only runs when there is something to triage. ```text theme={null} Automation: Failure triage Trigger: session-end, outcomes [failure] Step 1 "triage": when {{ trigger.payload.sessionID }} is set, summarize what failed ``` ## Example uses * Recheck a deployment or incident feed on an interval * Deliver a weekday-morning repository digest via cron * Typecheck or lint changed files as they are saved * Triage failed sessions automatically when they end * Run a research step followed by a report step, skipping the report when there is nothing new