iii-cron

Schedule functions to execute at specific times using cron expressions.

Install

iii worker add iii-cron

Resolves from the worker registry at workers.iii.dev.

Skills

Install the iii-cron agent skill for Claude Code, Cursor, and 30+ other agents:

npx skills add iii-hq/iii --full-depth --skill iii-cron

Sample Configuration

- name: iii-cron
  config:
    adapter:
      name: redis
      config:
        redis_url: ${REDIS_URL:redis://localhost:6379}

Configuration

Runtime configuration (hot reload)

iii-cron registers its configuration with the builtin configuration worker under the id iii-cron, so the adapter above can be read and changed at runtime (e.g. configuration::set { id: "iii-cron", value: { ... } }) without restarting the engine. The config.yaml block is the seed used on first boot only; afterwards the configuration entry is the runtime source of truth and a runtime edit survives engine restarts. Values are validated against the schema at set time, and ${VAR:default} placeholders are expanded on read.

A change to adapter is a full hot-swap, all without a restart: the new lock backend is built first (the swap is gated — a value that fails to build keeps the previous backend, config, and jobs), then the old backend is shut down (stopping its tasks and releasing its locks), and finally every live cron job is re-registered onto the new backend best-effort (a single job that fails to re-register is logged while the rest move over). Shutting the old backend down before re-registering avoids a window where a job runs on both backends at once; the trade-off is a brief scheduling gap on this instance — a job whose fire time lands in the swap window is skipped, not run twice. Across a multi-instance deployment the old and new lock backends still cannot coordinate while instances sit on different backends mid-migration, so a job could run on more than one instance — prefer a quiet moment to repoint the adapter.

Adapters

kv

Built-in adapter using process-local locks. Suitable for single-instance deployments.

Warning: When running multiple engine instances, the kv adapter does not provide reliable distributed locking — the same cron job may execute on every instance simultaneously. Use the redis adapter for multi-instance deployments.

name: kv
config:
  lock_ttl_ms: 30000
  lock_index: cron_locks

store_method / file_path / save_interval_ms configure the shared backing store and take effect only for the first kv adapter built in the process; lock_ttl_ms and lock_index apply per adapter instance.

redis

Uses Redis for distributed locking to prevent duplicate job execution across multiple engine instances. The lock TTL and key prefix are fixed by the adapter; only the connection URL is configurable.

name: redis
config:
  redis_url: ${REDIS_URL:redis://localhost:6379}

Trigger Type: cron

Cron Expression Format

* * * * * * [*]
│ │ │ │ │ │  │
│ │ │ │ │ │  └── Year (optional, * for any)
│ │ │ │ │ └──── Day of week (0–7, Sun=0 or 7)
│ │ │ │ └────── Month (1–12)
│ │ │ └──────── Day of month (1–31)
│ │ └────────── Hour (0–23)
│ └──────────── Minute (0–59)
└──────────── Second (0–59)

Trigger Event Payload

Sample Code

const fn = iii.registerFunction(
  { id: 'jobs::cleanupOldData' },
  async (event) => {
    console.log('Running cleanup scheduled at:', event.scheduled_time)
    return {}
  },
)

iii.registerTrigger({
  type: 'cron',
  function_id: fn.id,
  config: { expression: '0 0 2 * * * *' },
})

Common Cron Expressions

Distributed Execution

When running multiple III Engine instances, the once-only execution guarantee applies only with the redis adapter. Select it with adapter.name: redis and configure adapter.config.redis_url so all engine instances share the same Redis-backed lock store.

The default kv adapter uses process-local locks. In multi-instance deployments, each engine instance can acquire its own local lock and run the same cron job.

Cron handlers receive the trigger payload described above: trigger, job_id, scheduled_time, and actual_time.