Skip to content
RunWisp

Reload

You edited runwisp.toml — added a task, tweaked a cron, dropped one you don’t need anymore. You don’t have to restart the whole daemon to pick that up. A reload re-reads runwisp.toml and reconciles the running task set against it: new tasks start being scheduled, removed tasks stop, and changed tasks swap to their new definition.

You can trigger one from any surface:

The Web UI is read-only and never reloads config itself. When the runwisp.toml on disk drifts from what the daemon is running, a banner appears pointing you at runwisp reload — run that from a shell and the banner clears on the next refresh.

Reload is always explicit. RunWisp never watches the file and reloads on its own; it does exactly what you ask, when you ask.

Validate-first, all-or-nothing

Section titled “Validate-first, all-or-nothing”

Before touching anything live, RunWisp loads and validates the whole new config. If it doesn’t parse, fails validation, or changes a setting that can’t be reloaded (see below), the reload is rejected and your running task set is left exactly as it was — no half-applied state.

Terminal window
$ runwisp reload
Error: reload rejected: [storage] changed; requires `runwisp restart`

So a typo in runwisp.toml can’t take your scheduler down. Fix it, reload again.

What reloads live, and what needs a restart

Section titled “What reloads live, and what needs a restart”

Most of your day-to-day edits reload cleanly:

  • Adding, removing, and changing tasks and services — new commands, cron expressions, environment, instance counts, concurrency and retry policies.
  • [defaults] — because defaults are merged into each task before the comparison, changing a default shows up as a change on every task it touches.

A few daemon-wide settings can’t be swapped under a running process. Changing any of these is rejected and asks you to run runwisp restart:

  • [daemon] — shutdown timeout, external URL, metrics, cloud dispatch
  • [scheduler] timezone
  • [storage]
  • [notify]

The HTTP bind host and port aren’t config at all — they’re CLI flags — so they can only change on a fresh start.

Moving a task between files usually isn’t a change

Section titled “Moving a task between files usually isn’t a change”

runwisp promote moves a task’s definition into your runwisp.toml — out of the staging file an import wrote (runwisp.d/imported.toml), or out of a live crontab. Promote a staged task, or a cron task you’d already taken over from cron, and a reload after it reports no task changes, which is the honest answer: the schedule, the command, the environment — none of it moved. Only the file did.

That’s deliberate rather than a rounding error. A promoted service keeps running instead of being recycled, and such a cron task keeps its place in the schedule. The only thing the reload updates is the provenance the UI, TUI and --json report, which is why runwisp promote --reload exists as a shorthand.

The one exception is promoting a job while its cron daemon is still live. RunWisp had been holding that job — standing down so cron alone ran it — and promote comments the crontab line out, so on the next load the job is native and no longer held. That is a change: the reload reports it as a changed task and RunWisp takes over scheduling it. See Graduating a job.

What a reload tells you

Section titled “What a reload tells you”

runwisp reload prints the diff it applied — what was added, changed, and removed — and then any warnings the newly-live config carries, each on a ! line. The most common of those is a crontab job include_cron couldn’t schedule: it names the file and line so you can go fix it.

That’s deliberately not part of the diff. A job that stopped being schedulable doesn’t show up as a task change — from the task set’s point of view it simply isn’t there — so a reload after a bad crontab -e would otherwise report “no task changes” and leave you thinking it worked. The same warnings appear in runwisp status, in /api/info (so the UI and TUI header can show them), and in runwisp validate before you deploy at all.

A reload also re-checks whether a system cron daemon is still alive, so the jobs it was holding become RunWisp’s on the spot. You don’t have to reload for that, though — the daemon re-checks on its own about once a minute either way. Reloading after you retire cron just makes the handover immediate.

Reload is not a restart

Section titled “Reload is not a restart”

A couple of boot-only behaviors deliberately don’t fire on reload:

  • A newly added task does not run its run_on_start command, and it is not caught up for ticks it “missed” before it existed. It simply starts scheduling from now.
  • An in-flight run keeps running under the definition it started with. Removing or changing a cron task never kills a run that’s already going — it finishes, and only the next firing uses the new definition. Removed services are the exception: their instances are stopped, since the whole point is to take them down.

If you want the full boot path — run_on_start, missed-run catch-up, a fresh read of the restart-only settings — use runwisp restart instead.