The canonical, exhaustive reference for the cronstable YAML configuration. It documents the top-level structure and every per-job option, with the exact strictyaml type, default, and load-time validation rule taken from cronstable/config.py. Deep topics (schedules, reporting, the HTTP API, metrics, logging, includes) have dedicated pages linked from each section.

A configuration is either a single YAML file or a directory of *.yml/*.yaml files, selected with the -c flag (see the command-line reference). The document is parsed and validated against a fixed strictyaml schema (CONFIG_SCHEMA). An unknown key, a wrong type, or a malformed value is a hard ConfigError at load time. An empty document is valid.

Classic (Vixie-style) crontab files are accepted alongside YAML, recognized by name (*.crontab, *.cron, or a file named crontab). Each entry is lowered to an ordinary job definition and merged over the same DEFAULT_CONFIG defaults documented later, so internally it is configured to cronstable's standard behavior rather than an emulation of cron's. A crontab can only define jobs. Every other section on this page (and any per-job option beyond schedule, command, shell, timezone, and environment) is YAML-only. See classic crontabs.

In the option tables that follow, "Required" means the strictyaml key is mandatory (not wrapped in Opt(...)). Every other key is optional and falls back to the default shown. Per-job defaults come from DEFAULT_CONFIG. A defaults: block and any included files override DEFAULT_CONFIG, and an individual job overrides both. See includes, defaults, and multi-file config for the precise merge order.

After validation, ${VAR} and ${VAR:-default} in any string value are expanded from cronstable's environment ($$ is a literal $), so a listen address, state path, time zone, or webhook URL can come from an environment variable. Job and reporter command/shell fields are left for the runtime shell, and the logging section is left for Python's logging.config. An unset variable with no default is a hard ConfigError. See environment-variable interpolation.

defaults: { ... }   # optional: per-job defaults for this file
jobs:               # optional: list of job definitions
  - name: ...
    command: ...
    schedule: ...
dags:               # optional: durable orchestration DAGs (needs state)
  - name: ...
    tasks: [ ... ]
include: [ ... ]    # optional: list of other config files to merge
web: { ... }        # optional: HTTP control API
mcp: { ... }        # optional: Model Context Protocol server for AI agents
cluster: { ... }    # optional: mTLS peer attestation / leader election
state: { ... }      # optional: durable state store (history, catch-up, retries)
pools: { ... }      # optional: shared capacity and durable admission queues
logging: { ... }    # optional: Python logging dictConfig
notify: { ... }     # optional: daemon/orchestration event notifications
push: { ... }       # optional: E2E-encrypted push alerts (relay + device registry)

listen is the only required key. Full behavior, authentication, and endpoint semantics are documented in HTTP Control API. The tls block, certificate rotation, and the client-side flags are documented in Listener TLS.

Opt-in Model Context Protocol server, so an AI agent (Claude Desktop/Code, Cursor, VS Code Copilot, and other clients) can drive cronstable the way an operator drives the dashboard. It is served as a stateless Streamable-HTTP endpoint at POST /mcp on the existing web.listen addresses (inheriting the same authToken / unix-socket auth) and over the cronstable mcp stdio bridge for desktop clients. Every field is optional. The server is off unless enabled: true, and requires a web section (there is nowhere to serve it otherwise). Tools operate on the same data as the REST API, so there is one source of truth.

web:
  listen:
    - http://127.0.0.1:8080
  authToken:
    fromEnvVar: CRONSTABLE_WEB_TOKEN   # also gates /mcp

mcp:
  enabled: true
  readOnly: false        # allow mutating tools
  toolsets:              # jobs + DAG reads/control
    - observe
    - dags
    - act

Wire a client to it with, for example, claude mcp add --transport http cronstable https://host/mcp --header "Authorization: Bearer $TOKEN", or over stdio with claude mcp add cronstable -- cronstable mcp --url http://127.0.0.1:8080.

This section is only the configuration schema. MCP documents the full tool catalog, the prompts and resources, client setup recipes, and the stdio bridge's flags.

Optional. A leadership backend coordinates scheduled jobs across replicas using one configuration. Execution guarantees depend on the backend and each job's clusterPolicy. cluster.backend selects the coordination mechanism:

• The default gossip backend attests, over mutual TLS, that a static list of peers is running the same job set, and runs a best-effort quorum election.
• The kubernetes and etcd backends use a coordination store (a Lease / a lease-bound key) for fenced leadership with a single lease holder.
• The filesystem backend elects through a fenced TTL lease on a shared POSIX mount, with no coordination service at all. Its safety additionally rests on synchronized clocks; see its table later.

There can be at most one cluster block across the whole configuration; a duplicate in an included file or a second config-directory file raises a ConfigError. Defaults come from DEFAULT_CLUSTER (plus DEFAULT_K8S / DEFAULT_ETCD / DEFAULT_FILESYSTEM for the lease backends) and are applied only when a cluster section is present.

Gossip backend (backend: gossip). listen, tls, and peers are required only for this backend:

Gossip load-time validation (in addition to the numeric ranges listed earlier): every tls path (ca, cert, key) must be nonempty, so a blank scalar (what a template renders for an unset variable) is a ConfigError at load rather than a /peer listener that requires no client certificate. Every address (listen and each peers[].host) must be host:port with a numeric port in 1-65535, and an IPv6 host must be written bracketed ([2001:db8::1]:8900). A bare IPv6 literal is a ConfigError at load (looks like a bare IPv6 address; write it as [ipv6]:port), because splitting it at the last colon would silently mis-read the host and, for a peer, drop it from quorum with no error.

The same address checks apply to the observability overlay's listen/peers, which are built through the same code path.

With electLeader: true, a 2-node cluster (one peer) is rejected outright with a ConfigError (a quorum of 2 needs both up, strictly worse than one replica). An even cluster size greater than 2 is allowed but logs a warning (an odd count is best for a clean majority).

Kubernetes backend (backend: kubernetes), under cluster.kubernetes. A coordination.k8s.io/v1 Lease is the fence. Defaults from DEFAULT_K8S:

etcd backend (backend: etcd), under cluster.etcd. A lease-bound key is the fence; the backend uses etcd's v3 gRPC-gateway JSON/HTTP API directly (no native client). Defaults from DEFAULT_ETCD:

etcd load-time guards: any TLS material (tls.ca/tls.cert/tls.key) requires at least one https:// endpoint (otherwise it would be silently ignored and traffic sent in cleartext, a ConfigError). Likewise a username or resolved password requires every endpoint to be https://, so the credentials and bearer token are never POSTed in cleartext. A username without a resolvable password is also rejected.

One more etcd check is advisory rather than fatal: a small ttl also shrinks the per-request timeout each renew POST gets (roughly (ttl - max(1, ttl/3) - 1s) / 5), and when that budget falls below ~1 second (any integer ttl from 3 to 8) load emits a one-time startup advisory.

If a single round-trip to etcd is slower than the budget (such as a cross-AZ or cross-region endpoint), every renew round times out, the node treats a reachable etcd as unreachable, and Leader jobs fail closed. It is the operator's explicit ttl choice and a local, low-latency etcd is fine, so cronstable warns rather than rejects. Raise ttl otherwise.

Filesystem backend (backend: filesystem), under cluster.filesystem. The flock-guarded, fence-counted TTL lease of the durable state store's filesystem backend is the fence, taken over a shared POSIX mount (Amazon EFS (NFSv4) / S3 Files). There is no coordination service: the mount is the store. Defaults from DEFAULT_FILESYSTEM:

The lease-backend family rules apply exactly as for kubernetes/etcd: electLeader is forced on (configuring the backend is opting into leadership), distribution: spread is a hard ConfigError, a store block belonging to a different backend (say an etcd: block under backend: filesystem) is a ConfigError rather than silently ignored, and gossip-only keys (listen, tls, peers, interval, driftAfter) draw an emit-once startup advisory.

One filesystem-backend guard is deferred to startup, because it needs the live mount. start() probes lock fidelity and hard-refuses a store whose locks are no-ops, verbatim cluster.backend filesystem: refusing to elect over <path>: <reason>. The probe requires two descriptors of one file to contend on a non-blocking exclusive lock; on Linux start() additionally refuses an NFS mount carrying nolock or local_lock=flock/local_lock=all, because those honor locks host-locally.

A refused start leaves the cluster manager unbuilt, so Leader jobs fail closed (the safe direction). Both checks run on one host, so on platforms without /proc/mounts (Windows, macOS) the residual risk rests on the operator's topology: shared assertion.

Unlike the kubernetes/etcd fences, election safety here also rests on wall clocks (two leaders need inter-host clock skew above roughly 2 seconds): run NTP on every node, the same requirement durable state documents for shared mounts.

Because the cluster schema has many load-time rejections (the ordering rules, the RFC1123 and https guards, the credential-over-plaintext refusals, and the lease-family rules listed earlier), check a cluster configuration before deploying with cronstable --validate-config, which runs the full load path and prints the first ConfigError without starting the scheduler. See the command-line reference.

Full behavior, the trust model, quorum math, the lease backends' guarantees, and per-job clusterPolicy are documented in Clustering and Leader Election.

cluster.observability shares fleet data (each node's live CPU/memory, see GET /node, and per-job run summaries) across the cluster for the dashboard's fleet view, independent of which backend owns election. It exists because the fleet view depends on node-to-node gossip, which the lease backends do not have: it lets a kubernetes/etcd/filesystem cluster run a second, election-inert gossip mesh purely to carry that data.

Two shapes:

• backend: gossip: the election mesh already exchanges /peer bodies, so observability is an opt-in marker. An observability block with shareNodeStats: true adds node CPU/memory to what that mesh already gossips. listen/tls/peers here are a ConfigError (redundant), and so are the overlay tuning keys nodeName/interval/driftAfter/connectTimeout (there is no overlay mesh to tune; the stats gossip at cluster.interval, so set the cluster-level keys instead). The stats ride each /peer response as an X-Cronstable-Node-Stats header, never in the body, so sharing live load keeps the mesh's idle 304 optimization intact.
• A lease backend (kubernetes/etcd/filesystem): election stays with the lease store. observability runs a dedicated gossip mesh (its own listen/tls/peers, all required) that never elects (it holds no leadership and gates no jobs), purely to carry fleet data.

cluster:
  backend: kubernetes            # election via a coordination.k8s.io Lease
  kubernetes:
    leaseName: cronstable-leader
  observability:                 # a gossip mesh JUST for the fleet view
    listen: "0.0.0.0:8140"
    tls:
      ca: /tls/ca.pem
      cert: /tls/node.pem
      key: /tls/node.key
    peers:
      - host: node-b:8140
      - host: node-c:8140

Requires psutil (a core dependency) for the CPU/memory numbers; a node that cannot read its own load shares none. Node stats are best-effort observability: a malformed or hostile peer payload degrades to "no data for that node", never poisoning the view.

Optional. Enables the durable state store: restart-durable run history, missed-run catch-up, restart-surviving retries, once-per-boot @reboot dedupe, restart-durable Prometheus job counters, and durable output archival. By default cronstable is stateless: absent this section, everything stays in memory.

The store is a directory of immutable JSON records behind a single filesystem backend. A local path gives single-node durability, while a shared Amazon EFS (NFSv4) / S3 Files mount gives the same durability and coordination fleet-wide (the same code either way; the mount decides the reach).

There can be at most one state block across the whole configuration; a duplicate in an included file or a second config-directory file raises a ConfigError. Defaults come from DEFAULT_STATE and are applied only when a state section is present. (The web dashboard's browser-side IndexedDB run ledger is a separate, client-local feature, unrelated to this store.)

The state.jobApi sub-keys:

path is the only required key. Durable state documents the full behavior: the store layout and durability model, restart-surviving retries, missed-run catch-up, @reboot dedupe, the service level agreement (SLA) trends endpoint, garbage collection, the state metrics, and the cronstable state CLI subcommands (backup, restore, migrate, gc, check, migrate-schema). The per-job knobs that build on this store are under durable state and catch-up later.

A list of durable orchestration DAGs. Requires a state section with jobApi.enabled (the default). Full guide: orchestration and DAGs.

Per-DAG keys:

Per-task keys:

Plus the shared launch fields a job takes: shell, environment, captureStdout / captureStderr, monitorResources, saveLimit, maxLineLength, streamPrefix, failsWhen, executionTimeout, killTimeout, priority, resourceLimits, statsd, user / group, env_file, workingDirectory, secrets, stateAllowedScopes, verify, pool, poolSlots, queuePriority, queueTimeout, and report-only onFailure / onSuccess hooks (each accepts a report block that fires on the task's runs; there is no onFailure.retry on a task, because a task's attempts come from the node's retries field listed earlier). Where a task's monitorResources numbers surface is covered under metrics later.

The graph is validated at load: unknown/duplicate ids, a cycle, a self-edge, or an expand.fromTask that is not a direct non-mapped dependency are config errors.

A standard Python logging.config dictionary-schema. version (Int) is required; incremental, disable_existing_loggers, formatters, filters, handlers, loggers, and root are optional. See logging configuration.

Daemon and orchestration event notifications: events that belong to no single job run (so no per-job hook would fire) delivered through the same reporter machinery as the per-job hooks. See reporting for the delivery semantics and templates.

The daemon-global half of the end-to-end encrypted push reporter: where sealed alerts are relayed and where device pairings are stored. Turning the reporter on stays per-job/per-event (report.push.enabled / notify.report.push); this section only says where alerts go. Requires the push extra (PyNaCl). Without it, the daemon refuses to start on a configuration that has a push: section. See push notifications.

Every key in this section comes from _job_schema_dict (jobs) / _job_defaults_common (defaults and the per-file defaults). Defaults are from DEFAULT_CONFIG. name, command, and schedule are required on a job; all other keys are optional. The three keys name, command, and schedule are not allowed in a defaults block (only the common keys are).

See output capturing for buffering, truncation, and the captured-output handoff to reporters.

See schedules and timezones.

See concurrency and timeouts.

verify adds a post-command result check to jobs and executable DAG tasks. Its required command is a string or sequence of strings; its optional timeout is a finite positive float, defaulting to 60. The default verify: null disables the check. See result verification.

The top-level pools map declares named pools. Each requires integer slots and accepts integer maxQueued (default 1000); both range from 1 to 10000. Pools require state. Names must be unique across the assembled configuration.

Jobs and executable DAG tasks accept pool (string, default null), poolSlots (integer, default 1), queuePriority (integer, default 0), and queueTimeout (finite positive float in seconds, default 3600). Slots must be positive and fit the named pool. Nondefault queue options require a pool. Approval gates reject pools. See resource pools.

failsWhen determines when a completed run is treated as a failure. In the strictyaml schema only producesStdout is a required key inside failsWhen. The others are optional. The DEFAULT_CONFIG defaults are:

jobs:
  - name: example
    command: echo "hi"
    schedule: "* * * * *"
    failsWhen:
      producesStdout: false
      producesStderr: true
      nonzeroReturn: true
      always: false

See failure detection and retries.

Three lifecycle hooks each carry a report block (mail, sentry, shell, webhook, push, eventlog); onFailure also carries a retry block. The report blocks all share the same _report_schema and the same _REPORT_DEFAULTS (deep-copied so the three blocks do not alias one another).

When a retry block is present, the strictyaml schema requires all four keys inside onFailure.retry: maximumRetries, initialDelay, maximumDelay, and backoffMultiplier. See failure detection and retries.

Reporting (mail, Sentry, shell, webhook) covers the report blocks in full; their schema and _REPORT_DEFAULTS are summarized here.

from and to are required keys (each EmptyNone() | Str). Defaults from _REPORT_DEFAULTS["mail"]:

Defaults from _REPORT_DEFAULTS["sentry"]:

Defaults from _REPORT_DEFAULTS["webhook"]:

The end-to-end encrypted push channel. Enabling it anywhere requires the daemon-global push: section (relay + device registry) and the push extra (PyNaCl); both requirements fail closed at config load. See push notifications.

Windows Event Log records, and a no-op on every other platform (the load warns once, naming each hook that enabled it). Needs no extra and no dependency. See Windows Event Log for the event-ID and insertion-string tables.

Per-job thresholds for the runs that did not happen, evaluated once per minute by the in-process monitor. A breach fires the onLate reporters once. The full semantics live on late-run detection; this is the schema summary.

If all three sla keys are unset, configuring an onLate reporter (a mail to/from, a sentry dsn, a shell command, a webhook url, or an enabled push or eventlog block) is a load-time ConfigError (onLate requires sla). Both keys merge normally under defaults: and are excluded from the job-set ID fingerprint, like the catch-up options. The monitor does not evaluate disabled and paused jobs.

These options build on the top-level state store and only take full effect when a state section is configured. Without one they parse and validate normally but change nothing. The one exception is onlyIfLastSucceeded, which also works without a state section from the in-memory history alone (the gate then resets on restart). See durable state for the full semantics.

jobs:
  - name: example
    command: env
    schedule: "* * * * *"
    env_file: .env
    environment:
      - key: PATH
        value: /bin:/usr/bin

See commands and environment.

This section is POSIX-only (the setuid/setgid model). On POSIX, setting user or group requires cronstable to run as root (euid 0); otherwise load raises a ConfigError. Privilege switching is not supported on Windows: a job with user or group set raises a configuration error, verbatim Job <name>: changing user/group is not supported on Windows. See production and container deployment and running on Windows.

Raising a priority (any level whose nice sits below cronstable's own; from the usual nice 0 that means above-normal and high) needs CAP_SYS_NICE or RLIMIT_NICE headroom on POSIX. The daemon says so once, at config load, naming the job. If the kernel then refuses the renice, cronstable does not fail the run. The job's processes keep the nice value they inherited, and the refusal is logged at DEBUG. Windows hands every one of these classes to an unprivileged account, so nothing is refused there.

On Linux, a nice value orders a job only against the processes in its CPU group. Under the packaged systemd unit, that group holds the system's services. A unit with Delegate=yes makes cronstable a group of its own. With the cpu controller delegated that way, each run is a group of its own while a job has a resourceLimits.cpu cap, and its CPU weight follows its priority, even when the kernel refuses the renice. That weight orders the run only against cronstable's other runs, within cronstable's own share. See priority and Linux CPU groups.

realtime is deliberately not on the list. On Windows that class outranks the threads that service disk, keyboard, and mouse, so a runaway job at REALTIME can put the host out of reach of the operator who has to stop it.

See commands and environment. Running on Windows shows how the levels line up with Task Scheduler's -Priority numbers.

Every cap accepts max in any letter case, which also lifts a cap inherited from defaults:. A bare resourceLimits: cannot clear an inherited map. The schema reads each cap as text, so a ${VAR} value follows the same rules as a literal; required is a boolean and takes no ${VAR}. An unreadable value is a ConfigError that names the key, such as Job <name>: resourceLimits.memory: cannot read '512X' as a size; .... Approval gates reject resourceLimits and ignore one inherited from defaults:.

On Linux the caps need cgroup v2 and a cgroup delegated to cronstable; the packaged systemd unit sets Delegate=memory pids and OOMPolicy=continue, and CPU caps need Delegate=yes in a drop-in. Windows needs no setup. macOS, the BSDs, and illumos cannot enforce caps, and each config load there logs one warning that names the capped jobs. Where the host cannot enforce a cap, the run goes ahead without it, its record says so, and the daemon logs one warning for each change. Full feature guide: resource limits.

See metrics with statsd. Prometheus metrics are not configured per job: the GET /metrics endpoint is global, tuned under web.metrics in the earlier web section. See metrics with Prometheus.

Resource accounting (monitorResources). With it on, a run is sampled by psutil (a core dependency) over its whole process tree, so a job that launches child processes through a shell is accounted too.

The result (total user/system CPU seconds and the peak RSS observed) appears in the dashboard run history and stats, in the durable run record's resources object (so it survives a restart), and as the metrics listed in metrics with Prometheus. Report templates and the shell reporter also receive cpu_seconds / max_rss_bytes (CRONSTABLE_CPU_SECONDS / CRONSTABLE_MAX_RSS_BYTES). This section covers the configuration surface; the full feature guide is resource monitoring.

DAG tasks accept monitorResources too, but surface the result differently: a finished task instance's usage is recorded in the resources object of its task record inside the durable dag_run document (returned by GET /dags/<name>/runs/<run_key>), and sent to the task's statsd sink when one is configured. DAG task instances are ephemeral and do not appear in the per-job Prometheus families on GET /metrics.

The numbers are sampled, so a run that finishes between two samples is measured approximately. The long, heavy runs whose resource use matters are sampled many times. It is best-effort: if psutil cannot read a process (already exited, permission denied), the run carries no resource stats, and monitoring never fails a job.

Sampling cadence and chart series. The map form controls how monitoring behaves:

monitorResources:
  interval: 0.5     # seconds between samples (default 1.0, minimum 0.1)
  history: 240      # chart points kept per run (default 240; 0 = summary only)

interval sets the process-tree polling cadence: shorter intervals catch sharper RSS spikes at the cost of more wakeups (each sample walks the process table, hence the 0.1s floor).

Alongside the summary numbers, each monitored run records a downsampled CPU%/RSS time series for the dashboard's Resources tab: one point per sample until history points accumulate, after which adjacent points merge (mean CPU%, peak RSS; spikes are never averaged away) and the effective resolution halves, so a run of any length stays within history points (at most 2000).

The series is embedded in the durable run record's resources.series, so charts survive restarts and are bounded by the same state.maxRunsPerJob retention as run records. It is served by GET /jobs/<name>/resources and deliberately excluded from the polled /jobs and /jobs/<name>/runs payloads.

The dashboard's node-level CPU/memory history chart is configured separately, under web.nodeHistory (see the web section): interval (Float seconds, default 5.0, minimum 1.0) and points (Int ring size, default 720, an hour at the default cadence), or nodeHistory: false to disable the background node sampler entirely.

strictyaml enforces only the type (Int/Float). After type validation, JobConfig._validate_numeric_ranges enforces value ranges (plus one cross-field rule) and raises a ConfigError (prefixed Job <name>:) on violation. JobConfig._validate_resource_limits checks the resourceLimits rows the same way after it reads each cap from its text. These checks run at load time, not at run time.

defaults:
  shell: /bin/bash   # POSIX path; on Windows omit shell (uses cmd.exe) or set a Windows interpreter
  utc: false

jobs:
  - name: nightly-backup
    command: /usr/local/bin/backup.sh
    schedule: "0 3 * * *"
    captureStdout: true
    captureStderr: true
    executionTimeout: 3600
    onFailure:
      retry:
        maximumRetries: 3
        initialDelay: 5
        maximumDelay: 60
        backoffMultiplier: 2