koi

README

Koi

Koi is a drop-in replacement for cron with a hosted dashboard for easy monitoring, rich output history, and manual script execution with automatic GUIs for your least tech-savvy coworkers.

This is the client-side software that acts identically to cron, but can connect to koi.org's dashboard APIs.

How to use

Run koitab -e to edit your jobs using standard crontab syntax, as seen below. In addition, jobs can have the @manual dashboard trigger rather than a scheduled time.

*/5 * * * * /usr/local/bin/crawl
@hourly python script.py
@manual ~/tweet.sh

Run koitab -d new once to create a private dashboard. Now these jobs and their output history can be viewed online, and the tweet.sh job can be run from the dashboard. Koitab syntax also includes naming jobs, job sections, and manual job arguments to be filled in when running from the dashboard.

[Bots]
"Crawler" */5 * * * * /usr/local/bin/crawl
"Script" @hourly python script.py

[Admin]
"Say Hi" @manual ~/tweet.sh {{To Handle}} {{Delay, int, 0}} {{Emoji 😃, bool}}

Job arguments are written in the format {{name, type, default value}}. Types are string (default), int, and bool.

Manual job execution security

Dashboard passwords aren't sent to koi.org. They locally generate two keys: an API key and a "run key". The API key is sent to koi.org when the dashboard is created to enable access. The run key is only stored locally, and used to ensure that any manually run jobs are authentically created.

When a user clicks "run" on a manual job in their koi dashboard, the job's "tag" identifier, a unique timestamp, and any filled out argument values are bundled into a JSON string. A hash is locally generated from these values plus the user's secret run key. This JSON string and the hash are sent to the koi.org dashboard queue.

The client-side koid daemon polls the koi.org API every second to see if any manual jobs are in the queue. If so, it checks that a job matching that tag exists locally in the user's koitab. It also checks that the hash matches the expected value. A rogue koi.org could not modify any arguments or other parameters without the hash no longer being accurate.

It will then run the job exactly as it's definied locally as an sh command. If the local job has arguments to be filled out, the values taken from the queue are escaped before being applied. See this code in the koid/main.go function jobCommandFillArgs. In short, o'brien becomes 'o'\''brien'.

Installing

Linux and MacOS/Darwin support. Install by running:

curl -s https://get.koi.org | sh

Or to install from source follow these steps.

1. Create these necessary files

   mkdir /var/lib/koi
   touch /var/lib/koi/koitab /var/lib/koi/apikey /var/lib/koi/runkey /var/lib/koi/user
   chmod 666 /var/lib/koi/koitab /var/lib/koi/apikey /var/lib/koi/runkey /var/lib/koi/user
   whoami > /var/lib/koi/user # user that runs koi jobs, best avoid sudo/root
   

2. Build the koid and koitab binaries

   go build -o koid/koid ./koid
   go build -o koitab/koitab ./koitab
   

3. That's it. You may place the binaries somewhere in your PATH and use systemd or launchd to always run the koid daemon on startup. See https://get.koi.org/

WARNING

Koi is in early development! I'd love if you tried it out and shared your feedback with me, but please don't use it on sensitive/production servers.