runwisp

RunWisp

See what ran, when, why it failed, and what it printed.

RunWisp is an open-source, self-hosted cron job manager and process supervisor. It ships as a single Go binary with a built-in web dashboard, terminal UI, and REST API.

runwisp.com · Documentation · Install · Quick Start · Compare

RunWisp replaces crond and supervisord when you want scheduled jobs and long-running services in one place. You describe both in runwisp.toml; the daemon runs them without needing Python, Node.js or an external database.

Want a look first? Run bunx runwisp demo to try RunWisp with demo data and nothing to configure.

Every run leaves evidence behind: its exit code, duration, timestamps, and stdout/stderr. You can inspect history, follow logs, and trigger or stop tasks from the web dashboard, terminal UI, or REST API. Task definitions stay on disk in TOML.

Trigger a run, follow its output, and inspect failures from the built-in dashboard.

Install

Install the latest binary on your PATH:

curl -fsSL https://get.runwisp.com | sh

On macOS or Linux with Homebrew:

brew install runwisp/tap/runwisp

You can also use the npm package, which runs the prebuilt Go binary:

bunx runwisp
bun add -g runwisp     # or: npm install -g runwisp

Tarballs are available from runwisp.com/releases. For Docker:

docker run -d --name runwisp -p 9477:9477 \
  -e RUNWISP_PASSWORD=change-me \
  -v ./runwisp:/etc/runwisp \
  -v runwisp-data:/var/lib/runwisp \
  runwisp/runwisp:latest

On first start, RunWisp writes a starter config to ./runwisp/runwisp.toml. The image supports amd64 and arm64, with Alpine and Debian variants. See the Docker guide for tags, environment variables, and volumes.

To build from source, see Getting started in the contributing guide.

Quick Start

Run:

runwisp

If the current directory has no runwisp.toml, RunWisp offers to create an example config file. Press Enter and it will write an example task, start the daemon, and open the terminal UI. The Home page shows the web dashboard URL and a generated password; press Enter on the password row to copy it.

Set RUNWISP_PASSWORD env variable if you want to choose the password yourself. For a trusted local setup, RUNWISP_AUTH=off disables authentication explicitly.

Running headless? Use runwisp daemon in cron, systemd, Docker, CI, or a piped SSH session. It doesn't prompt, and a missing config exits non-zero. To start RunWisp after a reboot, use runwisp service install for systemd or launchd.

Replace the starter task with your own jobs and services:

[tasks.backup-db]
cron       = "0 2 * * *"
jitter     = "30m"  # delay by up to 30 mins if other jobs are running
on_overlap = "kill" # if yesterday's job is still running, kill it
keep_runs  = 30     # remove older runs
run = "pg_dump mydb | gzip > /backups/mydb-$(date +%F).sql.gz"

[services.worker]
instances    = 3                           # keep three copies running
env          = { NODE_ENV = "production" } # shown in API/UI
secrets_file = "/etc/runwisp/worker.env"   # never leaked to the API/UI
run          = "node /app/worker.js"

Moving from cron, supervisord, or Docker Compose

RunWisp can start from the configuration you already have:

• Take over from cron.
• Import crontab.
• Import supervisord
• Import docker compose.

The terminal UI keeps task status, logs, history, and controls in the SSH session.

Features

Scheduling and supervision

• Standard cron schedules, missed-run handling, retries, timeouts, and queue, skip, or kill overlap policies
• Long-running services with multiple instances, restart backoff, crash recovery, and graceful shutdown. 500k lines/day, for months without interruption, RunWisp can handle it and stream it to you.
• Typed parameters for manual runs, passed as arguments or environment variables through UI/API/CLI

Run history and logs

• Exit code, duration, timestamps, and status persisted in embedded SQLite
• Live stdout/stderr streaming in the web UI and terminal UI
• Per-task log rotation and failure notifications through Slack, Discord, Telegram, ntfy, Gotify, Pushover, email, webhooks, or the in-app inbox

Day-to-day operation

• One binary with the Svelte web dashboard and SQLite embedded
• TOML configuration that can be versioned and reviewed like code
• Validate-first reloads, recoverable state after a crash or power loss, and interrupted-run reporting on restart
• Local-first operation with no signup, account, or required network connection. The only outbound call by default is an anonymous update check, turned off with check_updates = false

Comparison

The API and user interfaces can inspect tasks and trigger or stop them. Task definitions cannot be modified remotely. runwisp.toml remains the source of truth.

Links

• Documentation — installation, configuration, REST API, and operations
• Changelog — recent changes and version history
• Contributing — development setup and contribution guidelines
• Security policy — responsible disclosure
• Issue tracker — bug reports and feature requests

How RunWisp is made

RunWisp is built by PoppyCake, s.r.o. Most of the code isn't written by hand, so we lean hard on review and tests. Review goes down to the small stuff, like whether a helper deserves to exist or should just be three lines inline, because that's how the code stays small and quick to read. The daemon has more lines of tests than code, including awkward cases like a daily job scheduled inside the hour that daylight saving skips.

Careful review and good tests still aren't a guarantee. If we missed something, open an issue and we'll fix it.

Richard Popelis, lead developer

License

The RunWisp daemon and web UI are licensed under GPL-3.0-or-later. Basically, do what you want but if you distribute a modified version, you must keep it open under the same license. See LICENSE.

Shared libraries under packages/ use Apache-2.0 instead. See LICENSE-APACHE and the license file in each package.