# RunWisp

> One small Go binary that replaces crond + supervisord: it schedules tasks and supervises long-running services, and persists every run's exit code, duration, timestamps, and captured stdout/stderr — browsable and streamable from an embedded Web UI, a TUI, and a REST API. Local-first, offline-complete, zero runtime deps. Every task is defined in a single runwisp.toml; the API and UI are read-only + trigger.

Every page below is served as Markdown if you send `Accept: text/markdown`, or if you append `.md` to the URL.

## Agent reference

- [RunWisp agent reference](https://docs.runwisp.com/agents/reference.md): Dense, token-optimized full reference — complete runwisp.toml schema, CLI, and REST surface, written for agents. Start here.

## Overview

- [RunWisp documentation](https://docs.runwisp.com/): RunWisp runs scheduled jobs and long-running services from one runwisp.toml and records every run with its exit code, duration, and output. One binary, no runtime dependencies.

## Getting started

- [Quick start](https://docs.runwisp.com/getting-started/quick-start/): Install RunWisp, create a starter runwisp.toml, run your first task, and open the Web UI.
- [Running in Docker](https://docs.runwisp.com/getting-started/docker/): Run the RunWisp daemon in a container with the official runwisp/runwisp image. Image tags, required settings, volumes, healthcheck, TLS, timezone, and running as non-root.
- [Web UI](https://docs.runwisp.com/getting-started/web-ui-tour/): A tour of the RunWisp Web UI. Logging in, the overview page, the runs list and its filters, task detail, the log viewer, and notifications.
- [TUI](https://docs.runwisp.com/getting-started/tui-tour/): A tour of the RunWisp terminal UI. Starting it, the Home, Info, and Debug pages, following a run, reading failures, and keyboard shortcuts.

## Guides

- [Tasks and services](https://docs.runwisp.com/concepts/tasks-vs-services/): The difference between a [tasks.*] and a [services.*] block, and how to pick one for commands that could be either.
- [Scheduling](https://docs.runwisp.com/concepts/scheduling/): Cron syntax, timezones and daylight saving time, catching up after downtime, missed-run alerts, jitter, pausing a schedule, and what happens to runs after a crash.
- [Overlapping runs](https://docs.runwisp.com/concepts/concurrency/): What happens when a task is started while it's already running, how to choose between queue, skip, and kill, and when to raise max_concurrent.
- [Failures, retries & timeouts](https://docs.runwisp.com/concepts/retries/): When a run counts as a failure, how to retry failed task runs with a delay and backoff, and how to stop runs that take too long.
- [Parameters](https://docs.runwisp.com/concepts/parameters/): Declare per-run inputs on a task with params and fill them in when you start it from the Web UI, TUI, CLI, or REST API.
- [Run logs](https://docs.runwisp.com/concepts/logs/): Where RunWisp keeps each run's output, how size limits and retention work, and how to follow, download, and search logs.
- [Notifications](https://docs.runwisp.com/notifications/): Get told when a task fails, in the bell or on Slack, Discord, Telegram, a phone push app, email, or a webhook. Add a channel, store its secret, choose which tasks alert where, and test it.
- [Slack](https://docs.runwisp.com/notifications/providers/slack/): Send RunWisp notifications to a Slack channel through an incoming webhook.
- [Discord](https://docs.runwisp.com/notifications/providers/discord/): Send RunWisp notifications to a Discord channel as color-coded embeds through a channel webhook.
- [Telegram](https://docs.runwisp.com/notifications/providers/telegram/): Send RunWisp notifications to a Telegram chat, group, or channel through a bot, including how to find the chat_id.
- [ntfy](https://docs.runwisp.com/notifications/providers/ntfy/): Send RunWisp notifications as phone push alerts through ntfy.sh or your own ntfy server.
- [Gotify](https://docs.runwisp.com/notifications/providers/gotify/): Send RunWisp notifications to your self-hosted Gotify server as push messages.
- [Pushover](https://docs.runwisp.com/notifications/providers/pushover/): Send RunWisp notifications to your phone through Pushover.
- [Email (SMTP)](https://docs.runwisp.com/notifications/providers/smtp/): Send RunWisp notifications by email through any SMTP server, with examples for Gmail, SendGrid, Amazon SES, Mailgun, Postmark, and a local Postfix.
- [Email (local MTA)](https://docs.runwisp.com/notifications/providers/sendmail/): Send RunWisp notifications through the machine's own sendmail binary (Postfix, exim, msmtp, ssmtp), the way cron sent MAILTO mail. No host, port, or password to configure.
- [Webhook](https://docs.runwisp.com/notifications/providers/webhook/): POST RunWisp notifications as JSON to any HTTP endpoint, with custom headers for authentication.
- [Docker tasks](https://docs.runwisp.com/recipes/docker/): Run containers from RunWisp tasks. One-shot containers, commands in a running compose service, image prefetch, pruning, and what RunWisp needs when it runs in a container itself.
- [Remote triggers](https://docs.runwisp.com/recipes/remote-trigger/): Run a RunWisp task on another machine from a script or CI and get its output and exit code back, with runwisp run --url or plain curl. Includes deploy hooks from CI.

## Examples

- [Nightly backup](https://docs.runwisp.com/recipes/backup/): A nightly Postgres backup with RunWisp: pg_dump on a schedule, 90 days of history, no overlap, and an alert when a run fails or is missed.
- [Health checks](https://docs.runwisp.com/recipes/healthcheck/): An HTTP health check every 5 minutes with RunWisp. Skips on overlap, retries short blips, and groups repeated alerts during an outage.

## Migrating from cron, supervisord, systemd, or docker-compose

- [Migrating to RunWisp](https://docs.runwisp.com/coming-from/): Move to RunWisp from cron, supervisord, systemd, or docker-compose. RunWisp reads or converts your existing config.
- [From cron](https://docs.runwisp.com/coming-from/cron/): Move cron jobs to RunWisp. Take over in one command with sudo runwisp takeover, or convert a crontab with runwisp import cron, then promote jobs into your own runwisp.toml.
- [From supervisord](https://docs.runwisp.com/coming-from/supervisord/): Convert a supervisord config into runwisp.toml with runwisp import supervisord. How each [program] key maps, and what needs a human.
- [From systemd](https://docs.runwisp.com/coming-from/systemd/): Convert systemd .service units into runwisp.toml with runwisp import systemd. How each directive maps, and what needs a human.
- [From docker-compose](https://docs.runwisp.com/coming-from/docker-compose/): Point RunWisp at an existing docker-compose.yml. Every compose service becomes a RunWisp service, without changing the YAML.

## Operations

- [Autostart](https://docs.runwisp.com/operations/autostart/): Start the RunWisp daemon on boot with systemd (Linux, WSL) or launchd (macOS). Install, check, stop and restart, set the password and environment, uninstall.
- [Reload & restart](https://docs.runwisp.com/operations/reload/): Apply runwisp.toml edits to a running daemon with runwisp reload or SIGHUP, and which changes need runwisp restart instead.
- [Authentication](https://docs.runwisp.com/operations/auth/): How the CLI, TUI, Web UI, and REST clients log in to RunWisp; setting the password; running without auth; rate limits; and reverse proxies.
- [Daemon log](https://docs.runwisp.com/operations/logging/): The RunWisp daemon's own stderr log (level, format, timestamps) and the one-line-per-run lifecycle entries it writes.
- [Metrics](https://docs.runwisp.com/operations/metrics/): Scrape RunWisp's OpenMetrics /metrics endpoint from Prometheus, Grafana Agent, or the OpenTelemetry Collector.
- [Troubleshooting](https://docs.runwisp.com/operations/troubleshooting/): Symptom-first fixes for common RunWisp problems. The daemon won't start, a task never fires, config edits aren't picked up, you're locked out, logs are missing, runs pile up, a service is FATAL, notifications don't arrive.

## Configuration reference

- [Configuration overview](https://docs.runwisp.com/configuration/overview/): How runwisp.toml is structured: tasks, services, compose, defaults, daemon, storage, and notifications.
- [[tasks.*]](https://docs.runwisp.com/configuration/tasks/): Every key accepted by a [tasks.<name>] table: cron, run, on_overlap, retries, timeout, retention, params, notifications.
- [[services.*]](https://docs.runwisp.com/configuration/services/): Long-running processes: instances, restarts, health checks, boot order, graceful shutdown, and the keys shared with tasks.
- [[compose.*]](https://docs.runwisp.com/configuration/compose/): Import services from a docker-compose.yml so every service becomes a RunWisp service with logs, restarts, notifications, and start/stop.
- [[defaults]](https://docs.runwisp.com/configuration/defaults/): Fallback values inherited by every task and service unless overridden: timeout, log limits, retention, restart policy, env, failures.
- [[daemon]](https://docs.runwisp.com/configuration/daemon/): Daemon-wide settings: shutdown_timeout, timezone, external_url, TLS, metrics, trusted proxies, include, and include_cron.
- [[storage]](https://docs.runwisp.com/configuration/storage/): max_size and min_free_space: the two daemon-wide disk limits that keep RunWisp from filling your partition.
- [[notify]](https://docs.runwisp.com/configuration/notify/): Daemon-wide notification settings: global_notifiers, retry_budget, bell history, and coalescing.
- [[[route]]](https://docs.runwisp.com/configuration/routes/): Notification rules: match run events by kind, failure, and task name, and send them to Slack, Discord, Telegram, ntfy, Gotify, Pushover, email, or a webhook.
- [${...} substitution](https://docs.runwisp.com/configuration/substitution/): Pull values from environment variables or files into any string in runwisp.toml with ${VAR} and ${file:path}.

## Reference

- [CLI reference](https://docs.runwisp.com/reference/cli/): Every runwisp command, flag, and environment variable.
- [AI agents](https://docs.runwisp.com/reference/agents/): What an AI coding agent needs to configure and run RunWisp. The llms.txt index, Markdown pages, the agent reference, the config schema, and the validate/run --json loop.

## Optional

- [runwisp.toml JSON Schema](https://docs.runwisp.com/config.schema.json): Machine-readable schema (draft 2020-12) for the config file; also `runwisp schema`. Editors read it via a `#:schema` directive.
- [OpenAPI schema](https://docs.runwisp.com/openapi.json): Full REST API specification (OpenAPI 3.1, JSON).