/ kraahn-stuh-bl /

cronstable is a feature-rich job scheduler and simple workflow orchestrator for anything from a single machine to a cluster, built with efficiency, security, and stability in mind. It runs your commands on a schedule, defined in YAML or loaded from an existing crontab, and adds retries, alerts, saved run history, workflows, and dashboards for the web, the terminal, and iOS.

Why cronstable?

Scheduling

• YAML and classic crontab files: define jobs in YAML, or load an existing crontab (see classic crontab files).
• Business-day and hashed schedules: run on the last weekday of the month or the third Friday, and spread a fleet's jobs across the hour with H (see schedules).
• Second-level schedules and time zones: run jobs as often as every second, and evaluate each job's schedule in any time zone (see second-level schedules and time zones).
• iCal calendar export: subscribe to upcoming runs in your calendar app, or view them in the dashboard's week calendar (see calendar export).
• Schedule introspection: ask why a job did or didn't run at a given moment, and get a field-by-field answer from the scheduler's own match test. Collision heatmaps, duplicate detection, and slot suggestions help you place new jobs (see schedule introspection).
• Schedule linting: catch schedules that can never run, uneven intervals, and times that daylight saving time skips or repeats (see schedule linting).

Failure handling

• Retries with backoff: retry failed runs with exponential backoff, and choose whether a nonzero exit status or output on stderr or stdout counts as a failure (see failure detection and retries).
• Result verification: check a job's output before recording success or starting downstream tasks (see result verification).
• Alerts: report failures through Sentry, email, Slack-compatible webhooks, shell commands, and the Windows Event Log (see reporting).
• End-to-end encrypted push notifications: send alerts to the iOS app that only paired devices can decrypt (see push notifications).
• Late-run detection: alert when a run is missing, late, or running too long, and mark the job as overdue in the dashboards (see late-run detection).

Durability and orchestration

• Opt-in durable state: keep run history and pending retries across restarts, catch up missed runs, and give job commands shared storage, locks, and idempotency keys (see durable state).
• Durable workflows: run tasks as a directed acyclic graph (DAG) with dependencies, data sharing, dynamic fan-out, sensors, and approval gates (see workflow orchestration).
• Selective workflow recovery: retry failed tasks or replay failed dates while reusing successful results (see workflow recovery).
• Shared resource pools: limit capacity across jobs and workflow tasks, with priority queues and deadlines (see resource pools).

Observability and control

• Web, terminal, and iOS dashboards: follow live logs, review history, control jobs and workflows, and monitor the cluster.
• HTTP API: read job status and history, and start, cancel, or pause jobs (see HTTP API).
• Runtime pause and resume: pause scheduled runs for maintenance without editing configuration (see pausing jobs).
• Prometheus and statsd metrics: track outcomes, durations, retries, and cluster health (see metrics).
• Per-job resource monitoring: track CPU time and peak memory across each job's process tree (see resource monitoring).
• Built-in TLS: serve the API over HTTPS, optionally require client certificates, and rotate certificates without a restart (see TLS and client certificates).
• MCP server: let AI agents inspect jobs and debug schedules, read-only by default, with optional control (see MCP).

Fleets

• Opt-in clustering and leader election: coordinate which replica runs scheduled jobs through a Kubernetes Lease, an etcd lease, a shared filesystem, or mutual TLS between peers (see clustering and leader election).
• Job-set ID: compare configuration fingerprints to detect drift between replicas (see job-set ID).

Deployment

• Prebuilt releases: container images in eight variants, and self-contained binaries for Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD, and illumos (see installation).
• Built for restricted containers: run as a non-root user with a read-only root filesystem and restricted Kubernetes security settings (see production container deployment).
• Native Windows support: run as a Windows service, install with WinGet or an MSI, and import Task Scheduler tasks (see Windows).

Quick start

Install cronstable with pipx, or with pip install cronstable inside a virtual environment. For Docker, Homebrew, WinGet, and standalone binaries, see 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. The job runs once a minute, and schedules use UTC unless a job sets a time zone. cronstable picks up changes to the file within a minute, so you can add jobs without restarting it.

Four short tutorials build on this configuration:

• Retry failed jobs, and alert when the retries fail.
• Survive restarts and catch up missed runs.
• Chain tasks into a durable workflow with an approval gate.
• Coordinate two replicas with leader election.

To follow your jobs from a phone, pair the iOS app from the dashboard. To see every feature at once, start the nine-node 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 YA