Docs

Everything OpenRoutine does is driven by two plain-text files: a *.cron.md task you own, and a config.toml that says where to look and what an agent is.

• Install
• First five minutes
• Task files
• Configuration
• CLI reference
• REST API
• Deployment
• Concepts

Install

Requires a Rust toolchain; macOS and Linux only. Windows is an explicit non-goal.

git clone https://github.com/soulmachine/openroutine
cd openroutine
cargo install --path .       # or: cargo build --release
openroutine init .           # writes a config and a sample task
openroutine list             # see what would run
openroutine serve            # run the scheduler in the foreground
openroutine install          # or register it as a boot service, no sudo

init writes ~/.config/openroutine/config.toml, registers the directory you name, and leaves a sample hello.cron.md beside it. Nothing else to configure.

First five minutes

What openroutine init prints, and what to do with it.

Wrote config …/config.toml
Wrote sample task …/hello.cron.md

Try:  openroutine list                  # what would run
      openroutine run hello --dry-run   # what it would do
      openroutine serve                 # start the scheduler

Nothing fires until a daemon is running. `openroutine install`
registers one with your service manager, without sudo.

run --dry-run is the one to reach for first. It renders the fully resolved execution plan — command line, environment, working directory, upcoming fire times — without spawning anything. It is a read, not a run; nothing is recorded.

Task files

A task is a single *.cron.md file. The frontmatter is the metadata, the body is the prompt, and the file is the complete definition. Its identity is <project>/<filename stem> — renaming or moving the file creates a new task.

---
description: Say hello, nightly
cron: "0 9 * * *"
---

Say hello, then stop. This is a sample task — edit or delete it.

Frontmatter keys

Durations accept 30s, 5m, 2h, 1d, or a bare number of seconds.

A task with neither cron nor at is Manual — it runs only when fired, from the API or the UI.

on_failure and tz are declared in the v1 schema but not yet honoured. OpenRoutine warns about them by name rather than calling them unknown keys, because a key that silently does nothing is the worst outcome.

Configuration

Human-owned and hand-editable, at ~/.config/openroutine/config.toml. This is what openroutine init writes:

# openroutine — https://openroutine.dev

# The agent a task gets when it names none.
default_agent = "claude"

# Directories whose *.cron.md files should be scheduled.
[[projects]]
path = "/Users/you/tasks"

# An agent is a command template. {prompt} is substituted as a
# single argument; without it, the prompt arrives on stdin.
[agents.claude]
cmd = "claude -p {prompt}"

[agents.codex]
cmd = "codex exec {prompt}"

Keys

Run state — last run time, the tick it was scheduled for, recorded skips, pause toggles — is machine-owned and lives in a scheduled-tasks.json outside your repo. Delete it and you lose run history, not tasks.

CLI reference

openroutine --help for the same list. A global --config <PATH> overrides the XDG config path on any command.

REST API

The daemon listens on 127.0.0.1:7373, guarded by a bearer token from openroutine token.

curl -X POST http://127.0.0.1:7373/v1/tasks/myrepo/todo-digest/fire \
  -H "Authorization: Bearer $(openroutine token)" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod."}'

The optional text reaches the agent labelled as caller-supplied context, not as instructions — anyone who can reach the endpoint can send text, so text must not be able to redefine the task.

Endpoints

Deployment

To leave the daemon running unattended on a machine you don’t sit at — the Mac mini under the desk, a home server — register it with the system’s service manager.

cargo install --path .        # install to a stable path; see below
openroutine init ~/tasks      # config, and a sample task to prove it works
openroutine install           # register with launchd/systemd, no sudo
openroutine status            # daemon: running (pid …)

install records the path of the binary that registers it, so run it from the installed copy rather than from target/release/openroutine — a cargo clean should not be able to unmake your scheduler. It writes a per-user service and never asks for sudo. openroutine install --print shows exactly what it would write, and what it would run, without writing anything.

Your agent must be on the login shell’s PATH

The daemon runs every agent through a login shell, so a run gets the same PATH, shims, and API keys your terminal has. A login shell is not an interactive one: zsh reads .zshenv and .zprofile but not .zshrc, and bash reads .bash_profile but not .bashrc. So an agent that only your .zshrc puts on the PATH — anything in ~/.local/bin is the usual case — is found when you test by hand and missing once launchd starts the daemon:

zsh:1: command not found: claude

openroutine list warns before you get there. It samples the login shell the way a service manager starts one — with PATH seeded to the bare /usr/bin:/bin:/usr/sbin:/sbin a daemon inherits, never the PATH your terminal happens to have — so it answers for the daemon rather than for you:

warning: "claude" is on your PATH here but not under a service manager, so
scheduled Runs will fail; move its PATH export into your login profile

Fix it by moving the PATH export into .zprofile, which repairs SSH and cron sessions at the same time, or by naming the agent absolutely:

[agents.claude]
cmd = "/Users/you/.local/bin/claude -p {prompt}"

Verify the way the daemon will see it — a login shell with none of your terminal’s inherited environment:

env -i HOME="$HOME" SHELL=/bin/zsh PATH=/usr/bin:/bin /bin/zsh -lc 'command -v claude'

macOS

install writes a LaunchAgent to ~/Library/LaunchAgents/, so the daemon starts at login rather than at boot, and launchd restarts it if it dies. On a headless machine, pair it with auto-login (System Settings → Users & Groups → Automatically log in as), which requires FileVault to be off.

Auto-login is not only about the daemon starting. Agent CLIs keep credentials in your login keychain, and that keychain is unlocked by the GUI login — a service that starts without one finds it locked, and the agent reports itself logged out. That is also why install does not write a root LaunchDaemon: starting before anyone logs in is precisely the state in which the agent cannot authenticate, so the one thing a LaunchDaemon buys is the one thing that breaks it. The trade runs the other way too, and it is a real one: auto-login with FileVault off means physical access is a logged-in desktop.

While you are there, stop the machine sleeping through its own schedules:

sudo pmset -c sleep 0 displaysleep 0 disksleep 0  # never sleep
sudo pmset -c autorestart 1 womp 1                # return after power loss
launchctl print gui/$(id -u)/dev.openroutine.daemon | grep state

Linux

install writes a systemd user unit and enables lingering, so the daemon starts at boot with no login session — the one platform where “no login needed” holds without an asterisk.

systemctl --user status dev.openroutine.daemon
journalctl --user -u dev.openroutine.daemon -f

Confirming it survives

openroutine run <task>   # a real run, end to end
openroutine logs <task>  # what the agent actually printed

Killing the daemon outright is a fair test: the service manager should bring it back within seconds under a new pid. openroutine uninstall unregisters it and leaves your config, state, and tasks untouched.

Concepts

The vocabulary the CLI, the UI, and the docs all use. Precision here is deliberate — most of these terms have a near-synonym that means something subtly different.