Skip to content
Back to search

cronstable

A job scheduler with retries, alerts, saved run history, workflows, and dashboards for single machines and clusters.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ptweezy/cronstable with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ptweezy/cronstable'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ptweezy--cronstable/badge.svg)](/listings/ptweezy--cronstable)

HTML

<a href="/listings/ptweezy--cronstable"><img src="/api/listings/ptweezy--cronstable/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install cronstable with [pipx](https://github.com/pypa/pipx), or with `pip install cronstable` inside a virtual environment. For Docker, Homebrew, WinGet, and standalone binaries, see [installation](#installation).

pipx install cronstable

Create a `cronstable.yaml` file with your first job:

jobs:
  - name: hello
    command: echo hello from cronstable
    schedule: "* * * * *"        # every minute
    captureStdout: true

web:
  listen:
    - http://127.0.0.1:8080      # optional: the REST API and dashboard

Start the scheduler. It runs in the foreground:

cronstable -c cronstable.yaml

Open <http://127.0.0.1:8080/> to watch the `hello` job's output in the [dashboard](#web-dashboard). The job runs once a minute, and schedules use UTC unless a job sets a [time zone](#time-zones). cronstable picks up changes to the file within a minute, so you can add jobs without restarting it.

Four short [tutorials](#tutorials) build on this configuration:

* [Retry failed jobs, and alert when the retries fail](#tutorial-1-retry-failed-jobs-and-alert-when-retries-fail). * [Survive restarts and catch up missed runs](#tutorial-2-survive-restarts-catch-up-what-was-missed). * [Chain tasks into a durable workflow with an approval gate](#tutorial-3-your-first-dag-a-durable-pipeline). * [Coordinate two replicas with leader election](#tutorial-4-coordinate-two-replicas).

To follow your jobs from a phone, pair the [iOS app](#ios-app) from the dashboard. To see every feature at once, start the nine-node [grand tour](https://github.com/ptweezy/cronstable/tree/main/example/grand-tour) from a clone of this repository:

docker compose -f example/grand-tour/docker-compose.yml up --build

To run an existing crontab exported with `crontab -l`, pass the file to `-c`: `cronstable -c my.crontab`. A system crontab such as `/etc/crontab` has an extra user column, so convert its entries to YAML (see [classic crontab files](#classic-crontab-files)).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,952 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ![The cronstable wordmark; its l is a live self-balancing double pendulum: it sways through the theme glitches, collapses when the signal drops, and swings itself back upright](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/logo-balance.webp)
  2. [![PyPI version](https://img.shields.io/pypi/v/cronstable.svg?logo=pypi&logoColor=white&color=0073b7)](https://pypi.org/project/cronstable/)
  3. [![GitHub release](https://img.shields.io/github/v/release/ptweezy/cronstable?logo=github&color=8a2be2)](https://github.com/ptweezy/cronstable/releases/latest)
  4. [![App Store](https://img.shields.io/itunes/v/6801933039?logo=apple&logoColor=white&label=App%20Store&color=0d96f6)](https://apps.apple.com/app/cronstable/id6801933039)
  5. [![PyPI status](https://img.shields.io/pypi/status/cronstable.svg?color=2ea44f)](https://pypi.org/project/cronstable/)
  6. [![Coverage](https://img.shields.io/codecov/c/github/ptweezy/cronstable?logo=codecov&logoColor=white&color=f01f7a)](https://codecov.io/gh/ptweezy/cronstable)
  7. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ptweezy/cronstable/badge)](https://scorecard.dev/viewer/?uri=github.com/ptweezy/cronstable)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ptweezy/cronstable/blob/main/LICENSE)
  9. [![Release downloads](https://img.shields.io/github/downloads/ptweezy/cronstable/total?logo=github&label=binary%20downloads&color=fb8c00)](https://github.com/ptweezy/cronstable/releases)
  10. [![Container image](https://img.shields.io/badge/ghcr.io-ptweezy%2Fcronstable-2496ed?logo=docker&logoColor=white)](https://github.com/ptweezy/cronstable/pkgs/container/cronstable)
  11. [![Docker Hub](https://img.shields.io/badge/docker.io-ptweezy%2Fcronstable-2496ed?logo=docker&logoColor=white)](https://hub.docker.com/r/ptweezy/cronstable)
  12. [![Python versions](https://img.shields.io/pypi/pyversions/cronstable.svg?logo=python&logoColor=ffd343&color=306998)](https://pypi.org/project/cronstable/)
  13. [![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-00bcd4)](https://github.com/ptweezy/cronstable/releases/latest)
  14. [![Architectures](https://img.shields.io/badge/arch-amd64%20%7C%20amd64v3%20%7C%20arm64%20%7C%20armv7%20%7C%20armv6%20%7C%20i686%20%7C%20ppc64le%20%7C%20s390x%20%7C%20riscv64%20%7C%20loong64%20%7C%20mips64le%20%7C%20armel-c2185b)](https://github.com/ptweezy/cronstable/releases/latest)
  15. / kraahn-stuh-bl /
  16. cronstable is a feature-rich job scheduler and simple workflow orchestrator for anything from a single machine to a cluster,
  17. built with efficiency, security, and stability in mind. It runs your commands
  18. on a schedule, defined in YAML or loaded from an existing crontab, and adds
  19. retries, alerts, saved run history, workflows, and dashboards for the web, the
  20. terminal, and iOS.
  21. [Live demo](https://demo.cronstable.com) ·
  22. [Quick start](#quick-start) ·
  23. [Installation](#installation) ·
  24. [Documentation](https://github.com/ptweezy/cronstable/wiki) ·
  25. [iOS app](#ios-app)
  26. [![cronstable web dashboard, animated: a tour of the live job overview, the command palette, a live log tail, a workflow's task graph, the nine-node cluster and fleet matrix, the wallboard and incident timeline, the device-pairing QR panel for encrypted push alerts, and the accessibility options (a color-vision-safe palette and larger UI scale)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-reel.webp)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-reel.webp)
  27. > A tour of the web dashboard. To try it in your browser, open the
  28. > [live demo](https://demo.cronstable.com).
  29. ## Why cronstable?
  30. ### Scheduling
  31. * **YAML and classic crontab files**: define jobs in YAML, or load an existing
  32. crontab (see [classic crontab files](#classic-crontab-files)).
  33. * **Business-day and hashed schedules**: run on the last weekday of the month
  34. or the third Friday, and spread a fleet's jobs across the hour with `H` (see
  35. [schedules](#schedules)).
  36. * **Second-level schedules and time zones**: run jobs as often as every
  37. second, and evaluate each job's schedule in any time zone (see
  38. [second-level schedules](#second-level-schedules) and
  39. [time zones](#time-zones)).
  40. * **iCal calendar export**: subscribe to upcoming runs in your calendar app,
  41. or view them in the dashboard's week calendar (see
  42. [calendar export](https://github.com/ptweezy/cronstable/wiki/Calendar-Export)).
  43. * **Schedule introspection**: ask why a job did or didn't run at a given
  44. moment, and get a field-by-field answer from the scheduler's own match test.
  45. Collision heatmaps, duplicate detection, and slot suggestions help you place
  46. new jobs (see [schedule introspection](#schedule-introspection)).
  47. * **Schedule linting**: catch schedules that can never run, uneven intervals,
  48. and times that daylight saving time skips or repeats (see
  49. [schedule linting](https://github.com/ptweezy/cronstable/wiki/Schedule-Linting)).
  50. ### Failure handling
  51. * **Retries with backoff**: retry failed runs with exponential backoff, and
  52. choose whether a nonzero exit status or output on stderr or stdout counts as
  53. a failure (see [failure detection and retries](#failure-detection-and-retries)).
  54. * **Result verification**: check a job's output before recording success or
  55. starting downstream tasks (see
  56. [result verification](https://github.com/ptweezy/cronstable/wiki/Result-Verification)).
  57. * **Alerts**: report failures through Sentry, email, Slack-compatible
  58. webhooks, shell commands, and the Windows Event Log (see
  59. [reporting](#reporting)).
  60. * **End-to-end encrypted push notifications**: send alerts to the
  61. [iOS app](#ios-app) that only paired devices can decrypt (see
  62. [push notifications](#push-notifications)).
  63. * **Late-run detection**: alert when a run is missing, late, or running too
  64. long, and mark the job as overdue in the dashboards (see
  65. [late-run detection](#late-run-detection-sla-monitoring)).
  66. ### Durability and orchestration
  67. * **Opt-in durable state**: keep run history and pending retries across
  68. restarts, catch up missed runs, and give job commands shared storage, locks,
  69. and idempotency keys (see
  70. [durable state](https://github.com/ptweezy/cronstable/wiki/Durable-State)).
  71. * **Durable workflows**: run tasks as a directed acyclic graph (DAG) with
  72. dependencies, data sharing, dynamic fan-out, conditional branching, sensors,
  73. and approval gates
  74. (see [workflow orchestration](https://github.com/ptweezy/cronstable/wiki/Orchestration-and-DAGs)).
  75. * **Selective workflow recovery**: retry failed tasks or replay failed dates
  76. while reusing successful results (see
  77. [workflow recovery](https://github.com/ptweezy/cronstable/wiki/Workflow-Recovery)).
  78. * **Shared resource pools**: limit capacity across jobs and workflow tasks,
  79. with priority queues and deadlines (see
  80. [resource pools](https://github.com/ptweezy/cronstable/wiki/Resource-Pools)).
  81. ### Observability and control
  82. * **[Web](#web-dashboard), [terminal](#terminal-dashboard), and
  83. [iOS](#ios-app) dashboards**: follow live logs, review history, control jobs
  84. and workflows, and monitor the cluster.
  85. * **HTTP API**: read job status and history, and start, cancel, or pause jobs
  86. (see [HTTP API](#http-api)).
  87. * **Status badges**: show a job's live status in a README or wiki with an SVG
  88. badge (see [status badges](#status-badges)).
  89. * **Runtime pause and resume**: pause scheduled runs for maintenance without
  90. editing configuration (see
  91. [pausing jobs](https://github.com/ptweezy/cronstable/wiki/Pausing-Jobs)).
  92. * **Prometheus and statsd metrics**: track outcomes, durations, retries, and
  93. cluster health (see [metrics](#metrics)).
  94. * **Per-job resource monitoring**: track CPU time and peak memory across each
  95. job's process tree (see [resource monitoring](#resource-monitoring)).
  96. * **Per-job resource limits**: cap each run's CPU, memory, and process count
  97. with cgroup v2 on Linux and Job Objects on Windows (see
  98. [resource limits](#resource-limits)).
  99. * **Built-in TLS**: serve the API over HTTPS, optionally require client
  100. certificates, and rotate certificates without a restart (see
  101. [TLS and client certificates](#tls-and-client-certificates)).
  102. * **MCP server**: let AI agents inspect jobs and debug schedules, read-only by
  103. default, with optional control (see
  104. [MCP](https://github.com/ptweezy/cronstable/wiki/MCP)).
  105. ### Fleets
  106. * **Opt-in clustering and leader election**: coordinate which replica runs
  107. scheduled jobs through a Kubernetes Lease, an etcd lease, a shared
  108. filesystem, or mutual TLS between peers (see
  109. [clustering and leader election](#clustering-and-leader-election)).
  110. * **Job-set ID**: compare configuration fingerprints to detect drift between
  111. replicas (see [job-set ID](#job-set-id)).
  112. ### Deployment
  113. * **Prebuilt releases**: container images in eight variants, and
  114. self-contained binaries for Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD,
  115. and illumos (see [installation](#installation)).
  116. * **Built for restricted containers**: run as a non-root user with a read-only
  117. root filesystem and restricted Kubernetes security settings (see
  118. [production container deployment](#production-container-deployment)).
  119. * **Native Windows support**: run as a Windows service, install with WinGet or
  120. an MSI, and import Task Scheduler tasks (see [Windows](#windows)).
  121. ## Quick start
  122. Install cronstable with [pipx](https://github.com/pypa/pipx), or with
  123. `pip install cronstable` inside a virtual environment. For Docker, Homebrew,
  124. WinGet, and standalone binaries, see [installation](#installation).
  125. ```shell
  126. pipx install cronstable
  127. ```
  128. Create a `cronstable.yaml` file with your first job:
  129. ```yaml
  130. jobs:
  131. - name: hello
  132. command: echo hello from cronstable
  133. schedule: "* * * * *" # every minute
  134. captureStdout: true
  135. web:
  136. listen:
  137. - http://127.0.0.1:8080 # optional: the REST API and dashboard
  138. ```
  139. Start the scheduler. It runs in the foreground:
  140. ```shell
  141. cronstable -c cronstable.yaml
  142. ```
  143. Open <http://127.0.0.1:8080/> to watch the `hello` job's output in the
  144. [dashboard](#web-dashboard). The job runs once a minute, and schedules use UTC
  145. unless a job sets a [time zone](#time-zones). cronstable picks up changes to
  146. the file within a minute, so you can add jobs without restarting it.
  147. Four short [tutorials](#tutorials) build on this configuration:
  148. * [Retry failed jobs, and alert when the retries fail](#tutorial-1-retry-failed-jobs-and-alert-when-retries-fail).
  149. * [Survive restarts and catch up missed runs](#tutorial-2-survive-restarts-catch-up-what-was-missed).
  150. * [Chain tasks into a durable workflow with an approval gate](#tutorial-3-your-first-dag-a-durable-pipeline).
  151. * [Coordinate two replicas with leader election](#tutorial-4-coordinate-two-replicas).
  152. To follow your jobs from a phone, pair the [iOS app](#ios-app) from the
  153. dashboard. To see every feature at once, start the nine-node
  154. [grand tour](https://github.com/ptweezy/cronstable/tree/main/example/grand-tour)
  155. from a clone of this repository:
  156. ```shell
  157. docker compose -f example/grand-tour/docker-compose.yml up --build
  158. ```
  159. To run an existing crontab exported with `crontab -l`, pass the file to `-c`:
  160. `cronstable -c my.crontab`. A system crontab such as `/etc/crontab` has an
  161. extra user column, so convert its entries to YAML (see
  162. [classic crontab files](#classic-crontab-files)).
  163. ## Installation
  164. cronstable aims to run on as many platforms and CPU architectures as possible.
  165. Every release publishes Linux container images, standalone binaries for Linux,
  166. macOS, Windows, FreeBSD, OpenBSD, NetBSD, and illumos, packages for Linux and
  167. FreeBSD, and Windows installers. If
  168. your platform or architecture is missing,
  169. [open an issue](https://github.com/ptweezy/cronstable/issues/new) or send a
  170. pull request (see
  171. [CONTRIBUTING.md](https://github.com/ptweezy/cronstable/blob/main/CONTRIBUTING.md)).
  172. ### Run with Docker
  173. Every release publishes multi-architecture images to the GitHub Container
  174. Registry (`ghcr.io/ptweezy/cronstable`) and Docker Hub (`ptweezy/cronstable`).
  175. Mount your configuration file and start the container:
  176. ```shell
  177. docker run --rm -p 8080:8080 \
  178. -v "$PWD/cronstable.yaml:/etc/cronstable.d/cronstable.yaml:ro" \
  179. ghcr.io/ptweezy/cronstable:latest
  180. ```
  181. Inside a container, the dashboard must listen on all interfaces, so change the
  182. quick start's listener to `http://0.0.0.0:8080`. Before you expose it beyond
  183. your machine, set an [authentication token](#authentication).
  184. The default image is based on Debian slim and supports seven Linux platforms:
  185. `amd64`, `arm64`, `386`, `arm/v7`, `ppc64le`, `s390x`, and `riscv64`. It runs
  186. as a non-root user and reads its configuration from `/etc/cronstable.d`. Each
  187. release also publishes Alpine, Ubuntu, RHEL (UBI), Fedora, openSUSE, Amazon
  188. Linux, and distroless variants, tagged with a `-<distro>` suffix such as
  189. `latest-alpine`. Every variant also has `-amd64v3` tags, such as
  190. `latest-amd64v3`, for [x86-64-v3 CPUs](#choose-an-x86-64-build). For each
  191. variant's platforms, see
  192. [installation](https://github.com/ptweezy/cronstable/wiki/Installation) in the
  193. wiki.
  194. In production, pin a release version instead of `latest`. For a hardened
  195. Kubernetes or Docker setup, see
  196. [production container deployment](#production-container-deployment).
  197. ### Install using pip
  198. cronstable requires Python 3.11 or later. Install it in a virtual environment:
  199. ```shell
  200. pip install cronstable
  201. ```
  202. Or let [pipx](https://github.com/pypa/pipx) create an isolated environment for
  203. you:
  204. ```shell
  205. pipx install cronstable
  206. ```
  207. Optional extras install the dependencies of specific features: `push` for
  208. [push notifications](#push-notifications), `discovery` for
  209. [LAN discovery](https://github.com/ptweezy/cronstable/wiki/LAN-Discovery),
  210. `kubernetes` for the official Kubernetes client library, and `speedups` for
  211. uvloop, orjson, and isal. For example, run `pip install "cronstable[push]"`. On a
  212. system with an older Python, use a
  213. [standalone binary](#install-a-standalone-binary).
  214. ### Install using Homebrew or WinGet
  215. Homebrew and WinGet install prebuilt releases, so you don't need Python. On
  216. macOS or Linux, use Homebrew:
  217. ```shell
  218. brew install ptweezy/tap/cronstable
  219. ```
  220. On Windows, use WinGet:
  221. ```shell
  222. winget install ptweezy.cronstable
  223. ```
  224. Upgrade later with `brew upgrade cronstable` or
  225. `winget upgrade ptweezy.cronstable`.
  226. WinGet runs a signed setup program that installs the per-machine MSI. Approve
  227. the administrator prompt, then open a new shell so that `cronstable` is on your
  228. `PATH`. The installer registers the Windows service without starting it, and
  229. creates a configuration directory that only SYSTEM and Administrators can
  230. write. The service starts at the next boot and runs no jobs until you add
  231. configuration. For catalog availability and how to switch from a portable
  232. install, see the
  233. [WinGet installation guide](https://github.com/ptweezy/cronstable/wiki/Installation#install-using-winget).
  234. ### Install a standalone binary
  235. Every release attaches self-contained binaries that embed Python, so the target
  236. system doesn't need it. Download one from the
  237. [releases page](https://github.com/ptweezy/cronstable/releases), or use
  238. `curl`:
  239. ```shell
  240. # For an x86-64 Linux CPU with glibc. Use amd64v3 instead of amd64 on
  241. # x86-64-v3 CPUs, and append -musl on Alpine.
  242. curl -fsSL -o cronstable \
  243. https://github.com/ptweezy/cronstable/releases/latest/download/cronstable-linux-amd64
  244. chmod +x cronstable
  245. ./cronstable --version
  246. ```
  247. Releases include these builds:
  248. * Linux: glibc and musl builds for `amd64`, `amd64v3`, `arm64`, `i686`,
  249. `armv7`, `armv6`, `ppc64le`, `s390x`, `riscv64`, and `loong64`, plus glibc
  250. builds for `mips64le` and `armel`
  251. * macOS: `amd64`, `amd64v3`, and `arm64`, signed and notarized by Apple
  252. * Windows: `amd64`, `amd64v3`, `arm64`, and `i686`
  253. * FreeBSD: `amd64`, `amd64v3`, and `arm64`
  254. * OpenBSD, NetBSD, and illumos: `amd64` and `amd64v3`
  255. * Packages: `.deb`, `.rpm`, Alpine `.apk`, and FreeBSD `.pkg`
  256. The `amd64`, `amd64v3`, `arm64`, and `s390x` glibc builds need only glibc 2.17,
  257. so they run on RHEL 7 and later. The `ppc64le` build needs glibc 2.28 (RHEL 8
  258. and later). The `.deb` and `.rpm` packages also install a systemd unit and a
  259. starter configuration in `/etc/cronstable.d`. They don't start the service;
  260. run `systemctl enable --now cronstable` when your configuration is ready.
  261. Windows builds come in four formats:
  262. * `cronstable-windows-<arch>-setup.exe`: a signed setup program for `amd64`,
  263. `amd64v3`, and `arm64` that installs the MSI. WinGet runs this setup.
  264. * `cronstable-windows-<arch>.exe`: a single-file executable.
  265. * `cronstable-windows-<arch>.zip`: a one-directory build that extracts to a
  266. single `cronstable` folder and can host the
  267. [Windows service](#windows-service).
  268. * `cronstable-windows-<arch>.msi`: a machine-wide installer that registers the
  269. service, for deployment through Group Policy, Intune, or SCCM (see
  270. [Windows MSI](https://github.com/ptweezy/cronstable/wiki/Windows-MSI)).
  271. At startup, a standalone binary unpacks its embedded Python runtime into a
  272. temporary directory, so on a read-only root filesystem it needs a small
  273. writable, executable temporary mount. The container images, pip installs, and
  274. the Windows `.zip` and `.msi` builds don't unpack anything at startup. For a
  275. tmpfs or `emptyDir` recipe, the full asset table, and the other install
  276. methods (ubi, mise, and Nix), see
  277. [installation](https://github.com/ptweezy/cronstable/wiki/Installation) in the
  278. wiki.
  279. #### Choose an x86-64 build
  280. Every x86-64 binary, package, and Docker image comes in two builds:
  281. * `amd64v3` (recommended for compatible CPUs): uses an optimized embedded
  282. Python runtime and requires the full x86-64-v3 feature set, as on Intel
  283. Haswell and newer Core and Xeon CPUs, or AMD Excavator and Zen.
  284. * `amd64` (compatibility build): runs on any x86-64 CPU. Choose it when the
  285. CPU or VM doesn't expose x86-64-v3, or when you're unsure.
  286. Homebrew and WinGet install the `amd64` builds. For the exact feature list,
  287. see
  288. [CPU requirements](https://github.com/ptweezy/cronstable/wiki/Installation#amd64v3-cpu-requirements).
  289. ## Web dashboard
  290. The daemon serves the built-in web dashboard at `/` on each `http://` and
  291. `https://` listener. It's one self-contained page, with no build step and no
  292. external requests, served under a strict Content Security Policy. To turn it
  293. on, add a `web` listener, as in the [quick start](#quick-start):
  294. ```yaml
  295. web:
  296. listen:
  297. - http://127.0.0.1:8080
  298. ```
  299. [![cronstable web dashboard: a live overview of every job, showing status, live resource usage, owner node, schedule, last run, next-run countdown, and a run-trend sparkline](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-overview.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-overview.png)
  300. The overview shows each job's status, upcoming runs, recent outcomes, and,
  301. when monitoring is on, resource usage. Open a job to follow its logs, review
  302. its run history, or inspect its schedule. You can also:
  303. * Trigger workflows, follow their task graphs, and approve or reject approval
  304. gates.
  305. * Inspect cluster health and compare each job's runs across nodes.
  306. * Investigate failures with an incident timeline and merged live logs.
  307. * Use the wallboard, the activity heatmap, and the durable state inspector.
  308. | Live logs | Workflow task graph | Fleet view |
  309. | :---: | :---: | :---: |
  310. | [![Live log tailing with ANSI color, timestamps, and in-log search](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-logs.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-logs.png) | [![The workflow drawer's graph tab: a diamond of tasks, every node green](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-dag-graph.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-dag-graph.png) | [![The fleet view: a jobs-by-nodes matrix with each node's last outcome and age per job](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-fleet.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-fleet.png) |
  311. Press `Ctrl-K` or `⌘K` for the command palette, `?` for shortcuts, or `Enter`
  312. to open the selected job. The dashboard has ten themes, adjustable fonts and UI
  313. scale, color-vision-safe palettes, and reduced-motion support. It shows status
  314. with text and symbols as well as color.
  315. Run history and captured output stay in memory unless you enable the
  316. [durable state store](https://github.com/ptweezy/cronstable/wiki/Durable-State),
  317. which keeps run history across restarts. To also keep each run's captured
  318. output, set `archiveOutput: true` on the job or under `defaults:`. For every
  319. panel, shortcut, and setting, see the
  320. [web dashboard guide](https://github.com/ptweezy/cronstable/wiki/Web-Dashboard).
  321. To try the dashboard without installing anything, open the
  322. [live demo](https://demo.cronstable.com). It's a public board that all
  323. visitors share, and it needs no account or token. You can start, cancel,
  324. pause, and resume its sample jobs, trigger its workflows, and approve or
  325. reject their gates.
  326. For a demo board on your own machine with a varied set of jobs, run this
  327. command from a clone of this repository, and then open
  328. <http://localhost:8080/>:
  329. ```shell
  330. docker compose up
  331. ```
  332. The [example gallery](#example-gallery) has larger setups, including a
  333. three-node cluster and the nine-node grand tour.
  334. ## Terminal dashboard
  335. The `cronstable tui` command brings the dashboard to your terminal, including
  336. over SSH and in tmux. It's a client of the same HTTP API, uses the web
  337. dashboard's keyboard shortcuts, and has job logs, history, workflows, cluster
  338. views, and incident tools.
  339. [![The cronstable TUI: a live 70-job board with status glyphs, next-fire countdowns, run sparklines, live CPU/memory chips, cluster owner column, and the fleet verdict bar](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/tui-overview.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/tui-overview.png)
  340. ```shell
  341. cronstable tui # local daemon on port 8080
  342. cronstable tui --url http://prod-node:8080 # remote daemon
  343. cronstable tui --tv # open the wallboard
  344. ```
  345. If the daemon requires a [token](#authentication), set the
  346. `CRONSTABLE_WEB_TOKEN` environment variable, or name another variable with
  347. `--token-env`. Use `--job` to open a job's details at startup, or `--ascii`
  348. when your terminal font lacks the status symbols. For all options, panels, and
  349. themes, see the
  350. [terminal dashboard guide](https://github.com/ptweezy/cronstable/wiki/Terminal-Dashboard).
  351. ## iOS app
  352. <p align="center">
  353. <a href="https://apps.apple.com/app/cronstable/id6801933039"><img src="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-icon.png" alt="The Cronstable app icon: the wordmark's double pendulum, balanced upright on its cart" width="112" height="112"></a>
  354. </p>
  355. <p align="center">
  356. <strong>Cronstable for iPhone and iPad</strong><br>
  357. The on-call companion and native dashboard for your cronstable servers.
  358. </p>
  359. <p align="center">
  360. <a href="https://apps.apple.com/app/cronstable/id6801933039"><img src="https://toolbox.marketingtools.apple.com/api/v2/badges/download-on-the-app-store/black/en-us" alt="Download on the App Store" height="48"></a>
  361. </p>
  362. The app connects directly to your servers over the LAN, Tailscale, or HTTPS,
  363. and receives [encrypted push alerts](#push-notifications). It needs no account
  364. or sign-up, has no analytics or ads, and keeps access tokens in the device
  365. Keychain.
  366. The app includes these features:
  367. * Alerts for failed runs, SLA breaches, workflow failures, and approval gates.
  368. Each alert is sealed to the device's key before it leaves your server, and
  369. you can approve or reject a gate from the lock screen.
  370. * The jobs board, run history, live log tails, workflow runs, run trends, CPU
  371. and memory charts, and node and cluster views.
  372. * Schedule tools: pressure heatmaps, duplicate detection, a cron expression
  373. sandbox, and an answer to "why did this run?"
  374. * Home Screen widgets for fleet health, and your job schedule as a calendar
  375. subscription.
  376. Push notifications are optional. Without the `push` reporter, the app polls
  377. your servers directly, every 1 to 300 seconds.
  378. <p align="center">
  379. <a href="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-jobs.png"><img src="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-jobs.png" alt="The app's jobs board in dark mode: a failing-jobs banner above each job's status, schedule, next-run countdown, and run sparkline" width="180"></a>
  380. <a href="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-approval.png"><img src="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-approval.png" alt="A workflow run in light mode, waiting at an approval gate with Approve and Reject buttons above its task list" width="180"></a>
  381. <a href="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-log.png"><img src="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-log.png" alt="A job's live log tail in dark mode, below its run stats and resource panel" width="180"></a>
  382. <a href="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-schedule.png"><img src="https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/ios-schedule.png" alt="The schedule view in light mode: scheduled runs for the next 24 hours, the busiest minute, and an hour-by-minute pressure heatmap" width="180"></a>
  383. </p>
  384. <p align="center"><sub>Jobs board · Approval gates · Live log tail · Schedule pressure</sub></p>
  385. To connect the app to a server, follow these steps:
  386. 1. Install [Cronstable](https://apps.apple.com/app/cronstable/id6801933039)
  387. from the App Store.
  388. 2. Enable the [HTTP API](#http-api) on an address that your phone can reach,
  389. such as a LAN, Tailscale, or HTTPS address, and
  390. [require a token](#authentication). A phone can't reach `127.0.0.1`.
  391. 3. Open the [web dashboard](#web-dashboard) at that address. On a page opened
  392. at a loopback address, such as `127.0.0.1`, the **Pair a device** panel
  393. shows no code.
  394. 4. In the command palette (`Ctrl-K` or `⌘K`) or in settings, select
  395. **Pair a device**.
  396. 5. Scan the QR code with the phone's camera, or tap **Scan QR code** in the
  397. app. The QR code contains the page's address and its access token, so pair
  398. over HTTPS or a trusted network, and give the phone a
  399. [scoped token](https://github.com/ptweezy/cronstable/wiki/HTTP-API#scoped-tokens-webauthtokens)
  400. instead of the all-scopes token.
  401. 6. To get lock-screen alerts, enable the [`push` reporter](#push-notifications).
  402. [![The dashboard's Pair a device panel: a QR code deep-linking the connection payload into the app being paired, the same payload as a copyable JSON string, and a warning that the embedded token holds every scope](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-pair.png)](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/dashboard-pair.png)
  403. The QR code is a deep link. If the app isn't installed, scanning it opens a
  404. page that explains how to get the app.
  405. To let the app find the daemon without a typed address, install the
  406. `discovery` extra and set `web.bonjour: true`. The daemon then advertises the
  407. API as a `_cronstable._tcp` mDNS service on the local network, and the app
  408. lists it under **Find nearby servers** (see
  409. [LAN discovery](https://github.com/ptweezy/cronstable/wiki/LAN-Discovery)). To
  410. explore the app before you set up a server, tap **Try the demo** on the welcome
  411. screen to connect to a live sample fleet.
  412. The app is optional. The web and terminal dashboards, the API, and every other
  413. reporter work without it.
  414. ### Pair from the terminal
  415. To pair on a server that runs the API without the dashboard page
  416. (`web.ui: false`), or from a shell with no browser, run `cronstable pair`. It
  417. prints the same QR code in the terminal:
  418. ```shell
  419. export CRONSTABLE_WEB_TOKEN=phone-token-value # the token the phone gets
  420. cronstable pair # local daemon on port 8080
  421. cronstable pair --public-url https://cron.example.net # the address the phone uses
  422. ```
  423. The code contains the token that `cronstable pair` uses, so pass a
  424. [scoped token](https://github.com/ptweezy/cronstable/wiki/HTTP-API#scoped-tokens-webauthtokens)
  425. for the phone.
  426. When `--url` is a loopback address, the command puts the host's LAN address in
  427. the code if the daemon answers there. Pass `--public-url` when the phone uses
  428. another address, such as a reverse proxy's. In the
  429. [terminal dashboard](#terminal-dashboard), **Pair a device (QR)** in the
  430. command palette shows the same code. For the options and the terminal size the
  431. code needs, see
  432. [pairing from the terminal](https://github.com/ptweezy/cronstable/wiki/Terminal-Pairing).
  433. ## Tutorials
  434. These four short walkthroughs build on the [quick start](#quick-start)
  435. configuration. Each example passes `cronstable --validate-config`: add it to
  436. your quick start file and replace the example commands with your own. Each
  437. tutorial links to the wiki page that covers its topic in full.
  438. ### Tutorial 1: Retry failed jobs and alert when retries fail
  439. This example retries a failed job with exponential backoff, and it posts to a
  440. Slack channel only if the job still fails after its last retry:
  441. ```yaml
  442. jobs:
  443. - name: nightly-backup
  444. command: /usr/local/bin/backup --incremental
  445. schedule: "0 3 * * *"
  446. captureStderr: true # include stderr in the report
  447. onFailure:
  448. retry:
  449. maximumRetries: 5
  450. initialDelay: 5 # waits 5s, 10s, 20s, 40s, then 80s
  451. maximumDelay: 300 # no single wait exceeds 300s
  452. backoffMultiplier: 2
  453. onPermanentFailure: # fires once, after the last retry fails
  454. report:
  455. webhook:
  456. url:
  457. fromEnvVar: SLACK_WEBHOOK_URL
  458. ```
  459. By default, a job fails when it exits with a nonzero status or writes to a
  460. captured stderr. To change that for a job, use
  461. [`failsWhen`](#failure-detection-and-retries). The webhook's default body is
  462. Slack-compatible, and Mattermost and Teams accept it as is. To report by email,
  463. Sentry, or a shell command, add the corresponding block under `report:`. Email
  464. and Sentry reports render Jinja2 templates with the run's name, output, and
  465. exit code, and shell command reports receive the same details as `CRONSTABLE_*`
  466. environment variables. For details, see
  467. [failure detection and retries](https://github.com/ptweezy/cronstable/wiki/Failure-Detection-and-Retries)
  468. and [reporting](https://github.com/ptweezy/cronstable/wiki/Reporting) in the
  469. wiki.
  470. ### Tutorial 2: Survive restarts, catch up what was missed
  471. By default, cronstable keeps no state across restarts. To handle a deploy or a
  472. reboot in the middle of a schedule, add a `state:` block:
  473. ```yaml
  474. state:
  475. path: ./cronstable-state # a local directory, or a shared mount for a fleet
  476. jobs:
  477. - name: hourly-invoice-emit
  478. command: python -m billing.emit_hourly
  479. schedule: "0 * * * *"
  480. onMissed: run-all # replay each hour missed while the daemon was down
  481. startingDeadlineSeconds: 21600 # skip missed runs older than 6 hours
  482. onFailure:
  483. retry:
  484. maximumRetries: 10
  485. initialDelay: 30
  486. maximumDelay: 600
  487. backoffMultiplier: 2
  488. ```
  489. Setting `state.path` alone has these effects:
  490. * Run history survives restarts, and the dashboard reloads it.
  491. * Pending retries resume at their original deadlines.
  492. * `@reboot` runs once per boot instead of once per daemon start.
  493. * Prometheus counters keep their values across restarts.
  494. The `onMissed` setting adds catch-up. `run-once` combines any number of missed
  495. runs into one launch, and `run-all` replays each missed run.
  496. `startingDeadlineSeconds` limits how old a missed run can be. Catch-up applies
  497. after a restart, and also when the daemon resumes after system sleep or a long
  498. stall.
  499. The same store gives job commands persistent storage and coordination tools
  500. through a loopback endpoint: key-value storage, cursors, fleet-wide locks,
  501. idempotency keys, artifacts, and run-scoped secrets. Commands use them through
  502. the `cronstable state`, `cursor`, `lock`, `idempotent`, `artifact`, and
  503. `secret` subcommands. For details, see
  504. [durable state](https://github.com/ptweezy/cronstable/wiki/Durable-State).
  505. ### Tutorial 3: Your first DAG, a durable pipeline
  506. A `dags:` block defines a durable workflow as a directed acyclic graph (DAG) of
  507. tasks. This example runs a build, waits for a person to approve it, and then
  508. publishes:
  509. ```yaml
  510. state:
  511. path: ./cronstable-state # DAGs live on the state store
  512. dags:
  513. - name: release-train # no schedule: manual-only
  514. tasks:
  515. - id: build
  516. command: make dist
  517. - id: approve
  518. type: approval # waits for approval
  519. dependsOn:
  520. - build
  521. - id: publish
  522. dependsOn:
  523. - approve
  524. command: make publish
  525. retries: 2 # task-level retries, DAG-owned
  526. retryDelaySeconds: 60
  527. ```
  528. Trigger the DAG and approve the gate, or click **Approve** in the dashboard's
  529. DAG drawer instead:
  530. ```shell
  531. curl -X POST http://127.0.0.1:8080/dags/release-train/trigger
  532. # -> {"dag": "release-train", "runKey": "manual-..."}
  533. curl -X POST http://127.0.0.1:8080/dags/release-train/runs/<runKey>/tasks/approve/decision \
  534. -H 'Content-Type: application/json' -d '{"decision": "approve", "by": "alice"}'
  535. ```
  536. The state store records workflow progress, so the daemon can resume a run after
  537. a restart. Across a fleet, a lease coordinates which node advances each run.
  538. Recovery can retry an interrupted task even if its earlier process is still
  539. running, so make task side effects safe to repeat, for example with an
  540. [idempotency key](https://github.com/ptweezy/cronstable/wiki/Durable-State#idempotency-keys).
  541. Scheduled DAGs also support catch-up and `backfill` over a date range. Tasks
  542. can pass data with `cronstable xcom push` and `cronstable xcom pull`, fan out
  543. over a list that an upstream task produced, and poll for conditions with
  544. `type: sensor`. A task can skip itself with an exit code listed in
  545. `skipExitCodes`, and a `triggerRule` such as `none_failed_min_one_success`
  546. joins the branches. A workflow can declare run parameters under `params:`.
  547. A manual or API trigger supplies the values, cronstable checks them, and
  548. each task reads them as `CRONSTABLE_PARAM_<NAME>` variables. A task with
  549. `when:` runs only when a parameter, or a value that an upstream task
  550. published, meets its comparisons. Otherwise the task is skipped and its
  551. command never starts. A plain job can declare `params:` too, and a manual
  552. start supplies its values. For details, see
  553. [orchestration and DAGs](https://github.com/ptweezy/cronstable/wiki/Orchestration-and-DAGs).
  554. ### Tutorial 4: Coordinate two replicas
  555. Run the same configuration on two or more hosts that share a POSIX mount. The
  556. hosts elect a leader through a fenced lease file, without certificates or a
  557. coordination service. The mount must support locks across hosts, and every host
  558. must keep its clock synchronized with NTP:
  559. ```yaml
  560. state:
  561. path: /mnt/shared/cronstable/state # optional: durable state shared by the fleet
  562. cluster:
  563. backend: filesystem
  564. filesystem:
  565. path: /mnt/shared/cronstable # the mount is the election store
  566. electLeader: true # each node is named by its hostname
  567. jobs:
  568. - name: charge-subscriptions
  569. command: python -m billing.charge
  570. schedule: "0 6 * * *"
  571. clusterPolicy: Leader # the default: only the leader runs it
  572. ```
  573. Only the elected leader starts scheduled `Leader` jobs. If the leader stops, a
  574. follower can take over after the lease is released or expires, provided it can
  575. reach the shared mount. The lease coordinates which node can start jobs; it
  576. doesn't make job side effects exactly-once. Each job's `clusterPolicy` sets its
  577. behavior when leadership can't be confirmed:
  578. * `Leader`: skips scheduled runs.
  579. * `PreferLeader`: allows runs when the coordination store is unreachable, so
  580. multiple replicas can run the same job.
  581. * `EveryNode`: runs the job on every node, for work that belongs on each node.
  582. Without a shared mount, use another backend: `gossip` elects a leader over
  583. mutual TLS with no shared store, `kubernetes` uses a `coordination.k8s.io`
  584. Lease, and `etcd` uses a lease-bound key. To spread job ownership across the
  585. fleet, use the `gossip` backend with `distribution: spread`. For details, see
  586. [clustering and leader election](#clustering-and-leader-election).
  587. ## Example gallery
  588. Every example in
  589. [`example/`](https://github.com/ptweezy/cronstable/tree/main/example) is a
  590. self-contained, annotated project that you can run from a clone of this
  591. repository. Each Compose file is in its example's folder, except for `demo`,
  592. which uses the root `docker-compose.yml`. The following table lists the main
  593. examples:
  594. | Example | One command | What it shows |
  595. | --- | --- | --- |
  596. | [`demo`](https://github.com/ptweezy/cronstable/tree/main/example/demo) | `docker compose up` | The dashboard playground: varied jobs, live logs, retries, a long-running job, and an on-demand job. |
  597. | [`grand-tour`](https://github.com/ptweezy/cronstable/tree/main/example/grand-tour) | `docker compose -f example/grand-tour/docker-compose.yml up --build` | Everything at once: a 9-node mTLS cluster, shared durable state, five DAG patterns, second-level probes, and all five cross-platform reporters connected to live sinks. |
  598. | [`cluster`](https://github.com/ptweezy/cronstable/tree/main/example/cluster) | `docker compose -f example/cluster/docker-compose.yml up` | A 3-node gossip cluster: peer attestation, quorum, leader election, and live failover. |
  599. | [`cluster-large`](https://github.com/ptweezy/cronstable/tree/main/example/cluster-large) | `docker compose -f example/cluster-large/docker-compose.yml up` | A 10-node, CPU-heavy fleet for watching `distribution: spread` and the load meters. |
  600. | [`dag`](https://github.com/ptweezy/cronstable/tree/main/example/dag) | `cronstable -c example/dag` | Orchestration on a single node: dependencies, XCom, fan-out, a sensor, and an approval gate. |
  601. | [`dag-cluster`](https://github.com/ptweezy/cronstable/tree/main/example/dag-cluster) | `docker compose -f example/dag-cluster/docker-compose.yml up` | DAGs coordinating across three nodes on one shared store, with leases and crash recovery. |
  602. | [`job-state`](https://github.com/ptweezy/cronstable/tree/main/example/job-state) | `cronstable -c example/job-state` | The state primitives for jobs: key-value storage, cursors, locks, idempotency keys, artifacts, and secrets. |
  603. | [`mcp`](https://github.com/ptweezy/cronstable/tree/main/example/mcp) | `docker compose -f example/mcp/docker-compose.yml up --build` | The MCP server: an AI agent (Claude, Cursor, Copilot) observing and driving the scheduler over `POST /mcp`, or the `cronstable mcp` stdio bridge. |
  604. | [`pulse-monitor`](https://github.com/ptweezy/cronstable/tree/main/example/pulse-monitor) | `docker compose -f example/pulse-monitor/docker-compose.yml up` | Second-level scheduling as a real-time uptime and SLA monitor. |
  605. | [`pulse-cluster`](https://github.com/ptweezy/cronstable/tree/main/example/pulse-cluster) | `docker compose -f example/pulse-cluster/docker-compose.yml up` | The same probes spread across a 3-node cluster with leader election. |
  606. | [`zen-demo`](https://github.com/ptweezy/cronstable/tree/main/example/zen-demo) | `docker compose -f example/zen-demo/docker-compose.yml up` | A deliberately calm board, for the wallboard's zen screensaver. |
  607. | [`crontab`](https://github.com/ptweezy/cronstable/tree/main/example/crontab) | `cronstable -c example/crontab` | Five-field user crontabs alongside YAML jobs. |
  608. | [`kubernetes`](https://github.com/ptweezy/cronstable/tree/main/example/kubernetes) | `kubectl apply -f example/kubernetes/deployment.yaml` | Leader election through a `coordination.k8s.io/v1` Lease. |
  609. | [`etcd`](https://github.com/ptweezy/cronstable/tree/main/example/etcd) | `docker compose -f example/etcd/docker-compose.yml up` | Leader election through an etcd lease, over plain HTTP. |
  610. | [`docker`](https://github.com/ptweezy/cronstable/tree/main/example/docker) | `docker build -t cronstable-example example/docker` | The minimal "add cronstable to your own image" recipe. |
  611. ## Configuration
  612. ### Configuration basics
  613. cronstable reads its configuration from YAML files. Pass a file or a directory
  614. with `-c`:
  615. ```shell
  616. cronstable -c /etc/cronstable.d
  617. ```
  618. From a directory, cronstable reads every `*.yaml` and `*.yml` file and every
  619. classic crontab (`*.crontab`, `*.cron`, or a file named `crontab`), and skips
  620. names that start with `_` or `.`. Without `-c`, cronstable reads
  621. `/etc/cronstable.d` on POSIX systems (for Windows, see [Windows](#windows)).
  622. `cronstable init` writes a commented starter configuration to that default
  623. location, which needs root; `cronstable init DIRECTORY` writes it elsewhere.
  624. cronstable runs in the foreground and logs to stdout and stderr, so run it
  625. under a supervisor such as systemd or a container runtime. About once a minute,
  626. it checks the configuration for changes and applies them without a restart. To
  627. reload immediately, send it `SIGHUP`. If a changed configuration is invalid,
  628. cronstable logs the error and keeps running the previous jobs. To check a
  629. configuration without starting the scheduler, run
  630. `cronstable --validate-config -c <path>`.
  631. Each job needs a `name`, a `command`, and a `schedule`. This job runs every 5
  632. minutes:
  633. ```yaml
  634. jobs:
  635. - name: test-01
  636. command: echo "foobar"
  637. shell: /bin/bash
  638. schedule: "*/5 * * * *"
  639. ```
  640. A string `command` runs through a shell: `/bin/sh` by default, or the job's
  641. `shell`, which is `/bin/bash` in the preceding example. A list `command` runs
  642. directly, without a shell, and each item becomes one argument:
  643. ```yaml
  644. jobs:
  645. - name: test-01
  646. command:
  647. - echo
  648. - foobar
  649. schedule: "*/5 * * * *"
  650. ```
  651. For every option, see the
  652. [configuration reference](https://github.com/ptweezy/cronstable/wiki/Configuration-Reference).
  653. ### Schedules
  654. A string `schedule` uses crontab syntax, which cronstable's built-in cron
  655. engine parses. It accepts five, six, or seven fields:
  656. * Five fields: `minute hour day-of-month month day-of-week`, as in classic
  657. cron.
  658. * Six fields: the classic five, plus a trailing `year`.
  659. * Seven fields: a leading `second`, the classic five, and a trailing `year`
  660. (see [second-level schedules](#second-level-schedules)).
  661. Fields accept ranges, steps, lists, names such as `jan` and `mon`, and
  662. Quartz's `?` on its own in a day field. cronstable also supports these forms:
  663. * `L` alone in the day-of-month field for the month's last day, and `L5` in
  664. the day-of-week field for the month's last Friday.
  665. * Business-day forms: `LW` for the month's last weekday, `L-3` for three days
  666. before the month's last day, `15W` for the weekday nearest the 15th, and
  667. `5#3` for the third Friday (see
  668. [business-day schedules](https://github.com/ptweezy/cronstable/wiki/Business-Day-Schedules)).
  669. * `H`, which picks a stable value from a hash of the job's name, so a fleet of
  670. hourly jobs spreads across the hour instead of all starting at `:00` (see
  671. [hashed schedules](https://github.com/ptweezy/cronstable/wiki/Hashed-Schedules)).
  672. * Nicknames such as `@hourly` and `@daily`, and `@reboot`, which runs the job
  673. once when cronstable starts.
  674. A six-field expression reads its sixth field as a year. If that field can't be
  675. a year, as in a Quartz expression that ends in `?`, cronstable reports an error
  676. that explains how to convert it. A Quartz expression that ends in `*`, such as
  677. `0 15 10 * * *`, is valid but means something else here, so check converted
  678. expressions with `GET /schedule/preview`. For the full syntax, see
  679. [schedules and time zones](https://github.com/ptweezy/cronstable/wiki/Schedules-and-Timezones).
  680. The `schedule` option can also be an object. This job runs every 5 minutes on
  681. July 19 each year:
  682. ```yaml
  683. jobs:
  684. - name: test-01
  685. command: echo "foobar"
  686. schedule:
  687. minute: "*/5"
  688. dayOfMonth: 19
  689. month: 7
  690. dayOfWeek: "*"
  691. ```
  692. ### Second-level schedules
  693. Schedules have one-minute granularity by default. To run a job at one-second
  694. granularity, write a seven-field crontab string whose first field is the
  695. second, or use the object form with a `second:` property. Both of these jobs
  696. run every 15 seconds, at seconds 0, 15, 30, and 45 of every minute:
  697. ```yaml
  698. jobs:
  699. - name: every-15s-string
  700. command: echo "tick"
  701. schedule: "*/15 * * * * * *" # 7 fields: the leading field is seconds
  702. - name: every-15s-object
  703. command: echo "tick"
  704. schedule:
  705. second: "*/15"
  706. ```
  707. The seconds field accepts the same syntax as the other fields, so
  708. `second: "*"` runs a job every second. While any enabled job uses seconds, the
  709. scheduler wakes once per second instead of once per minute, and minute-level
  710. jobs still run once in their scheduled minute. Second-level schedules are
  711. available only in YAML; [classic crontab files](#classic-crontab-files) keep
  712. cron's five fields.
  713. For a runnable example, see
  714. [`example/pulse-monitor`](https://github.com/ptweezy/cronstable/tree/main/example/pulse-monitor),
  715. a small uptime and SLA monitor that probes a service every few seconds, and its
  716. three-node version,
  717. [`example/pulse-cluster`](https://github.com/ptweezy/cronstable/tree/main/example/pulse-cluster).
  718. ### Time zones
  719. cronstable interprets schedules in UTC by default. To interpret a job's
  720. schedule in a specific time zone, set `timezone`. The following job runs every
  721. day at 19:27 in Los Angeles:
  722. ```yaml
  723. jobs:
  724. - name: test-01
  725. command: echo "hello"
  726. schedule: "27 19 * * *"
  727. timezone: America/Los_Angeles
  728. captureStdout: true
  729. ```
  730. To use the machine's local time instead, set `utc: false`.
  731. ### Job environment
  732. To set environment variables for the command, use the `environment` option. To
  733. load them from a file, use `env_file`:
  734. ```yaml
  735. jobs:
  736. - name: test-01
  737. command: echo "foobar"
  738. shell: /bin/bash
  739. schedule: "*/5 * * * *"
  740. env_file: .env
  741. environment:
  742. - key: PATH
  743. value: /bin:/usr/bin
  744. ```
  745. The file contains one `KEY=VALUE` pair per line. cronstable ignores empty lines
  746. and lines that start with `#`. Variables in the `environment` option override
  747. variables from `env_file`.
  748. ### Classic crontab files
  749. cronstable reads five-field user crontabs in the classic Vixie format. Export
  750. your crontab and pass the file to `-c`:
  751. ```shell
  752. crontab -l > my.crontab
  753. cronstable -c my.crontab
  754. ```
  755. System crontabs such as `/etc/crontab` and files in `/etc/cron.d` contain an
  756. extra user column that cronstable doesn't parse. To preserve per-job users,
  757. convert these entries to YAML and set each job's
  758. [`user` field](#run-as-another-user-or-group). If all jobs should run as the
  759. daemon's user, remove the user column from a copy of the file instead.
  760. You can also put files named `*.crontab`, `*.cron`, or `crontab` in a
  761. configuration directory next to YAML files, or load them with
  762. [`include`](#includes). For example, a user crontab can contain:
  763. ```crontab
  764. SHELL=/bin/bash
  765. PATH=/usr/local/bin:/usr/bin:/bin
  766. # m h dom mon dow command
  767. */15 * * * * /usr/local/bin/backup --incremental
  768. 30 4 * * mon-fri /usr/local/bin/report --daily
  769. @daily /usr/local/bin/rotate-logs
  770. 0 0 * * * pg_dump mydb > /backup/mydb-$(date +\%F).sql
  771. ```
  772. Comments, `NAME=value` environment lines, nicknames such as `@reboot` and
  773. `@daily`, and `\%` escapes all work as described in `man 5 crontab`. An
  774. environment line applies to the entries after it, and cronstable honors `SHELL`
  775. and `CRON_TZ`. Each entry becomes an ordinary cronstable job named
  776. `<file>:<line>`, with cronstable's standard defaults rather than an emulation
  777. of cron's environment:
  778. * Schedules run in UTC unless the crontab sets `CRON_TZ`.
  779. * A run fails when it exits with a nonzero status or writes to stderr.
  780. cronstable doesn't send `MAILTO` mail.
  781. * An unescaped `%`, which cron passes to the command as standard input, causes
  782. an error when the file loads. `\%` still produces a literal `%`.
  783. To give an entry retries, reporting, timeouts, or any other per-job option,
  784. move it to YAML. For the full mapping and every difference from cron, see
  785. [classic crontabs](https://github.com/ptweezy/cronstable/wiki/Classic-Crontabs)
  786. in the wiki. For a runnable example, see
  787. [`example/crontab`](https://github.com/ptweezy/cronstable/tree/main/example/crontab),
  788. a configuration directory that combines a crontab with YAML jobs and the
  789. dashboard.
  790. ### Defaults
  791. A `defaults` section sets default values for the jobs in the same file, and
  792. each job can override them:
  793. ```yaml
  794. defaults:
  795. environment:
  796. - key: PATH
  797. value: /bin:/usr/bin
  798. shell: /bin/bash
  799. utc: false
  800. jobs:
  801. - name: test-01
  802. command: echo "foobar" # runs with /bin/bash
  803. schedule: "*/5 * * * *"
  804. - name: test-02
  805. command: echo "zbr"
  806. shell: /bin/sh # overrides the default shell
  807. schedule: "*/5 * * * *"
  808. ```
  809. In a configuration directory, each file's `defaults` section applies only to the
  810. jobs in that file. To share defaults across files, use [includes](#includes).
  811. ### Includes
  812. The `include` option merges a list of files into the current configuration so
  813. that multiple files can share defaults and other settings. For example, this is
  814. the main configuration:
  815. ```yaml
  816. include:
  817. - _inc.yaml
  818. jobs:
  819. - name: my-job
  820. ...
  821. ```
  822. The shared defaults live in `_inc.yaml`:
  823. ```yaml
  824. defaults:
  825. shell: /bin/bash
  826. onPermanentFailure:
  827. report:
  828. sentry:
  829. ...
  830. ```
  831. A directory load skips files whose names start with `_`, so `_inc.yaml` applies
  832. only where a file includes it. For the merge rules, see
  833. [includes, defaults, and multi-file config](https://github.com/ptweezy/cronstable/wiki/Includes-and-Defaults).
  834. ### Environment variable interpolation
  835. Any string value in the configuration can read cronstable's environment
  836. variables with `${VAR}`, or with `${VAR:-default}` to set a fallback. One
  837. configuration file can then serve many environments without a wrapper script
  838. that templates it. To write a literal `$`, use `$$`.
  839. Interpolation runs after the file is validated, so it works in any string
  840. field, such as a listen address, a state path, a time zone, or a webhook URL.
  841. If a `${VAR}` is unset and has no default, cronstable reports a configuration
  842. error that names the variable, and `cronstable --validate-config` catches it.
  843. ```yaml
  844. web:
  845. listen:
  846. - "http://0.0.0.0:${WEB_PORT:-8080}" # port from the environment, default 8080
  847. state:
  848. path: ${STATE_DIR} # required: unset fails --validate-config
  849. jobs:
  850. - name: rollup-${REGION} # required, like STATE_DIR
  851. command: run-rollup # ${VAR} in a command is left for the shell
  852. schedule:
  853. minute: "0"
  854. timezone: ${TZ:-UTC}
  855. ```
  856. cronstable doesn't interpolate the `command` and `shell` of jobs and reporters,
  857. so the shell expands their `${VAR}` references at run time against the job's
  858. own environment, not the daemon's. It also leaves the `logging` section for
  859. Python's `logging.config`. For the full rules, including how interpolation
  860. affects the [job-set ID](#job-set-id), see
  861. [environment variable interpolation](https://github.com/ptweezy/cronstable/wiki/Environment-Variable-Interpolation).
  862. ### Disable a job
  863. Jobs are enabled by default. To disable a job, add `enabled: false`. cronstable
  864. validates disabled jobs but doesn't run them.
  865. ```yaml
  866. jobs:
  867. - name: test-01
  868. enabled: false # skipped until you set this to true
  869. command: echo "foobar"
  870. shell: /bin/bash
  871. schedule: "* * * * *"
  872. ```
  873. ### Custom logging
  874. To customize cronstable's own logs, add a `logging` section in the format of
  875. Python's
  876. [`logging.config` dictionary schema](https://docs.python.org/3/library/logging.config.html#dictionary-schema-details).
  877. For example, the following configuration adds a timestamp to each log line:
  878. ```yaml
  879. logging:
  880. version: 1
  881. disable_existing_loggers: false
  882. formatters:
  883. simple:
  884. format: '%(asctime)s [%(processName)s/%(threadName)s] %(levelname)s (%(name)s): %(message)s'
  885. datefmt: '%Y-%m-%d %H:%M:%S'
  886. handlers:
  887. console:
  888. class: logging.StreamHandler
  889. level: DEBUG
  890. formatter: simple
  891. stream: ext://sys.stdout
  892. root:
  893. level: INFO
  894. handlers:
  895. - console
  896. ```
  897. For more, see
  898. [logging configuration](https://github.com/ptweezy/cronstable/wiki/Logging-Configuration).
  899. ## Schedule introspection
  900. cronstable answers questions about its own schedule. Each of these features has
  901. its own wiki page:
  902. * Why didn't it run: `GET /schedule/why?job=<name>&at=<timestamp>` shows, field
  903. by field, how the scheduler's match test evaluates one job at one moment. For
  904. a job scheduled `0 9 * * mon,fri`, asking about a Tuesday at 09:00 returns
  905. `"matches": false` with `day-of-week` as the failed field, plus the job's
  906. nearest runs before and after that moment
  907. ([Why Didn't It Run?](https://github.com/ptweezy/cronstable/wiki/Why-No-Run)).
  908. * Schedule linting: when cronstable loads the configuration, it flags valid
  909. expressions that probably don't mean what they say. Examples include an
  910. expression with no future occurrence, a schedule that sets both day of month
  911. and day of week, `*/n` steps that don't divide evenly, and wall-clock times
  912. that daylight saving time skips or repeats. Findings appear on `/jobs` and
  913. `/status`, and `GET /schedule/preview` checks any expression before it
  914. becomes a job
  915. ([Schedule Linting](https://github.com/ptweezy/cronstable/wiki/Schedule-Linting)).
  916. * Schedule pressure: `GET /schedule/pressure` groups the next 24 hours of
  917. scheduled runs into a collision heatmap, which both dashboards display
  918. ([Schedule Pressure](https://github.com/ptweezy/cronstable/wiki/Schedule-Pressure)).
  919. * Duplicate detection: `GET /schedule/duplicates` groups jobs whose schedules
  920. run at exactly the same times, even when the expressions are written
  921. differently
  922. ([Duplicate Schedule Detection](https://github.com/ptweezy/cronstable/wiki/Duplicate-Schedule-Detection)).
  923. * Suggest a slot: `GET /schedule/suggest` recommends the least busy time for a
  924. new job, based on the fleet's actual runs
  925. ([Suggest a Slot](https://github.com/ptweezy/cronstable/wiki/Suggest-a-Slot)).
  926. ## Job behavior
  927. ### Failure detection and retries
  928. By default, a run fails when the process exits with a nonzero status, or when it
  929. writes to stderr, which cronstable captures unless the job sets
  930. `captureStderr: false`. To change what counts as a failure, set the Boolean
  931. fields of the job's `failsWhen` option:
  932. | Field | Default | When `true` |
  933. | --- | --- | --- |
  934. | `nonzeroReturn` | `true` | A nonzero exit status fails the run. |
  935. | `producesStderr` | `true` | Output on a captured stderr fails the run. |
  936. | `producesStdout` | `false` | Output on a captured stdout fails the run. |
  937. | `always` | `false` | Every run fails, whatever its exit status or output. |
  938. A `retry` block inside `onFailure` retries a failed run with exponential
  939. backoff. The `onPermanentFailure` hook runs only after the last retry fails:
  940. ```yaml
  941. jobs:
  942. - name: test-01
  943. command: |
  944. echo "hello" 1>&2
  945. exit 10
  946. schedule:
  947. minute: "*/10"
  948. captureStderr: true
  949. onFailure:
  950. retry:
  951. maximumRetries: 10
  952. initialDelay: 1
  953. maximumDelay: 30
  954. backoffMultiplier: 2
  955. onPermanentFailure:
  956. report:
  957. mail:
  958. from: cron@example.com
  959. to: ops@example.com
  960. smtpHost: 127.0.0.1
  961. ```
  962. The first retry waits `initialDelay` seconds, and each later wait is multiplied
  963. by `backoffMultiplier`, up to `maximumDelay`. To retry forever, set
  964. `maximumRetries: -1`, for example to restart a long-running `@reboot` process
  965. whenever it fails. Pending retries stay in memory unless you configure a
  966. `state:` section, which lets them resume after a restart. To check a job's
  967. output before recording success, see
  968. [result verification](https://github.com/ptweezy/cronstable/wiki/Result-Verification).
  969. For details, see
  970. [failure detection and retries](https://github.com/ptweezy/cronstable/wiki/Failure-Detection-and-Retries)
  971. in the wiki.
  972. ### Late-run detection (SLA monitoring)
  973. Failure hooks only see runs that happened. To detect runs that are late,
  974. missing, or taking too long, add an `sla:` block. Each job can set up to three
  975. independent thresholds, and an in-process monitor checks them once per minute.
  976. When a threshold is breached, the `onLate` hook runs once. It takes the same
  977. `report` block as `onFailure`:
  978. ```yaml
  979. jobs:
  980. - name: nightly-etl
  981. command: python -m etl.run
  982. schedule: "0 4 * * *"
  983. sla:
  984. maxTimeSinceSuccessSeconds: 129600 # no success for 36 hours
  985. lateAfterSeconds: 900 # a due run hasn't started within 15 minutes
  986. maxRuntimeSeconds: 7200 # a run is still going after 2 hours
  987. onLate:
  988. report:
  989. webhook:
  990. url:
  991. fromEnvVar: SLACK_WEBHOOK_URL
  992. ```
  993. Each breach produces one report, not one per minute. When the check clears,
  994. cronstable logs a recovery line and sends no report. `maxRuntimeSeconds` only
  995. observes a run and never stops it; to enforce a limit, use
  996. [`executionTimeout`](#execution-timeout). The monitor skips paused and disabled
  997. jobs. Under leader election, only the node that owns the job checks it, so each
  998. breach sends a single alert.
  999. Breaches appear as an **OVERDUE** badge in both dashboards, as an `sla` object
  1000. on `GET /jobs`, and as the `cronstable_job_late{job_name, check}` and
  1001. `cronstable_job_sla_breaches_total{job_name, check}` metrics. The monitor runs
  1002. inside the daemon, so it can't report that the daemon itself has stopped; pair
  1003. it with an external Prometheus staleness alert. For details, see
  1004. [late-run detection](https://github.com/ptweezy/cronstable/wiki/Late-Run-Detection)
  1005. in the wiki.
  1006. ### Concurrency
  1007. If a job is still running when its next run is due, `concurrencyPolicy`
  1008. decides what happens:
  1009. * `Allow` (default): starts the new run alongside the running one.
  1010. * `Forbid`: skips the new run.
  1011. * `Replace`: cancels the running job and starts the new run in its place.
  1012. The policy applies on each node. On a cluster that shares a `state:` store, set
  1013. `concurrencyScope: cluster` to apply `Forbid` and `Replace` across nodes. To
  1014. limit how many runs of several jobs can happen at once, use a
  1015. [resource pool](https://github.com/ptweezy/cronstable/wiki/Resource-Pools). For
  1016. details, see
  1017. [concurrency and timeouts](https://github.com/ptweezy/cronstable/wiki/Concurrency-and-Timeouts).
  1018. ### Execution timeout
  1019. To stop a job after a set number of seconds, set `executionTimeout`. When
  1020. cronstable stops a job, it first asks the job to exit, waits up to
  1021. `killTimeout` seconds (30 by default), and then forces it to stop. On POSIX
  1022. systems, the request is `SIGTERM` to the job's process group, followed by
  1023. `SIGKILL`. On Windows, it's `CTRL_BREAK_EVENT`, followed by ending the job's
  1024. process tree. The same steps apply when `concurrencyPolicy: Replace` or a
  1025. cancel request stops a job.
  1026. The following job would take 10 seconds to finish. After one second,
  1027. cronstable sends `SIGTERM` to its process group. The shell and its `sleep`
  1028. child both ignore the signal, so cronstable sends `SIGKILL` half a second
  1029. later:
  1030. ```yaml
  1031. jobs:
  1032. - name: test-03
  1033. command: |
  1034. trap '' TERM
  1035. echo "starting..."
  1036. sleep 10
  1037. echo "all done."
  1038. schedule:
  1039. minute: "*"
  1040. captureStderr: true
  1041. executionTimeout: 1 # in seconds
  1042. killTimeout: 0.5
  1043. ```
  1044. ### Run as another user or group
  1045. The `user` field sets the user (UID or username) that a job's process runs as,
  1046. and the `group` field sets the group (GID or group name). If you set only
  1047. `user`, the group defaults to that user's primary group. For example:
  1048. ```yaml
  1049. jobs:
  1050. - name: test-03
  1051. command: id
  1052. schedule:
  1053. minute: "*"
  1054. captureStderr: true
  1055. user: www-data
  1056. ```
  1057. To switch users, cronstable must run as root. This feature relies on `setuid`
  1058. and `setgid`, so it's available only on POSIX systems. On Windows, cronstable
  1059. rejects a job that sets `user` or `group` with a configuration error.
  1060. ### Working directory
  1061. By default, a job starts in cronstable's own working directory. To start it in
  1062. a different directory, set `workingDirectory`. This matters most on Windows,
  1063. where an elevated console starts the daemon in the system directory, so
  1064. relative paths in a script resolve to the wrong place. It's the equivalent of
  1065. the **Start in** box on a Task Scheduler action.
  1066. ```yaml
  1067. jobs:
  1068. - name: nightly-import
  1069. command: import.bat
  1070. schedule:
  1071. minute: "0"
  1072. hour: "2"
  1073. workingDirectory: C:\jobs\importer
  1074. ```
  1075. cronstable expands `~` and `${VAR}` in the path and makes it absolute when it
  1076. loads the configuration. The operating system checks that the directory exists
  1077. when the job starts, so a missing directory fails only that run instead of
  1078. rejecting the whole configuration. You can also set `workingDirectory` in a
  1079. `defaults:` block and on a DAG task. For details, see
  1080. [commands and environment](https://github.com/ptweezy/cronstable/wiki/Commands-and-Environment#workingdirectory).
  1081. ### Process priority
  1082. The `priority` option sets a job's CPU scheduling priority relative to the
  1083. other processes on the machine: `idle`, `below-normal`, `normal` (the default),
  1084. `above-normal`, or `high`.
  1085. ```yaml
  1086. jobs:
  1087. - name: nightly-reindex
  1088. command: reindex.sh
  1089. schedule:
  1090. minute: "0"
  1091. hour: "3"
  1092. priority: idle
  1093. ```
  1094. On POSIX systems, cronstable renices the job's process group right after it
  1095. starts the job: `idle` is nice 19, and `high` is nice -10. Raising the priority
  1096. requires privileges; if the change is denied, the job runs at its inherited
  1097. priority. On Windows, the level becomes the process's priority class. Child
  1098. processes inherit a lowered priority on both platforms, but on Windows, the
  1099. children of an `above-normal` or `high` job start at normal priority. The
  1100. default, `normal`, leaves the inherited priority unchanged. For details, see
  1101. [commands and environment](https://github.com/ptweezy/cronstable/wiki/Commands-and-Environment#priority).
  1102. ### Resource monitoring
  1103. To find out which jobs use the most CPU and memory, turn on per-job resource
  1104. accounting. Set `monitorResources: true` on a job, as in the following example,
  1105. or under `defaults:` to cover every job:
  1106. ```yaml
  1107. jobs:
  1108. - name: nightly-model-refresh
  1109. command: python -m models.refresh
  1110. schedule: "0 4 * * *"
  1111. monitorResources: true
  1112. ```
  1113. While the job runs, cronstable uses [psutil](https://github.com/giampaolo/psutil)
  1114. to sample its whole process tree, including child processes. When the run ends,
  1115. cronstable records its total CPU time and peak resident memory. The dashboard
  1116. shows the numbers live on the job's row, per run in the **History** tab, and as
  1117. charts in the **Resources** tab. They also appear in `GET /jobs/{name}/runs`, in
  1118. Prometheus metrics such as `cronstable_job_cpu_seconds_total`, and in report
  1119. templates, so a failure alert can show how large the run was. With a
  1120. [state store](https://github.com/ptweezy/cronstable/wiki/Durable-State), they
  1121. survive restarts.
  1122. Resource monitoring only observes: it never changes whether a run succeeds or
  1123. fails. To cap a job's CPU, memory, or process count, see
  1124. [resource limits](#resource-limits). Monitoring is off by default and adds no
  1125. overhead when it's off. Because the numbers are sampled, figures for short runs
  1126. are approximate. To tune the sampling interval and chart history, or to monitor
  1127. DAG tasks and whole nodes, see
  1128. [resource monitoring](https://github.com/ptweezy/cronstable/wiki/Resource-Monitoring).
  1129. ### Resource limits
  1130. To bound what each run of a job can use, set `resourceLimits` on the job, as in
  1131. the following example, or under `defaults:` to cap every job:
  1132. ```yaml
  1133. jobs:
  1134. - name: nightly-model-refresh
  1135. command: python -m models.refresh
  1136. schedule: "0 4 * * *"
  1137. resourceLimits:
  1138. cpu: 1.5 # CPUs, like docker run --cpus
  1139. memory: 512M # powers of 1024
  1140. processes: 64
  1141. ```
  1142. The kernel enforces the caps across the run's whole process tree. A run at its
  1143. CPU cap runs more slowly, and a run at its process cap cannot start more
  1144. processes. A run that goes over its memory cap is killed with every process it
  1145. started and fails with `memory limit exceeded (512 MiB)`. The dashboards, the
  1146. run history, and Prometheus metrics show each job's caps and whether its runs
  1147. hit them.
  1148. On Linux, each capped run gets its own cgroup (cgroup v2), which needs a cgroup
  1149. delegated to cronstable. The packaged systemd unit sets `Delegate=memory pids`
  1150. and `OOMPolicy=continue`, so memory and process caps work with no setup, and
  1151. CPU caps need `Delegate=yes` in a drop-in. In a container, cronstable needs
  1152. root and a writable cgroupfs, in the container's own cgroup namespace or in a
  1153. container cgroup that the runtime delegated; the published images run as a
  1154. non-root user, so capped jobs run uncapped there. On Windows, each capped run
  1155. gets its own Job Object, with no setup. macOS, the BSDs, and illumos cannot
  1156. enforce caps. Where the host cannot enforce a cap, the run goes ahead without
  1157. it, the daemon logs a warning, and the run record says so. With
  1158. `required: true`, the run fails instead. For details, see
  1159. [resource limits](https://github.com/ptweezy/cronstable/wiki/Resource-Limits).
  1160. ## Reporting and metrics
  1161. ### Reporting
  1162. cronstable has six built-in reporters: `sentry`, `mail`, `shell`, `webhook`
  1163. (Slack-compatible with no extra configuration), `push` (see
  1164. [push notifications](#push-notifications)), and `eventlog` (see
  1165. [Windows Event Log](#windows-event-log)). Each reporter can run on the
  1166. `onFailure`, `onPermanentFailure`, `onSuccess`, and `onLate` hooks. The mail
  1167. `subject` and `body` and the Sentry `body` are Jinja2 templates that can use the
  1168. run's outcome and captured output. Secrets such as DSNs, passwords, and webhook
  1169. URLs can come from `value`, `fromFile`, or `fromEnvVar`:
  1170. ```yaml
  1171. jobs:
  1172. - name: test-01
  1173. command: |
  1174. echo "hello" 1>&2
  1175. exit 10
  1176. schedule:
  1177. minute: "*/2"
  1178. captureStderr: true
  1179. onFailure:
  1180. report:
  1181. sentry:
  1182. dsn:
  1183. fromEnvVar: SENTRY_DSN
  1184. mail:
  1185. from: cron@example.com
  1186. to: ops@example.com
  1187. smtpHost: 127.0.0.1
  1188. subject: Cron job '{{name}}' failed
  1189. body: |
  1190. {{stderr}}
  1191. (exit code: {{exit_code}})
  1192. shell:
  1193. shell: /bin/bash
  1194. command: echo "Error code $CRONSTABLE_RETCODE"
  1195. webhook:
  1196. url:
  1197. fromEnvVar: SLACK_WEBHOOK_URL
  1198. ```
  1199. A report includes the output streams that the job captures. `captureStderr` is
  1200. on by default, and `captureStdout` is off. For the capture options, including
  1201. the `streamPrefix` line prefix, see
  1202. [output capturing](https://github.com/ptweezy/cronstable/wiki/Output-Capturing).
  1203. For every reporter's options, including HTML mail, Sentry fingerprints, webhook
  1204. examples for other services, the template variables, and the shell reporter's
  1205. `CRONSTABLE_*` environment variables, see
  1206. [reporting](https://github.com/ptweezy/cronstable/wiki/Reporting) in the wiki.
  1207. ### Push notifications
  1208. The `push` reporter sends end-to-end encrypted alerts to devices paired with the
  1209. [iOS app](#ios-app). Before an alert leaves your server, the daemon seals it to
  1210. the device's public key. Where the platform supports it, the seal uses X-Wing,
  1211. a post-quantum hybrid of ML-KEM-768 and X25519; elsewhere it uses an X25519
  1212. sealed box. The hosted relay forwards each alert to the Apple Push Notification
  1213. service (APNs) and sees only ciphertext and routing metadata. It never sees job
  1214. names, hostnames, or log lines.
  1215. The reporter needs three things: the `push` extra
  1216. (`pip install "cronstable[push]"`), a daemon-wide `push:` section, and `push`
  1217. enabled on a reporting hook. If a configuration enables push without the extra
  1218. or the `push:` section, cronstable refuses to start instead of dropping alerts:
  1219. ```yaml
  1220. push:
  1221. relay:
  1222. url: https://relay.cronstable.com/
  1223. devicesFile: /var/lib/cronstable/devices.json
  1224. defaults:
  1225. onFailure:
  1226. report:
  1227. push:
  1228. enabled: true
  1229. ```
  1230. If you configure a `state:` section, you can omit `devicesFile`. The durable
  1231. store then keeps the pairings, and every node that shares it sees them. To pair
  1232. a device, follow the steps in [iOS app](#ios-app). For the report options,
  1233. pairing through the API, revocation, size limits, and the relay trust model,
  1234. see [push notifications](https://github.com/ptweezy/cronstable/wiki/Push-Notifications)
  1235. in the wiki.
  1236. ### Windows Event Log
  1237. On Windows, the `eventlog` reporter writes each outcome to the Application
  1238. event log, which Event Viewer, Windows Event Forwarding, SCOM, and SIEM
  1239. connectors read. It requires no optional dependencies. Each record has a stable
  1240. event ID and a fixed set of insertion strings for rules to match:
  1241. ```yaml
  1242. defaults:
  1243. onFailure:
  1244. report:
  1245. eventlog:
  1246. enabled: true
  1247. ```
  1248. ```powershell
  1249. Get-WinEvent -FilterHashtable @{ LogName = 'Application'; ProviderName = 'cronstable'; ID = 1001, 1002 }
  1250. ```
  1251. Jobs use event IDs 1000 (succeeded), 1001 (failed), 1002 (failed permanently),
  1252. and 1003 (overdue). Daemon and orchestration events use 1010 and 1011.
  1253. cronstable writes as an unregistered event source, so Event Viewer adds a
  1254. generic "description cannot be found" note to the rendered text. The XML view,
  1255. `Get-WinEvent`, forwarding, and SIEM connectors read every field normally. On
  1256. other platforms, the reporter does nothing, and cronstable says so once when it
  1257. loads the configuration. For the field tables and how to register the source,
  1258. see [Windows Event Log](https://github.com/ptweezy/cronstable/wiki/Windows-Event-Log)
  1259. in the wiki.
  1260. ### Metrics
  1261. When the [HTTP API](#http-api) is enabled, `GET /metrics` serves built-in
  1262. Prometheus metrics, so you don't need an exporter sidecar. They cover job run
  1263. outcomes, duration histograms, retries, next-run times, configuration reload
  1264. health, and cluster and leader election state, in both the Prometheus text
  1265. format and OpenMetrics. For the full metric reference, scrape configuration,
  1266. and example alert rules, see
  1267. [metrics with Prometheus](https://github.com/ptweezy/cronstable/wiki/Metrics-with-Prometheus).
  1268. The daemon can also push per-job metrics to
  1269. [statsd](https://github.com/statsd/statsd):
  1270. ```yaml
  1271. jobs:
  1272. - name: test01
  1273. command: echo "hello"
  1274. schedule: "* * * * *"
  1275. statsd:
  1276. host: my-statsd.example.com
  1277. port: 8125
  1278. prefix: my.cron.jobs.prefix.test01
  1279. ```
  1280. With this configuration, cronstable sends the following metrics over UDP to the
  1281. statsd server at `my-statsd.example.com:8125`:
  1282. ```text
  1283. my.cron.jobs.prefix.test01.start:1|g # sent when the job starts
  1284. my.cron.jobs.prefix.test01.stop:1|g # the rest are sent when the job stops
  1285. my.cron.jobs.prefix.test01.success:1|g
  1286. my.cron.jobs.prefix.test01.duration:3|ms
  1287. ```
  1288. For details, see
  1289. [metrics with statsd](https://github.com/ptweezy/cronstable/wiki/Metrics-with-Statsd).
  1290. ### Status badges
  1291. The [HTTP API](#http-api) serves a live SVG badge for each job, and one for
  1292. the whole job set, in the style of the build badges on many README files:
  1293. ![nightly-backup: passing](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/badge-passing.svg)
  1294. ![cronstable: 12 passing](https://raw.githubusercontent.com/ptweezy/cronstable/main/docs/img/badge-fleet.svg)
  1295. Embed a badge with Markdown that links it to the job in the dashboard:
  1296. ```markdown
  1297. [![nightly-backup](https://cron.example.com/jobs/nightly-backup/badge.svg)](https://cron.example.com/#job/nightly-backup)
  1298. ```
  1299. A job's badge shows a verdict such as `passing`, `failing`, `overdue`, or
  1300. `paused`, and the fleet badge at `/badge.svg` counts the jobs in the most
  1301. urgent state, such as `2 failing`. The command palettes of the web and
  1302. terminal dashboards copy this Markdown. When authentication is enabled, badge
  1303. requests require a token, which GitHub's image proxy can't send. Browsers also
  1304. block pages on other origins from embedding the badge. Set
  1305. `web.badges.public: true` to allow unauthenticated, cross-origin requests to
  1306. the two badge routes. For every verdict, the query parameters, and caching, see
  1307. [status badges](https://github.com/ptweezy/cronstable/wiki/Status-Badges) in
  1308. the wiki.
  1309. ## HTTP API
  1310. To control cronstable remotely, add a `web` section with one or more listeners:
  1311. ```yaml
  1312. web:
  1313. listen:
  1314. - http://127.0.0.1:8080
  1315. - unix:///tmp/cronstable.sock
  1316. ```
  1317. Every listen address needs a scheme: `http://`, `https://` (see
  1318. [TLS and client certificates](#tls-and-client-certificates)), or `unix://`,
  1319. which Windows doesn't support. The same listeners serve the
  1320. [web dashboard](#web-dashboard); to serve only the API, set `web.ui: false`.
  1321. The API covers these areas:
  1322. * The daemon: version, status, summary, metrics, and job-set ID
  1323. * Jobs: start, cancel, pause and resume, run history, live log tails over
  1324. server-sent events (SSE), and resources
  1325. * Schedules: preview, pressure, duplicates, suggest, and why
  1326. * DAGs
  1327. * The durable state store
  1328. * Push device pairing
  1329. * The cluster and fleet views
  1330. * An iCal feed of upcoming runs
  1331. * SVG status badges for a README or wiki
  1332. For example, the following HTTPie command pauses a job for a two-hour
  1333. maintenance window:
  1334. ```shell
  1335. $ http post http://127.0.0.1:8080/jobs/test-02/pause durationSeconds:=7200 note="db migration"
  1336. HTTP/1.1 200 OK
  1337. {"paused": {"since": "2026-07-19T14:00:00+00:00", "until": "2026-07-19T16:00:00+00:00", "note": "db migration", "by": "api", "channel": "api"}}
  1338. ```
  1339. The [HTTP API](https://github.com/ptweezy/cronstable/wiki/HTTP-API) reference in
  1340. the wiki documents every endpoint, with its request and response shapes. The
  1341. repository also includes a machine-readable
  1342. [OpenAPI specification](https://github.com/ptweezy/cronstable/blob/main/docs/openapi.yaml).
  1343. ### Authentication
  1344. By default, the API is unauthenticated: anyone who can reach a listener can call
  1345. every endpoint except `POST /shutdown`, which always requires a token. A
  1346. loopback address keeps other machines out, but every local account on the host
  1347. can still reach it. To require a bearer token, set `web.authToken`:
  1348. ```yaml
  1349. web:
  1350. listen:
  1351. - http://0.0.0.0:8080
  1352. authToken:
  1353. fromEnvVar: CRONSTABLE_WEB_TOKEN
  1354. ```
  1355. Clients send the token in an `Authorization: Bearer <token>` header. The
  1356. dashboard page loads without a token, then prompts for one and keeps it only in
  1357. that browser tab. `cronstable tui`, `cronstable mcp`, and `cronstable pair`
  1358. read it from the `CRONSTABLE_WEB_TOKEN` environment variable. For narrower
  1359. credentials, such as a view-only token for a wallboard, add
  1360. [scoped tokens](https://github.com/ptweezy/cronstable/wiki/HTTP-API#scoped-tokens-webauthtokens).
  1361. To turn the dashboard into a public read-only board, add `view` to
  1362. `web.anonymousScopes` alongside the tokens:
  1363. ```yaml
  1364. web:
  1365. listen:
  1366. - http://0.0.0.0:8080
  1367. authToken:
  1368. fromEnvVar: CRONSTABLE_WEB_TOKEN
  1369. anonymousScopes:
  1370. - view
  1371. ```
  1372. Requests without credentials then get the `view` scope, the dashboard skips the
  1373. token prompt and shows a view-only interface, and every route that changes
  1374. state still requires a token. For details, see
  1375. [public read-only access](https://github.com/ptweezy/cronstable/wiki/HTTP-API#public-read-only-access-webanonymousscopes).
  1376. ### TLS and client certificates
  1377. The `web.listen` option also accepts `https://` addresses, which use the
  1378. certificate and key from a `web.tls` block. Each listener keeps its own
  1379. transport, so one daemon can serve the same API and dashboard in plaintext on
  1380. loopback and over TLS on a routable interface. `unix://` listeners are always
  1381. plaintext; the socket's own permissions (`socketMode`) control access.
  1382. ```yaml
  1383. web:
  1384. listen:
  1385. - http://127.0.0.1:8080 # loopback, plaintext
  1386. - https://0.0.0.0:8443 # served with the material below
  1387. tls:
  1388. cert: /etc/cronstable/web.pem
  1389. key: /etc/cronstable/web.key
  1390. clientCa: /etc/cronstable/callers-ca.pem # optional: require client certificates
  1391. ```
  1392. To require mutual TLS, which authenticates clients as well as encrypting
  1393. connections, set `clientCa`. Web certificates rotate in place without a daemon
  1394. restart. The `cronstable tui`, `cronstable mcp`, and `cronstable pair` clients
  1395. take matching `--cacert`, `--client-cert`, `--client-key`, and `--insecure`
  1396. flags. The listeners, the cluster, the job CLI, and these clients verify
  1397. certificates in OpenSSL's strict X.509 mode on every Python version. With
  1398. OpenSSL 3.0 or later, a CA certificate needs critical `basicConstraints`, a
  1399. key usage with `keyCertSign`, and a Subject Key Identifier. Certificates
  1400. issued by a CA need an Authority Key Identifier. Failed handshakes log
  1401. the rejection reason. For how to issue the certificates, the mTLS trust
  1402. model and how it combines with `web.authToken`, and how rotation works, see
  1403. [listener TLS](https://github.com/ptweezy/cronstable/wiki/Listener-TLS) in the
  1404. wiki.
  1405. ## Replicas
  1406. ### Job-set ID
  1407. The job-set ID is a fingerprint of the set of jobs that a cronstable instance
  1408. runs. Two instances have the same ID exactly when they run the same set of
  1409. jobs, so replicas deployed from one configuration can compare IDs to confirm
  1410. that none has drifted.
  1411. cronstable computes the ID from each job's effective configuration, after
  1412. merging defaults. The ID doesn't depend on job order, on whether a setting is
  1413. written inline or in a `defaults` block, or on whether a schedule is written as
  1414. an object or as the equivalent crontab string. It covers every field that
  1415. affects behavior, such as `command`, `schedule`, `shell`, retry and reporting
  1416. policy, `timezone`, and `enabled`. It never includes secret values or
  1417. `environment` values (only variable names), so it's safe to log and serve. It
  1418. also leaves out per-host values such as `workingDirectory`. Because it reflects
  1419. platform-dependent defaults, such as the default `shell`, compare only instances
  1420. that run on the same platform.
  1421. You can get the ID in three ways:
  1422. * The CLI prints the ID and exits, which is useful in scripts and health
  1423. checks:
  1424. ```shell
  1425. $ cronstable -c /etc/cronstable.d --job-set-id
  1426. v1:b834d7565aee0da50cd017f666651a5ba3b2e6b161daf0cb6e430f23f51ce90b
  1427. ```
  1428. * `GET /job-set-id` on the [HTTP API](#http-api) returns it, as JSON if you
  1429. send `Accept: application/json`. The dashboard header shows it too.
  1430. * cronstable logs the ID at startup, and again whenever a configuration reload
  1431. changes it.
  1432. For everything the fingerprint covers and why, see
  1433. [job-set ID](https://github.com/ptweezy/cronstable/wiki/Job-Set-ID) in the wiki.
  1434. ### Clustering and leader election
  1435. By default, cronstable runs as a single instance, and every replica runs every
  1436. job. An optional `cluster` section lets several replicas coordinate. With the
  1437. default `gossip` backend, each node serves a small `GET /peer` endpoint over
  1438. mutual TLS and polls its configured peers. The nodes compare
  1439. [job-set IDs](#job-set-id) to confirm that they run the same set of jobs, which
  1440. is called cluster peer attestation. With `electLeader: true`, the nodes also use
  1441. that attestation to elect a leader, which requires a quorum:
  1442. ```yaml
  1443. cluster:
  1444. listen: "0.0.0.0:8443" # the mTLS listener for this node
  1445. tls:
  1446. ca: /etc/cronstable/cluster-ca.pem # trust anchor for peer certificates
  1447. cert: /etc/cronstable/this-node.pem # this node's certificate
  1448. key: /etc/cronstable/this-node.key
  1449. peers:
  1450. - host: cronstable-b.internal:8443
  1451. - host: cronstable-c.internal:8443
  1452. nodeName: cronstable-a # optional; defaults to the system hostname
  1453. electLeader: true # observe-only if false (the default)
  1454. ```
  1455. Each node independently elects the member with the lowest `nodeName` among the
  1456. peers that agree on the job-set ID, provided those peers form a quorum (a
  1457. strict majority) of the cluster. Because peer views can differ or become stale,
  1458. multiple nodes can consider themselves leader, so the `gossip` election is best
  1459. effort: it can duplicate or skip runs during failures or changes in cluster
  1460. membership.
  1461. To coordinate leadership through a shared lease, set `cluster.backend` to
  1462. `kubernetes` (a `coordination.k8s.io/v1` Lease), `etcd` (a lease-bound key), or
  1463. `filesystem` (a shared mount with locks across hosts and bounded clock skew, as
  1464. in [tutorial 4](#tutorial-4-coordinate-two-replicas)). These backends fence
  1465. leadership while the coordination store is reachable. Jobs can still miss runs,
  1466. and the lease doesn't make their side effects exactly-once. Each job's
  1467. `clusterPolicy` (`Leader`, `PreferLeader`, or `EveryNode`) sets its behavior
  1468. when leadership can't be confirmed, as tutorial 4 describes.
  1469. The `GET /cluster` endpoint returns the current view: members, the elected
  1470. leader, quorum, and any conflicts, and the dashboard shows the same view in a
  1471. panel. For the trust model, quorum math, sizing guidance,
  1472. `distribution: spread` load balancing, and the lease backends, see the
  1473. [clustering and leader election](https://github.com/ptweezy/cronstable/wiki/Clustering-and-Leader-Election)
  1474. guide in the wiki. To watch an election live, try a cluster from the
  1475. [example gallery](#example-gallery).
  1476. ## Production container deployment
  1477. In its default stateless configuration, the cronstable container needs no
  1478. writable filesystem paths. The daemon reads its configuration and secrets and
  1479. writes its output to stdout and stderr. It can run as a non-root user with the
  1480. `RuntimeDefault` seccomp profile, a read-only root filesystem, all Linux
  1481. capabilities dropped, and configuration and secret volumes mounted with an
  1482. `fsGroup`.
  1483. Mount writable storage for the optional features you enable:
  1484. * Durable state needs a writable directory at `state.path` for history,
  1485. retries, workflows, and any archived output.
  1486. * Filesystem clustering needs a writable shared directory at
  1487. `cluster.filesystem.path` that supports locks across hosts.
  1488. * Push device pairing needs a writable directory containing `push.devicesFile`,
  1489. or a writable state store when `devicesFile` is omitted.
  1490. * A `unix://` web listener needs a writable directory for its socket.
  1491. * The standalone binary needs a writable, executable temporary directory (see
  1492. [install a standalone binary](#install-a-standalone-binary)). The container
  1493. images and pip installations don't need one.
  1494. Job commands and custom file logging can also need writable paths or additional
  1495. permissions. Per-job [user and group switching](#run-as-another-user-or-group)
  1496. requires root.
  1497. The published images (`ghcr.io/ptweezy/cronstable` and
  1498. `docker.io/ptweezy/cronstable`) run as non-root, with `cronstable` as the
  1499. entrypoint and `-c /etc/cronstable.d` as the default command. Mount your configuration
  1500. read-only, and provide writable mounts for the features and jobs that need them.
  1501. For deployment examples, including a Kubernetes `Deployment` with a restricted
  1502. security context, baking configuration into your own image, and health checks,
  1503. see
  1504. [production deployment](https://github.com/ptweezy/cronstable/wiki/Production-Deployment)
  1505. in the wiki.
  1506. ## Windows
  1507. cronstable runs natively on Windows (x64, ARM64, and 32-bit x86). Install it
  1508. with [WinGet](#install-using-homebrew-or-winget), with pip, or from the
  1509. [Windows builds](#install-a-standalone-binary) on the releases page, which
  1510. don't need Python. Scheduling, reporting, retries, the HTTP API, and the
  1511. dashboards work the same as on POSIX systems. These details differ:
  1512. * Default configuration location: without `-c`, cronstable uses the
  1513. machine-wide `%ProgramData%\cronstable` directory when it contains
  1514. configuration, and otherwise the per-user `%APPDATA%\cronstable` directory.
  1515. `cronstable init` writes a commented starter configuration to whichever
  1516. applies.
  1517. * Default shell: a string `command` without a `shell` runs through the native
  1518. command processor (`%ComSpec%`, which is `cmd.exe`). You can also set
  1519. `shell: cmd` or `shell: powershell`, or pass `command` as a list to bypass
  1520. the shell:
  1521. ```yaml
  1522. jobs:
  1523. - name: powershell-job
  1524. command:
  1525. - powershell
  1526. - -Command
  1527. - Get-Date
  1528. schedule: "*/5 * * * *"
  1529. captureStdout: true
  1530. ```
  1531. * Graceful shutdown: press `Ctrl-C` to stop cronstable after the running jobs
  1532. finish, the same as `SIGTERM` on POSIX. Each job runs in its own console
  1533. process group, so the keystroke never reaches the jobs themselves. Closing
  1534. the console window or shutting down the machine also lets running jobs
  1535. finish, within the few seconds that Windows allows. Signing out doesn't stop
  1536. the daemon. To stop a daemon that has no console, call the authenticated
  1537. `POST /shutdown` route.
  1538. * Unsupported options: Windows has no `setuid` or `setgid` equivalent, so
  1539. cronstable rejects per-job `user` and `group` settings with a configuration
  1540. error. It also skips `unix://` web listeners with a warning; use an
  1541. `http://` listener instead.
  1542. For everything else that differs, see
  1543. [running on Windows](https://github.com/ptweezy/cronstable/wiki/Running-on-Windows)
  1544. in the wiki.
  1545. ### Windows service
  1546. `cronstable service install -c C:\ProgramData\cronstable` registers the
  1547. scheduler with the Service Control Manager (SCM). The service starts at boot,
  1548. runs whether or not anyone is signed in, appears in `services.msc`, and uses the
  1549. Windows recovery actions. When you stop the service, it lets running jobs finish
  1550. first. `cronstable service reload` rereads the configuration immediately, like
  1551. `SIGHUP` on POSIX.
  1552. The single-file `.exe` can't host a service, because its bootloader runs the
  1553. program in a child process that the SCM never sees; `service install` reports
  1554. this. To run as a service, install with pip or pipx, or use the one-directory
  1555. `.zip` or the MSI. To run the single-file `.exe` unattended, start it at boot
  1556. from Task Scheduler instead (see the
  1557. [Task Scheduler recipe](https://github.com/ptweezy/cronstable/wiki/Running-on-Windows#task-scheduler-for-the-one-file-executable)).
  1558. For details, see
  1559. [Windows Service](https://github.com/ptweezy/cronstable/wiki/Windows-Service).
  1560. ### Import from Task Scheduler
  1561. `cronstable import-taskscheduler tasks.xml -o jobs.yaml` converts exported Task
  1562. Scheduler tasks into cronstable jobs. It maps time, calendar, and boot triggers;
  1563. `Exec` actions; working directories; execution time limits; instance policy;
  1564. and priority. It lists everything it can't convert, with the reason, instead of
  1565. dropping it. On a whole-machine export, that list is long, because most tasks
  1566. on a stock Windows installation are COM handlers or event-driven internals
  1567. rather than schedules. Exporting a task leaves it registered, so disable or
  1568. remove the original task after you migrate it, or it runs in both schedulers.
  1569. For details, see
  1570. [Importing from Task Scheduler](https://github.com/ptweezy/cronstable/wiki/Importing-Task-Scheduler).
  1571. ## Documentation map
  1572. Every feature has its own page in the
  1573. [wiki](https://github.com/ptweezy/cronstable/wiki), and the wiki's sidebar is
  1574. the full index. Good places to start are
  1575. [Installation](https://github.com/ptweezy/cronstable/wiki/Installation), the
  1576. [Configuration Reference](https://github.com/ptweezy/cronstable/wiki/Configuration-Reference),
  1577. the [Command-Line Reference](https://github.com/ptweezy/cronstable/wiki/CLI-Reference),
  1578. the [Web Dashboard tour](https://github.com/ptweezy/cronstable/wiki/Web-Dashboard),
  1579. and [Troubleshooting](https://github.com/ptweezy/cronstable/wiki/Troubleshooting).
  1580. ## Contributing and license
  1581. Bug reports, feature ideas, and pull requests are welcome, including ones
  1582. written with AI help. For the development setup, the Developer Certificate of
  1583. Origin (DCO) sign-off, and how to open a pull request, see
  1584. [CONTRIBUTING.md](https://github.com/ptweezy/cronstable/blob/main/CONTRIBUTING.md).
  1585. For how releases work, see
  1586. [Release Pipeline](https://github.com/ptweezy/cronstable/wiki/Release-Pipeline).
  1587. The [performance benchmarks](https://github.com/ptweezy/cronstable/wiki/Performance-Benchmarks)
  1588. compare speed and memory use against the latest release on every commit to
  1589. catch regressions before release.
  1590. cronstable's development relies on AI agents. The maintainer reviews
  1591. every change before it merges, and each change must pass the test suite and its
  1592. coverage floor. The project judges each contribution by the work itself,
  1593. whatever tools produced it (see
  1594. [AI use](https://github.com/ptweezy/cronstable/blob/main/CONTRIBUTING.md#ai-use)).
  1595. Report security vulnerabilities privately, not in a public issue.
  1596. [SECURITY.md](https://github.com/ptweezy/cronstable/blob/main/SECURITY.md)
  1597. describes the disclosure process, what's in scope (including the hosted relay
  1598. and the public demo), and what to expect.
  1599. cronstable is
  1600. [MIT-licensed](https://github.com/ptweezy/cronstable/blob/main/LICENSE); for how
  1601. the repository's licensing is organized, see
  1602. [LICENSING.md](https://github.com/ptweezy/cronstable/blob/main/LICENSING.md).
  1603. The MIT License covers the code, not the brand: cronstable™ and the cronstable
  1604. logo are trademarks of Parker Loflin (see
  1605. [TRADEMARKS.md](https://github.com/ptweezy/cronstable/blob/main/TRADEMARKS.md)).
  1606. The rendered logo artwork is also excluded from the MIT grant, but the code that
  1607. draws it is MIT-licensed (see
  1608. [brand assets](https://github.com/ptweezy/cronstable/blob/main/LICENSING.md#brand-assets)).
  1609. cronstable is a fork of [yacron](https://github.com/gjcarneiro/yacron) by
  1610. Gustavo Carneiro, and it continues development from yacron version 0.19.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.