koku (刻)

A cron daemon written in Rust. Single binary that manages and runs scheduled jobs.

Install

just install

This builds a release binary and symlinks ku as an alias.

Quick start

ku init                  # scaffold ~/.config/koku/config.toml
ku check                 # validate config, preview schedule
ku daemon start          # start the daemon
ku status                # view job states

Config

~/.config/koku/config.toml

[[job]]
name = "backup"
cron = "0 2 * * *"
command = "bash backup.sh"
dir = "/home/user/scripts"
on_error = "backoff"      # continue | backoff | stop (default: continue)
overlap = false           # allow concurrent runs (default: false)
timeout = "30m"           # kill after duration (optional)

[[job]]
name = "cleanup"
cron = "*/15 * * * *"
command = "python3 cleanup.py"

Error policies

• continue — ignore failures, keep scheduling (default)
• backoff — exponential backoff on failure (2^n seconds, capped at ~17 min)
• stop — disable after 3 consecutive failures, requires ku resume

CLI

ku init              scaffold config with examples
ku check             validate config, preview next-run times
ku daemon start      start daemon in background
ku daemon stop       stop daemon
ku daemon run        run daemon in foreground
ku status            table of all jobs with state/timing
ku status --json     machine-readable output
ku run <name>        trigger one-off run
ku pause <name>      pause a job
ku resume <name>     resume a paused/stopped job
ku reload            reload config without restarting

Web dashboard

Use kagaya (ky serve) for a web UI. kagaya connects to koku's Unix socket and provides cron status, one-off runs, and pause/resume from the browser.

Dependencies

• muzan — daemon lifecycle (Unix socket IPC, PID management)
• croner — cron expression parsing
• tokio — async runtime