Croniq
Distributed cron that just works. Single binary. SQLite default. Production-ready retries.
Reliable distributed job scheduling with built-in retries, calendar-aware scheduling, a Vue dashboard, and an AI-native MCP server. Deploy as a single binary or Docker container — no cluster required.
Full API documentation: openapi.yaml
Why Croniq?
| Problem | Croniq |
|---|
| Cron jobs fail silently — nobody notices for days | Dead letter queue, execution logs, Prometheus metrics, failure notification hooks |
| Single server = single point of failure | Pull-based runner protocol — scale runners independently |
| No retries, no backoff, no timeout | Exponential, linear, fixed retry with jitter. Per-job timeout enforcement |
| Most schedulers need a cluster just to get started | Single binary, SQLite by default, Docker one-liner |
| Timezone and DST edge cases break everything | Per-job timezone, calendar system with business day rules |
| Teams can't self-service their own schedules | Hybrid model: Croniqfile DSL for ops, REST API + Runner SDK for developers |
Who Is It For?
- Small-to-mid engineering teams running 20–200 scheduled jobs without a platform team
- DevOps/SRE teams replacing fragile crontabs with something observable
- Self-hosters who want a single Docker container with a dashboard
Key Features
Croniqfile DSL — human-readable scheduling configuration. Includes parser, compiler, formatter, validator, and crontab migration tool.
Hybrid job registration — define jobs in the Croniqfile (infrastructure-as-code) or register them dynamically via REST API and Runner SDK. Both coexist; Croniqfile takes precedence on conflicts.
Pull-based runner protocol — runners poll for work via HTTP long-poll. Scale runners independently. Built-in capability routing, instance guard, and lease renewal.
Calendar system — include/exclude rules for weekdays, holidays, annual dates, and time windows. Jobs fire only when the calendar allows. Each calendar declares its own timezone, so one shared calendar means the same thing to every job that references it, whatever zone that job runs in.
Retry + dead letter — exponential, linear, or fixed backoff with jitter. Failed executions go to a dead letter queue for inspection and one-click replay.
Execution modes — queued (default) persists every execution with full retry and restart recovery. ephemeral skips persistence for high-frequency fire-and-forget jobs. Configurable per-job or globally in defaults {}. After a restart a job resumes its schedule, and a fire missed while the server was down runs once; an explicit catch_up all replays every missed fire (up to the queue depth), catch_up none skips them. Queue TTL and per-job depth limits prevent runaway backlogs.
Deploy-time reconciliation — run_on_register fires a job once when croniq adopts its definition: the first time the key is seen, and again whenever the compiled job changes. Closes the blind window between a deploy that changes what a reconciling job has to do and that job's next scheduled fire, without firing on every restart or --watch save. Gated jobs defer to their next permitted instant rather than skipping.
Auth — JWT tokens, API keys, and password authentication. Per-scope authorization is enforced on every endpoint: a token must carry the matching scope (e.g. jobs:write, dead-letters:write, runners:read) or the wildcard admin scope. See Scopes below.
Vue dashboard — login, jobs CRUD with live scheduling, runners with status badges, executions with log viewer + one-click cancel, dead letter detail panel, and a Live Console that tails the server's tracing stream in real time (admin-only, server-sent events, level filters, scroll-lock, copy + .ndjson download).
MCP server — 31 tools for AI assistant integration. Full CRUD over jobs, schedules, calendars, dead letters; queue observability; live forecast and execution log access — all from Claude, Cursor, or any MCP client. Available over stdio (croniq-mcp) or HTTP at /mcp on the running server. JWT-scoped: mcp:read for any tool, mcp:write for the 17 mutation tools; admin is a wildcard. Toggle via Croniqfile mcp { enabled false }.
Failure alerts — declare named channels + rules in the Croniqfile alerts { … } block. Six triggers ship: job_failed (permanent failure: dead-letter or drop — min_consecutive N waits for the Nth failed run in a row), job_recovered (the success that ends a streak of failed runs), job_sla_missed (in-flight execution exceeded its expected_within), job_missed_fire (a scheduled fire never happened — next_fire_at overdue past the expected_within grace, catching a silently-stalled scheduler that a green success-rate would otherwise hide), job_blocked (a fire has waited in the queue, undispatched, longer than expected_within — typically behind a singleton slot whose run does not finish; the alert names the claim holding it), and maintenance_active (maintenance mode has stayed on longer than expected_within — see Maintenance mode). The three liveness triggers stand down while maintenance is on. Each match is throttled per (rule, job_key), dispatched to the configured channels, and recorded in a persistent delivery log. CRONIQ_ON_FAILURE_CMD still works for one release as a back-compat shortcut.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
