﻿Every key a `[tasks.<name>]` block accepts, with its type, default, and accepted
values. Unset keys fall back to [`[defaults]`](/configuration/defaults/), then a
built-in default.

```bash
runwisp validate   # validate runwisp.toml and print a summary, or a structured error
runwisp schema     # print the full runwisp.toml JSON Schema (draft 2020-12) to stdout
```

## Identity & metadata

### `[tasks.<name>]`

**type**: `string` **required**

The text after `tasks.` is the task's name: `[tasks.backup-db]` is a task
called `backup-db`. The name is used in the Web UI, TUI, API, CLI, and log
directory.

- Letters, digits, and `. _ - :`, up to 100 characters.
- Must be unique across `[tasks.*]` and [`[services.*]`](/configuration/services/).
- A name with `.` or `:` must be quoted (`[tasks."db:backup"]`).

```toml title="runwisp.toml"
[tasks.backup-db]
run = "pg_dump app | gzip > /backups/app.sql.gz"

[tasks."db:backup"]  # quotes required: not a bare TOML key
run = "..."
```

### run

**type**: `string` **required** (unless [`compose_file`](/configuration/tasks/#compose_file) or [`sdk`](/configuration/tasks/#sdk) is set)

The shell command to run. It runs as `/bin/sh -e -c <command>`, so the first
failing command stops the run and its exit code becomes the run's exit code
(see [Fail-fast](/configuration/tasks/#fail-fast)). Set [`shell`](/configuration/tasks/#shell) to
bash for arrays or `pipefail`.

With [`compose_file`](/configuration/tasks/#compose_file), `run` is optional: it runs your command in
the service's container (see [`compose_mode`](/configuration/tasks/#compose_mode)).

```toml title="runwisp.toml"
[tasks.backup-db]
run = "pg_dump app | gzip > /backups/app.sql.gz"
```

Examples:

- `/usr/local/bin/backup.sh`: a script on disk
- `pg_dump app | gzip > /backups/app.sql.gz`: a shell pipeline
- `make -C /srv/app deploy`: any command on your `PATH`

### sdk

**type**: `boolean` **default**: `false` **since**: `1.7`

Runs the unit in the app that defines it through an [SDK](/sdk/), instead of a
shell command. The SDK sets it for you on every task and service you define in
code. The app's callback gets the unit's `env`, `secrets` and
[params](/configuration/tasks/#params), and what it prints becomes the run's
log.

A unit with `sdk` can't also set `run`, `compose_file`, `shell`, `umask`,
`user`, `env_base`, `working_dir` or `stop_signal`. If no app is connected when
the unit fires, the run waits up to 10 seconds for one, then fails. See
[When the app stops](/sdk/javascript/#when-the-app-stops).

### description

**type**: `string`

A short text shown in the Web UI and TUI. It doesn't change how anything runs.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
description = "Nightly Postgres dump to S3"
```

### group

**type**: `string` **default**: `"Tasks"`

The sidebar section it is listed under in the Web UI and TUI. Entries with the
same group are listed together.

```toml title="runwisp.toml"
[tasks.weekly-report]
# ...
group = "Reports"
```

### manual_trigger

**type**: `boolean` **default**: `true`

Whether operators can start, stop, or restart it by hand, and
[pause its schedule](/concepts/scheduling/#pausing-a-schedule). Set `false` to
lock it to its schedule (or, on a service, to supervisor-only restarts):
`runwisp start`/`stop`/`restart`/`pause` and the REST API return 403, the Web UI
hides its controls, the station trigger is refused.
[Hooks](/operations/auth/#hooks) still work.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
manual_trigger = false
```

### hook_tokens

**type**: `array of strings or tables` **since**: `1.2`

Tokens that let CI or a webhook control this unit over a
[hook](/operations/auth/#hooks) without the dashboard password. Each token works
for this unit only. Load them with `${VAR}` or `${file:...}` so they stay out of
the file. Tokens are never shown in the API or Web UI.

```toml title="runwisp.toml"
[tasks.deploy]
run         = "./deploy.sh"
hook_tokens = [
  "${CI_DEPLOY_TOKEN}",                                  # every action
  { token = "${ROLLBACK_TOKEN}", allow = ["stop"] },     # stop only
]
```

A plain string allows every action. A table with `allow` limits the token to
the listed actions: `run`, `start`, `stop`, `restart` (services have no `run`).

Each token needs at least 32 characters and no whitespace. Generate one with
`openssl rand -hex 32`. List more than one to rotate without downtime, or to
give each caller its own. [`manual_trigger`](/configuration/tasks/#manual_trigger) doesn't apply to
hooks.

## Scheduling

### cron

**type**: `string`

When the task runs, as a cron expression. Without it, the task runs only when
started by hand. Accepts 5 fields (`min hour day month weekday`), 6 fields with
a leading seconds field, or an `@` shorthand.

```toml title="runwisp.toml"
[tasks.healthcheck]
cron = "*/30 * * * * *" # every 30s, aligned to :00 and :30
run  = "curl -fsS http://localhost:8080/healthz"
```

Possible values:

- `*/5 * * * *`: every 5 minutes
- `0 3 * * *`: every day at 03:00
- `0 9 * * 1-5`: 09:00 Monday to Friday
- `0 0 L * *`: midnight on the last day of every month
- `*/30 * * * * *`: every 30 seconds (6-field, leading seconds)
- `@hourly`, `@daily`: shorthand forms
- `@every 1h30m`: fixed interval, ignores wall-clock alignment. The interval
  is a whole number of seconds, at least `1s`.

[How scheduling works](/concepts/scheduling/) has the full cron grammar, DST
rules, and catch-up details. `runwisp validate` runs the same checks as daemon
startup, so it catches a bad cron expression before you deploy.

### run_on_start

**type**: `boolean` or `enum` **default**: `false`

Run the task once at startup. This is separate from [`cron`](#cron) and
[`catch_up`](#catch_up).

```toml title="runwisp.toml"
[tasks.warm-cache]
run_on_start = true
run          = "/usr/local/bin/warm-cache"

[tasks.start-tunnel]
run_on_start = "boot"
run          = "/usr/local/bin/start-tunnel"
```

Possible values:

- `false`: don't run at startup
- `true` or `"daemon"`: run every time the daemon starts, including after
  `runwisp restart` and updates
- `"boot"`: run once per machine boot, like cron's `@reboot`. Restarting the
  daemon doesn't run it again until the next boot. In a container, each
  container start counts as a boot.

On Linux, RunWisp tells boots apart by the kernel boot ID and the start time
of PID 1. On macOS it uses the boot session UUID. Where neither is available,
`"boot"` runs on every daemon start, like `true`. A container that shares the
host's PID namespace (`--pid=host`) follows the host's boots.

### autostart

**type**: `boolean` **default**: `true` **since**: `1.6`

With `false`, the task's [`cron`](#cron) schedule starts paused the first time
RunWisp schedules the task: on the first daemon start with it, on the reload
that adds it or gives it a `cron`, or when `runwisp takeover` hands it over
from the system cron. It
fires nothing until you resume it from the Web UI, the TUI (`p`), or
`runwisp resume`. After that it stays resumed across restarts.

```toml title="runwisp.toml"
[tasks.nightly-export]
# ...
cron      = "0 2 * * *"
autostart = false # check the first run by hand, then resume
```

- Needs [`cron`](#cron).
- Can't be combined with `manual_trigger = false` (the schedule could never be
  resumed) or with [`run_on_start`](#run_on_start).
- Setting it to `false` on a task RunWisp already knows doesn't pause it. The
  reload prints a warning; run `runwisp pause <name>` to pause it now.

### catch_up

**type**: `integer` **default**: `1` **min**: `0` **max**: `10000`

How many runs missed while the daemon was down are run at startup.

- `0`: run none. Good for jobs that run every minute.
- `1`: run only the most recent missed one. Good for a daily sync.
- `N`: run up to the `N` most recent. Good for queue processors.

A value above `1` requires `on_overlap = "queue"`, because the missed runs start
one after another.

```toml title="runwisp.toml"
[tasks.hourly-roll]
# ...
cron       = "0 * * * *"
catch_up   = 24
on_overlap = "queue"
```

### jitter

**type**: `duration` **max**: `24h`

The longest this task's start may be delayed so that jittered tasks with the
same start time (like 03:00) run one after another instead of all at once. It
is a maximum, not a fixed delay: with nothing else jittered running, the task
starts on time.

- Doesn't apply to manual runs, retries, or catch-up runs.
- Needs [`cron`](#cron).

```toml title="runwisp.toml"
[tasks.nightly-report]
# ...
cron   = "0 3 * * *"
jitter = "30m"  # start may slip up to 30m while other jittered runs are busy
```

Set it in [`[defaults]`](/configuration/defaults/) to apply it to every cron
task.

### timezone

**type**: `string` **default**: [`[daemon] timezone`](/configuration/daemon/#timezone), then the host zone

The IANA zone this task's [`cron`](#cron) is read in. Follows daylight saving
time.

```toml title="runwisp.toml"
[tasks.eu-market-open]
# ...
cron     = "0 9 * * 1-5"
timezone = "Europe/Bratislava"
```

## Concurrency

### on_overlap

**type**: `enum` **default**: `"queue"`

What happens when the task is triggered while already at
[`max_concurrent`](#max_concurrent) (default `1`).

```toml title="runwisp.toml"
[tasks.queue-drain]
# ...
cron       = "*/10 * * * *"
on_overlap = "skip"
```

Possible values:

- `queue`: the new run waits and starts when a slot frees up (queue size bounded by [`max_queued`](#max_queued))
- `skip`: the new run is dropped and recorded as skipped
- `kill`: the running run is stopped so the new one takes over

### max_concurrent

**type**: `integer` **default**: `1` **min**: `1` **max**: `1024`

How many runs of this task may be active at once. At the limit,
[`on_overlap`](#on_overlap) decides what happens to the next trigger.

```toml title="runwisp.toml"
[tasks.thumbnailer]
# ...
max_concurrent = 4
```

### max_queued

**type**: `integer` **default**: `100` **min**: `0` **max**: `10000`

With `on_overlap = "queue"`, the cap on runs waiting in line. Past the cap,
further triggers record `end_reason = "queue_full"`. With `0`, no run waits: a
trigger that finds every slot busy records `queue_full` right away.

```toml title="runwisp.toml"
[tasks.ingest]
# ...
on_overlap = "queue"
max_queued = 500
```

## Retries & timeout

### timeout

**type**: `duration` **default**: none (no limit)

The longest one attempt may run. A longer run is stopped (with
[`stop_signal`](#stop_signal), then [`graceful_stop`](#graceful_stop)) and
recorded as `timeout`. `"0s"` turns off a `[defaults]` timeout.

```toml title="runwisp.toml"
[tasks.queue-drain]
# ...
cron    = "*/10 * * * *"
timeout = "9m"
```

### warn_after

**type**: `duration` **default**: none **since**: `1.7`

Sends one [`long_running`](/configuration/routes/#matchkinds) notification when
a run is still going this long after it started. The run keeps going; pair it
with [`timeout`](#timeout) to stop it later. The clock starts when the run
starts, not while it waits in a queue. `"0s"` turns off a `[defaults]` value.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
cron       = "0 3 * * *"
warn_after = "45m"
timeout    = "2h"
```

- It goes to the task's [`notify`](#notify) list and
  [`global_notifiers`](/configuration/notify/#global_notifiers), or to any
  [`[[route]]`](/configuration/routes/) that lists `long_running`.
- A run that ends first sends nothing. A `warn_after` at or above `timeout`
  never fires.
- It is not a failure: the run's own outcome is judged by
  [`failures`](#failures) when it ends.
- Tasks only. A service has no end to run long past.

### retry_attempts

**type**: `integer` **default**: `0` **min**: `0` **max**: `100`

Extra attempts after the first one fails. A retry happens only when the reason
is `failed`, `timeout`, `crashed`, `log_overflow`, `start_failed`, or
`unhealthy`, **and**
[`failures`](#failures) counts the run as a failure. A manual stop or a kill ends
the retries.

```toml title="runwisp.toml"
[tasks.flaky-fetch]
# ...
retry_attempts = 3
retry_delay    = "2s"
```

### retry_delay

**type**: `duration` **default**: `5s`

The wait before the first retry. Used only when
[`retry_attempts`](#retry_attempts) is above `0`;
[`retry_backoff`](#retry_backoff) decides how it grows.

```toml title="runwisp.toml"
[tasks.flaky-fetch]
# ...
retry_attempts = 3
retry_delay    = "5s"
```

### retry_backoff

**type**: `enum` **default**: `"constant"`

How [`retry_delay`](#retry_delay) grows across attempts.

```toml title="runwisp.toml"
[tasks.flaky-fetch]
# ...
retry_attempts = 4
retry_delay    = "2s"
retry_backoff  = "exponential"  # 2s, 4s, 8s, 16s
```

Possible values:

- `constant`: the same [`retry_delay`](#retry_delay) before every attempt (2s, 2s, 2s, 2s)
- `linear`: [`retry_delay`](#retry_delay) times the attempt number (2s, 4s, 6s, 8s)
- `exponential`: double each time (2s, 4s, 8s, 16s)

The computed delay is capped at 5m, regardless of `retry_backoff`.

### graceful_stop

**type**: `duration` **default**: `5s`

How long a stopping run has to exit after [`stop_signal`](/configuration/tasks/#stop_signal) before
RunWisp SIGKILLs it. Used on timeout, `on_overlap = "kill"`, manual stop, and
daemon shutdown. `"0s"` kills at once.

```toml title="runwisp.toml"
[tasks.queue-drain]
# ...
graceful_stop = "30s"
```

- The signal goes to the whole process group. Every child process gets the same
  time, and anything still running after it is killed.
- If it is longer than
  [`shutdown_timeout`](/configuration/daemon/#shutdown_timeout), the daemon
  warns at boot, because at shutdown the run may be killed early.

### stop_signal

**type**: `enum` **default**: `"SIGTERM"`

The first signal sent to stop a run. The `SIG` prefix is optional. Use
`SIGINT` for tools that expect Ctrl-C, or `SIGKILL` to skip the grace time.
Anything still running after [`graceful_stop`](/configuration/tasks/#graceful_stop) is SIGKILLed.

```toml title="runwisp.toml"
[tasks.queue-drain]
# ...
stop_signal   = "SIGINT"
graceful_stop = "10s"
```

Possible values: `SIGTERM`, `SIGINT`, `SIGQUIT`, `SIGHUP`, `SIGKILL`, `SIGUSR1`,
`SIGUSR2` (also without the `SIG` prefix).

### Fail-fast

RunWisp starts [`run`](#run) as `<shell> -e -c <script>`. A multi-line script
stops at the first command that fails, and that exit code becomes the run's
exit code. You don't need `set -e`.

- `-u` and `-o pipefail` are not set. For `pipefail`, set [`shell`](#shell) to
  `/bin/bash` and add `set -o pipefail` to the script.
- To turn fail-fast off for a task, start [`run`](#run) with `set +e`.
- For one command that may exit non-zero, add `|| true`.

## What counts as a failure

:::note[The failure model]
Every run ends with a reason. [`failures`](#failures) decides which reasons and
exit codes turn a run red and fire [`notify`](#notify).

- A token is a reason name, an exit code, an inclusive range (`"42"`,
  `"1-23"`), or an output pattern (`'output:(?i)error'`). Codes are 1 to 255.
- Exit `0` is a success unless an output pattern matched a line of stdout or
  stderr. Then the run ends as `failed`, and its log notes which pattern matched.
- With `"failed"` in the list, every non-zero exit is a failure. Without it,
  only the listed codes fail; other non-zero exits are recorded and shown, but
  are not red and don't notify.
- A bare list replaces the inherited set. Prefix every token with `+` or `-` to
  change the inherited set instead. You can't mix the two styles in one list.

It also limits [`retry_attempts`](#retry_attempts) and services'
`restart = "on_failure"`: only runs counted as failures are run again. Adding
`stopped` or `missed` never causes a retry.
:::

### failures

**type**: `string[]` **default**: `["failed", "timeout", "crashed", "log_overflow", "start_failed", "unhealthy", "missed"]`

Which run outcomes count as a failure.

```toml title="runwisp.toml"
[tasks.web]
# ...
failures = ["-missed"]              # stop paging on a missed tick

[tasks.rsync]
# ...
failures = ["timeout", "23", "24"]  # only these exits fail

[tasks.report]
# ...
failures = ['+output:(?i)error']    # also fail when a line says "error"
```

Possible values:

- `failed`: the command exited non-zero or was killed by a signal
- `timeout`: stopped for running longer than [`timeout`](#timeout)
- `crashed`: still running when the daemon itself was killed (recorded at the next start)
- `log_overflow`: hit [`log_max_size`](#log_max_size) under `log_on_full = "kill"`
- `start_failed`: a service gave up after too many fast restarts (see [`restart_attempts`](/configuration/services/#restart_attempts))
- `unhealthy`: a service instance was stopped for failing its [`health_check`](/configuration/services/#health_check)
- `missed`: a scheduled firing was skipped while the daemon was down
- `stopped`: an operator stopped the run
- `daemon_stopped`: still running when the daemon shut down
- `skipped`: dropped because a run was already going under [`on_overlap = "skip"`](#on_overlap)
- `queue_full`: dropped because the queue already held [`max_queued`](#max_queued) runs
- `dst_skipped`: the second of two identical firings when the clock falls back for DST
- `output:<regex>`: a line of stdout or stderr matched the regex, even if the command exited 0. See [Output patterns](#output-patterns).

### Output patterns

**since**: `1.3`

Some commands print an error and still exit 0. Add an `output:` token to catch
that:

```toml title="runwisp.toml"
[tasks.report]
run = "./report.sh"
failures = ['+output:ERROR']
```

- Each line of stdout and stderr is checked on its own. The pattern can match
  anywhere in the line.
- The first match ends the run as `failed`. The log shows which pattern matched.
- Lines are checked after [`secrets`](#secrets) are masked, so they look the
  same as in the log.
- Patterns match the text without colour codes, so `^ERROR` also matches a red
  `ERROR` line. The log keeps the codes.
- Wrap the token in single quotes. Inside double quotes, TOML reads `\` as an
  escape: `"output:\d"` is a config error, and `"output:\bfail"` quietly turns
  `\b` into a backspace character.

Add several tokens to fail on any of them:

```toml title="runwisp.toml"
[tasks.report]
# ...
failures = ['+output:(?i)\berror\b', '+output:^Traceback']
```

Patterns use Go's [RE2 syntax](https://github.com/google/re2/wiki/Syntax), which
is close to the regex in most languages. Lookarounds (`(?=...)`) and
backreferences (`\1`) are not supported. Common patterns:

| Token                             | Fails when a line                                       |
| --------------------------------- | ------------------------------------------------------- |
| `'output:ERROR'`                  | contains `ERROR`, in upper case only                    |
| `'output:(?i)error'`              | contains `error` in any case (`Error`, `ERROR`)         |
| `'output:\bfail\b'`               | contains the word `fail`, but not `failover`            |
| `'output:^FATAL'`                 | starts with `FATAL`                                     |
| `'output:failed$'`                | ends with `failed`                                      |
| `'output:error\|warning'`         | contains `error` or `warning`                           |
| `'output:\[ERROR\]'`              | contains `[ERROR]` (`\` makes `[` and `]` plain text)   |
| `'output:[1-9][0-9]* errors?'`    | reports one or more errors (`3 errors`), not `0 errors` |
| `'output:HTTP 5[0-9]{2}'`         | contains a 5xx status such as `HTTP 503`                |
| `'output:(?i)(exception\|panic)'` | contains `exception` or `panic` in any case             |

The building blocks:

- `(?i)` at the start ignores case for the whole pattern.
- `^` is the start of the line, `$` is the end.
- `\b` is a word edge, `\d` or `[0-9]` is a digit, `.` is any character.
- `*` repeats the previous item zero or more times, `+` one or more, `?` makes
  it optional, `{2}` exactly twice.
- `a|b` matches either side. Use `(...)` to group.
- To match `. [ ] ( ) * + ? | ^ $ \` as plain text, put `\` before it.

To drop a pattern inherited from [`[defaults]`](/configuration/defaults/), write
the same token with `-`, for example `'-output:(?i)error'`. The text must match
exactly.

## Logs & retention

### keep_runs

**type**: `integer` **default**: none (no limit) **min**: `0` **max**: `1000000`

Keep only the N most recent completed runs. Older runs and their logs are
deleted by the hourly cleanup. `0` keeps no completed runs. With
[`keep_for`](/configuration/tasks/#keep_for) also set, whichever deletes more wins.

With neither this nor `keep_for` set, a task keeps every run, so an every-minute
task grows until you set one. Set it for every task in
[`[defaults]`](/configuration/defaults/), or cap all logs with
[`storage.max_size`](/configuration/storage/#max_size).

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
keep_runs = 200
```

### keep_for

**type**: `duration` **default**: none (no limit)

Delete runs older than this. With [`keep_runs`](/configuration/tasks/#keep_runs) also set, whichever
deletes more wins.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
keep_for = "90d"
```

Examples: `48h` (2 days), `14d`, `2w`, `90d`.

Every duration accepts `ms`, `s`, `m`, `h`, `d` (days), and `w` (weeks), for
example `"90s"`, `"2d"`, `"1w"`. See [Logs & retention](/concepts/logs/) for log
rotation and cleanup timing.

### log_max_size

**type**: `size` **default**: `100mb`

The largest size of one run's captured output on disk. Units: `b`, `kb`, `mb`,
`gb`, `tb`. At the limit, [`log_on_full`](/configuration/tasks/#log_on_full) decides what happens.
`0`, negative, and invalid values are rejected at load.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
log_max_size = "500mb"
```

### log_on_full

**type**: `enum` **default**: `"drop_old"`

What happens when a run's log reaches [`log_max_size`](/configuration/tasks/#log_max_size).

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
log_max_size = "50mb"
log_on_full  = "drop_old"
```

Possible values:

- `drop_old`: keep the newest output, delete the oldest
- `drop_new`: keep the first output, ignore the rest
- `kill`: stop the run and record `log_overflow`

## Environment & secrets

[`env`](/configuration/tasks/#env) and [`secrets`](/configuration/tasks/#secrets) reach the process the same way. The
difference is who can see them:

- [`env`](/configuration/tasks/#env) and [`env_file`](/configuration/tasks/#env_file) values are shown in the Web UI, TUI,
  and REST API to anyone logged in.
- [`secrets`](/configuration/tasks/#secrets) and [`secrets_file`](/configuration/tasks/#secrets_file) values are never shown.
  At most, the `secrets_file` path is shown.
- If a command prints a secret, RunWisp replaces the exact value with
  `[redacted]` in the stored and streamed output. This only matches the exact
  text: a secret that was changed (base64, URL-encoded) or split across lines
  can still appear.

Merge order at start (a later layer wins on the same key):

1. The daemon's own environment (see [`env_base`](/configuration/tasks/#env_base)).
2. [`env_file`](/configuration/tasks/#env_file), then [`env`](/configuration/tasks/#env): first from `[defaults]`, then
   from the task itself.
3. [`secrets_file`](/configuration/tasks/#secrets_file), then [`secrets`](/configuration/tasks/#secrets): first from
   `[defaults]`, then from the task itself.

So an inline value beats a file value, and a secret beats an env value with the
same name.

Files:

- Paths can be absolute, `~/`-relative, or relative to the `runwisp.toml`
  directory.
- Format is dotenv: one `KEY=VALUE` per line, `#` starts a comment, blank lines
  are skipped. Values are read as they are: no shell expansion and no
  [`${...}` substitution](/configuration/substitution/).

Limits, checked at load:

- Keys must match `^[A-Za-z_][A-Za-z0-9_]*$`.
- Values can't contain NUL bytes or be longer than 32 KiB.
- At most 256 env + secrets entries in total.

### env

**type**: `map`

Environment variables for the process. Their values are shown in the API and
UI, so put passwords and tokens in [`secrets`](/configuration/tasks/#secrets). To read from a file,
use [`env_file`](/configuration/tasks/#env_file).

```toml title="runwisp.toml"
# ...

[tasks.backup.env]
BACKUP_BUCKET = "s3://prod-backups"
DRY_RUN       = "0"
```

### secrets

**type**: `map`

Secret environment variables: passwords, tokens, API keys. They work like
[`env`](/configuration/tasks/#env), but their keys and values are never shown. To read from a file,
use [`secrets_file`](/configuration/tasks/#secrets_file).

```toml title="runwisp.toml"
# ...

[tasks.backup.secrets]
RESTIC_PASSWORD = "${file:~/.config/runwisp/restic.pass}"
```

### env_file

**type**: `string`

A dotenv file merged below [`env`](/configuration/tasks/#env) (inline values win). Its values are
shown in the API and UI, like `env`. Paths can be absolute, `~/`-relative, or
relative to the `runwisp.toml` directory. Lines are plain `KEY=VALUE`, with no
shell expansion.

```toml title="runwisp.toml"
[tasks.backup]
# ...
env_file = "backup.env"
```

### secrets_file

**type**: `string`

A dotenv file merged below [`secrets`](/configuration/tasks/#secrets). Only the path is shown in the
API and UI, never the contents. Same paths and format as
[`env_file`](/configuration/tasks/#env_file).

```toml title="runwisp.toml"
[tasks.backup]
# ...
secrets_file = "/etc/runwisp/backup-secrets.env"
```

[`env`](#env) and [`secrets`](#secrets) are for values that are the same on every
run. For a value that changes per run, use a [parameter](#params).

## Parameters

For an introduction, see [Parameters](/concepts/parameters/).

### params

**type**: `table` (array of `[[tasks.<name>.params]]` entries)

The inputs a task takes. Each one becomes a field on the Run form in the Web
UI, TUI, and REST API. Each entry has exactly one kind keyword (`env`, `arg`,
`option`, or `flag`) that decides how the value reaches your command.

- Values are passed as real arguments or env vars, never pasted into the shell
  string, so input like `; rm -rf /` is harmless.
- Scheduled runs (cron, catch-up, retries) use the declared defaults.

```toml title="runwisp.toml"
[tasks.backup]
run = "/usr/local/bin/backup.sh"
params = [
  { env = "PROJECT_ID", required = true },
  { arg = "source", required = true },
  { arg = "dest", default = "/backups" },
  { option = "--region", choices = ["us", "eu"] },
  { flag = "--force" },
]
```

Kind keyword (exactly one per entry):

- `env`: pass the value as an environment variable with this name. The name
  can't also be an [`env`](#env) or [`secrets`](#secrets) key on the same task.
- `arg`: append the value as a positional argument, in declaration order.
- `option`: render as `--name value`. A name ending in `=` glues them
  (`--date=2026-01-01`).
- `flag`: a boolean whose token is appended when on, omitted when off. Takes no
  `choices` or `type`.

Attributes:

- `default`: the value scheduled runs use and the manual form starts with
  (`true`/`false` for a flag).
- `required`: the manual form won't submit without a value (`env`, `arg`,
  `option`). A required parameter on a scheduled task must also set `default`.
- `type`: `string` (default) or `number`. A value that isn't a number is
  rejected before the run starts.
- `choices`: a fixed list, shown as a dropdown. Other values are rejected.
- `allow_custom`: with `choices`, also allow a value not in the list. Rejected
  without `choices`.
- `description`: help text shown under the field.

:::note[Empty field vs. empty string]
On a manual run:

- A filled field (the default or your value) is passed.
- A cleared field is not passed at all: no option, arg, or env var. It does
  not fall back to the default. A `required` field can't be cleared.
- To pass an empty string (`--note ''`), use the toggle under the field (in the
  TUI, <kbd>ctrl+t</kbd>).

A flag that is off is not passed. A retry uses exactly the values of the
original run.
:::

## Working directory & shell

### working_dir

**type**: `string`

The directory the process runs in. Unset, it is the daemon's directory.

- A relative path is relative to the `runwisp.toml` directory.
- `~` is the home directory of the user the run runs as.
- The directory is checked when the run starts, not at load.

```toml title="runwisp.toml"
[tasks.deploy]
working_dir = "/srv/app"
run         = "./bin/build"
```

### shell

**type**: `string` **default**: `/bin/sh`

The shell for [`run`](/configuration/tasks/#run), as an absolute path. Use
`/bin/bash` for arrays, `[[ ]]`, or `set -o pipefail`. It is started as
`<shell> -e -c <script>`, so [fail-fast](/configuration/tasks/#fail-fast) works
for POSIX shells. RunWisp warns at boot when it can't turn fail-fast on.
Host processes only: it is an error on a compose unit.

```toml title="runwisp.toml"
[tasks.nightly-report]
shell = "/bin/bash"
run   = "set -o pipefail; make report | tee out.log"
```

### env_base

**type**: `enum` **default**: `"inherit"`

What the environment starts from, before [`env`](/configuration/tasks/#env) and
[`secrets`](/configuration/tasks/#secrets) are added. Host processes only: it is an error on a
compose unit.

```toml title="runwisp.toml"
[tasks.backup-db]
env_base = "clean"
run      = "/usr/local/bin/nightly"
```

Possible values:

- `inherit`: start from the daemon's environment. Runs then depend on how the
  daemon was started.
- `clean`: start with only `PATH`, `SHELL`, `HOME`, and `USER`/`LOGNAME` (like
  cron), so runs are repeatable. Set everything else in [`env`](/configuration/tasks/#env).

### user

**type**: `string`

Run as another OS user: `user` or `user:group`, by name or numeric id (the same
form as `chown` and Compose). RunWisp looks up the account at start, sets
`HOME`, `USER`, and `LOGNAME`, and applies its groups.

- Works only when the daemon runs as root. Otherwise the run fails.
- Empty keeps the daemon's user.
- Host processes only: it is an error on a compose unit.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
user = "reporter:reporter"
```

### umask

**type**: `string`

The octal file-creation mask for the run: `"027"` makes new files `rw-r-----`.

- Write at least three digits (`"022"`, not `"22"`).
- It applies only to this run's process, not to other runs.
- Empty keeps the daemon's umask.
- Host processes only: it is an error on a compose unit.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
umask = "027"
```

## Compose-backed tasks

A task can run a compose service instead of a shell command:

```toml title="runwisp.toml"
[tasks.nightly-backup]
cron            = "0 3 * * *"
compose_file    = "./docker-compose.yml"
compose_service = "backup"
```

### compose_file

**type**: `string`

Path to a docker-compose file. The unit then runs the compose service named by
[`compose_service`](/configuration/tasks/#compose_service) instead of a shell command. Without
[`run`](/configuration/tasks/#run), each run is `docker compose run --rm <service>` with the
service's own command. With `run`, see [`compose_mode`](/configuration/tasks/#compose_mode).

The unit runs in the compose project the file describes, the one
`docker compose up` uses in that directory: `COMPOSE_PROJECT_NAME`, the file's
top-level `name:`, or the directory name. A fresh container joins that
project's network and named volumes.

```toml title="runwisp.toml"
[tasks.nightly-backup]
cron            = "0 3 * * *"
compose_file    = "./docker-compose.yml"
compose_service = "backup"
```

### compose_service

**type**: `string` **default**: the task name

The service in [`compose_file`](/configuration/tasks/#compose_file) to run. `runwisp validate`
rejects a name the file doesn't define.

Since 1.7, a task with [`run`](/configuration/tasks/#run) can leave out `compose_file` when RunWisp
runs in the same compose project; see [Without `compose_file`](/configuration/compose/#without-compose_file).

```toml title="runwisp.toml"
[tasks.nightly-backup]
compose_file    = "./docker-compose.yml"
compose_service = "backup"
```

### compose_mode

**type**: `enum` **default**: `"exec"` when [`run`](/configuration/tasks/#run) is set, else `"run"`

How a [`compose_file`](/configuration/tasks/#compose_file) unit runs.

```toml title="runwisp.toml"
[tasks.migrate]
compose_file    = "./docker-compose.yml"
compose_service = "app"
compose_mode    = "exec"
run             = "rails db:migrate"
```

Possible values:

- `exec`: run your [`run`](/configuration/tasks/#run) command inside the service's running container
  (`docker compose exec`). Requires `run`.
- `run`: start a new container for each run (`docker compose run --rm`). It runs
  your `run` command if set, else the service's own command.

See [Running a command in a service](/configuration/compose/#running-a-command-in-a-service-compose_mode)
for the limits of `exec`.

To import every service in a compose file, see
[`[compose.*]`](/configuration/compose/).

:::note[Parameters on a compose task]
[Parameters](#params) work here. In new-container mode (no [`run`](#run)),
`arg`, `option`, and `flag` values are passed like `docker compose run <svc> …`
arguments: they replace the service's `command:` and go to the image's
`ENTRYPOINT`.

```toml title="runwisp.toml"
[tasks.nightly-backup]
cron            = "0 3 * * *"
compose_file    = "./docker-compose.yml"
compose_service = "backup"
params          = [{ arg = "since", default = "yesterday" }]
```

:::

## Notifications

### notify

**type**: `string[]`

Notifier ids to alert when a run counts as a failure (see
[`failures`](/configuration/tasks/#failures)), when a run succeeds after a
failed one ([`recovered`](/configuration/routes/#matchkinds), since 1.8), or, on
a task, when it is still going after
[`warn_after`](/configuration/tasks/#warn_after). A missed run is a failure by
default, so it alerts here too.

```toml title="runwisp.toml"
[tasks.backup-db]
# ...
notify = ["slack-ops"]
```

- Each entry is a notifier declared in `[notifiers.<id>]`, `"inapp"` (the bell),
  or `"<id>:<target>"` to reuse a notifier's credentials with another target
  (`"slack:#deploys"`, `"tg:-1009998887"`, `"mail:ops@example.com"`). See
  [`notifiers`](/configuration/routes/#notifiers) for which types accept a target.
- [`[notify] global_notifiers`](/configuration/notify/#global_notifiers)
  (default `["inapp"]`) is added to every list.
- `notify = []` is the same as leaving it out.
- To alert on other outcomes (a success, for example), use a
  [`[[route]]`](/configuration/routes/).

## What's rejected on tasks

The config fails to load with any of these:

- Service-only keys: [`restart`](/configuration/services/#restart),
  [`restart_attempts`](/configuration/services/#restart_attempts),
  [`restart_delay`](/configuration/services/#restart_delay),
  [`restart_backoff`](/configuration/services/#restart_backoff),
  [`healthy_after`](/configuration/services/#healthy_after),
  [`instances`](/configuration/services/#instances),
  [`priority`](/configuration/services/#priority),
  [`depends_on`](/configuration/services/#depends_on). A task uses
  [`retry_attempts`](#retry_attempts) instead of restarts.
- A name already used by a `[services.*]` entry.
- An empty or missing [`run`](#run) (unless [`compose_file`](#compose_file) or [`sdk`](#sdk) is set).
