# RunWisp agent reference Dense reference for agents authoring/operating RunWisp. Human-readable prose lives at https://docs.runwisp.com (each page also at `.md`). This file is the schema/CLI/REST surface only. Notation in schema blocks: `key: type =default — note`. `=default` omitted means no default (unset). `dur` = Go duration string (`300ms`,`5s`,`10m`,`1h`); retention also accepts `d`/`w`. `size` = byte size (`100mb`,`2gb`). `req` = required. ## Model - `runwisp.toml` is the ONLY source of task definitions. REST/UI/TUI can read + trigger/stop/restart runs, never create or edit definitions. - Config reload is explicit: `runwisp reload` / `SIGHUP` / `POST /api/reload` re-read the whole TOML and reconcile the live task set (add/change/remove tasks, services, `[defaults]`). Validate-first/atomic — a parse/validation failure, or a change to a restart-only setting (`[daemon]`, `[scheduler] timezone`, `[storage]`, `[notify]`, bind host/port), is rejected and leaves the running set untouched. Reload is NOT a restart: added tasks get no `run_on_start`/catch-up, in-flight runs finish under their old definition. The daemon never auto-watches the file. Restart-only settings (and re-firing `run_on_start`/catch-up) need `runwisp restart`. - Two unit kinds: `[tasks.]` run-to-exit (cron or manual); `[services.]` long-running, `restart=always` forced. Names must be unique across both tables. `name` validated by RunWisp's task-name rules. - `run =` is shell, executed from disk only — never from an HTTP/WS body. - Inheritance: `[defaults]` → each task/service → per-key override. `env` merges (task wins); `[compose..]` overrides per imported service. - IDs are ULIDs. Logs are per-task files on disk; SQLite holds run metadata only. ## runwisp.toml Machine-readable JSON Schema (draft 2020-12): `runwisp schema` (offline) or https://docs.runwisp.com/config.schema.json. Scaffolded/imported configs carry a `#:schema` directive so editors validate them. After editing, `runwisp validate --json` reports errors with structured `key`/`line`/`column`. ### [scheduler] ``` timezone: IANA string =host system zone — TZ for cron eval when a task pins none ``` ### [storage] (daemon-wide log disk safeguards) ``` max_size: size =0(no cap) — hard cap on total log bytes across all tasks min_free_space: size =0(no check) — stop accepting log lines when partition free < this ``` ### [daemon] ``` allow_cloud_dispatch: bool =false — accept peer-dispatched ad-hoc shell/container/compose runs (opt-in; one-shot, never edits TOML; HTTP & existing-task triggers always allowed) shutdown_timeout: dur =10s — SIGTERM→SIGKILL drain budget for in-flight runs on shutdown external_url: string — public Web UI base for notification deep-links; absolute http(s) w/ host metrics_enabled: bool =false — master switch for /metrics metrics_listen: host:port — dedicated metrics listener; REQUIRES metrics_enabled=true include: []string — glob(s) of extra TOML files merged at load; root config only, no nesting ``` ### [defaults] (inherited by every task & service) ``` timeout: dur — per-attempt wall-clock cap; unset = no timeout (TASKS only) jitter: dur — start-spread window inherited by cron tasks; off when unset (TASKS only) shell: path =/bin/sh — interpreter for run scripts (absolute path) stop_signal: enum =SIGTERM — stop-ladder signal: SIGTERM|SIGINT|SIGQUIT|SIGHUP|SIGKILL|SIGUSR1|SIGUSR2 exit_codes: []int =[0] — exit codes treated as success (0..255) log_max_size: size =100mb — per-run log cap (effective task default) log_on_full: enum =drop_old — drop_new | drop_old | kill_task keep_runs: int — row-count retention; 1..1000000 keep_for: dur — age retention; positive healthy_after: dur =60s — service uptime that counts as healthy: resets the restart counter and clears the failed-start streak (SERVICES only) start_retries: int =3 — consecutive fast failures before an instance goes FATAL (SERVICES only) notify_on_missed: bool =true — alert on missed scheduled runs; false silences daemon-wide (per-task still wins) env: map — inline env merged into every task; key ^[A-Za-z_][A-Za-z0-9_]*$, <=256 entries, value <=32KiB, no NUL env_file: path — dotenv file merged into every task; relative to runwisp.toml dir secrets: map — inline secrets merged into every task; never shown in API/UI secrets_file: path — dotenv file merged beneath secrets; only the path is visible ``` ### [tasks.<name>] (run-to-exit) Required: the table + `run` (unless `compose_file`). `restart="always"` and `instances` are rejected on tasks (use `[services.*]`). ``` group: string =Tasks — UI grouping label description: string — human description cron: string — 5- or 6-field cron (optional leading seconds); also @hourly, @every 1h30m; omit => manual-only timezone: IANA string — per-task TZ override (else [scheduler] timezone) jitter: dur — cap how far this cron task's start may slip; needs cron (inherits [defaults]) run_on_start: bool =false — fire once at daemon start, on top of any cron (the @reboot equivalent) api_trigger: bool =true — allow CLI/API/UI trigger; false = cron-only catch_up: enum =latest — missed-firing policy: latest | all | skip max_catch_up_runs: int =100 — cap when catch_up=all; >=1 timeout: dur — per-attempt cap (inherits [defaults]) graceful_stop: dur =5s — grace before SIGKILL on stop stop_signal: enum =SIGTERM — stop-ladder signal (inherits [defaults]); SIGTERM|SIGINT|SIGQUIT|SIGHUP|SIGKILL|SIGUSR1|SIGUSR2 restart: enum — never | on_failure (always => rejected on tasks) max_concurrent: int =1 — concurrent run cap; 1..1024 queue_max: int =100 — queued-run depth; 0..10000 on_overlap: enum =queue — queue | skip | terminate retry_attempts: int =0 — retries after a failed attempt; 0..100 retry_delay: dur =5s — delay between retries (<=0 floors to 5s) retry_backoff: enum — constant | linear | exponential exit_codes: []int =[0] — exit codes treated as success (inherits [defaults]); 0..255 working_dir: path — process cwd; relative to runwisp.toml dir, ~ expands (else daemon cwd) shell: path =/bin/sh — interpreter for run (absolute path); invoked as -c