Project
Monocron
A self-hosted scheduler for tasks on VMs, bare metal, and container environments.
A scheduler for machines you own and jobs you need to trust.
What it is
Monocron is a self-hosted task scheduler for VMs, bare metal, and container environments. It is built around a controller, runner, local daemon, and operator CLI, so schedules can be managed centrally while jobs execute on the machines that actually own the work.
The project started from a simple idea: cron is useful, but operating many hosts needs more structure than scattered crontabs. Monocron gives schedules a control plane, runner enrollment, labels, logs, and a way to inspect executions from one place.
The pieces
- monocron-controller stores desired state, runners, schedules, audit logs, and the public API.
- monocron-runner enrolls a host with the controller, reconciles assignments, and reports status over outbound HTTPS.
- monocrond runs locally on the host and executes commands through a protected Unix socket.
- monocronctl is the administrative CLI for operators.
Why the architecture is split
The split keeps control and execution separate. The controller decides what should run. The runner receives assignments and reports back. The daemon owns local scheduling and process execution. That means runner hosts only need outbound access to the controller, while job execution stays close to the machine and its local environment.
It also makes the failure modes easier to reason about. If the control plane is down, a host-local daemon can still be treated as a separate execution boundary. If a runner cannot reach the controller, the issue is isolated to reconciliation instead of job process management.
Operator flow
An operator installs the controller, logs in with monocronctl, creates an enrollment token, joins a runner host, then creates schedules with labels that match eligible runners.
monocronctl runner token zone=home os=linux
monocronctl schedule create backup "0 2 * * *" 10m /usr/local/bin/backup.sh zone=home
monocronctl execution list
monocronctl execution logs <execution-id>What I focused on
Monocron is mostly a systems-design project: APIs, placement, host agents, process execution, migrations, release scripts, and operational docs. The interesting part is not just making a command run on a schedule. It is giving the schedule a durable model that can work across many machines without making every host expose itself publicly.