﻿A service is a long-running process. RunWisp restarts it when it exits or
crashes, until you stop it. This page lists every key a `[services.<name>]`
block accepts. Unset keys fall back to [`[defaults]`](/configuration/defaults/),
then a built-in default.

## Identity & metadata

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

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

The text after `services.` is the service's name: `[services.api-worker]` is a
service called `api-worker`. The name is used in the CLI, API, Web UI, and log
directory.

- Letters, digits, and `. _ - :`, up to 100 characters.
- Must be unique across `[services.*]` and [`[tasks.*]`](/configuration/tasks/).
- Quote names that aren't a bare TOML key (`[services."api:v2"]`).

```toml title="runwisp.toml"
[services.api-worker]
run = "/usr/local/bin/worker"
```

### 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**: `"Services"`

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
```

On a service, this also gates the TUI's `s`/`r` keys and
[`runwisp start`/`stop`/`restart <name>`](/reference/cli/#runwisp-restart).
With `manual_trigger = false`, only a `runwisp.toml` edit plus `runwisp reload`,
or a [hook](#hook_tokens), changes its running state.

### 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.

## Instances

### instances

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

How many copies of the process run at once.

- Each instance is its own run with an `instance_index` (`0`, `1`, `2`, …). The
  Web UI and TUI show them as `name#1`, `name#2`; a single instance is plain
  `name`.
- Each instance gets its index in the `RUNWISP_INSTANCE_INDEX` environment
  variable. A value in [`env`](#env) overrides it.
- All instances share the config and the log view.
- When one instance exits, only that one is restarted.

```toml title="runwisp.toml"
[services.api-worker]
instances = 3
run       = "/usr/local/bin/worker"
```

## Restart behaviour

For a command that should run once and exit, use a
[task](/concepts/tasks-vs-services/).

### restart

**type**: `enum` **default**: `"always"`

When an instance is started again after it exits.

```toml title="runwisp.toml"
[services.worker]
# ...
restart = "on_failure"
```

Possible values:

- `always`: restart after any exit
- `on_failure`: restart only when [`failures`](#failures) counts the exit as a
  failure (and the reason is `failed`, `timeout`, `crashed`, `log_overflow`,
  `start_failed`, or `unhealthy`)
- `never`: don't restart; one exit is final

A manual **Restart** always starts the instance again, whatever this is set to.

### restart_delay

**type**: `duration` **default**: `1s`

The base wait before an automatic restart. [`restart_backoff`](#restart_backoff)
decides how it grows. `0` is allowed and means no wait. A manual **Restart**
never waits.

```toml title="runwisp.toml"
[services.flaky]
# ...
restart_delay = "2s"
```

### healthy_after

**type**: `duration` **default**: `60s`

How long an instance must stay up to count as healthy. Reaching it resets the
restart backoff and the failed-start count used by
[`restart_attempts`](#restart_attempts).

With a [`health_check`](#health_check), it is the deadline for the first passing
check instead, and `0` is rejected.

```toml title="runwisp.toml"
[services.api-worker]
# ...
healthy_after = "2m"
```

### restart_attempts

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

How many failed starts in a row an instance may have before it goes
[FATAL](#when-a-service-cant-start-fatal) and stops restarting. `0` gives up
after the first failed start. With the default
[`restart_delay`](#restart_delay) and [`restart_backoff`](#restart_backoff),
10 attempts keep trying for about 5 minutes, enough to ride out a database
restart. Since 1.8, the default is `10` (it was `3`).

```toml title="runwisp.toml"
[services.flaky]
# ...
restart_attempts = 2
```

### restart_backoff

**type**: `enum` **default**: `"exponential"`

How [`restart_delay`](#restart_delay) grows after each restart. The delay has an
upper limit.

```toml title="runwisp.toml"
[services.flaky]
# ...
restart_backoff = "exponential"
```

Possible values: `constant`, `linear`, `exponential` (the same curves as
[`retry_backoff`](/configuration/tasks/#retry_backoff)).

### When a service can't start: FATAL

A **failed start** is any exit before the instance became healthy: before it
reached [`healthy_after`](#healthy_after), or, with a
[`health_check`](#health_check), before its check first passed. Since 1.8, a
clean exit (success code) counts too, since a service has to keep running.

A service must stay in the foreground. A command that daemonizes (`redis-server
--daemonize yes`, `nginx` without `-g 'daemon off;'`, a trailing `&`) exits 0
at once, so every start fails, and the run log says so. Run it in its
foreground mode instead.

- After more than [`restart_attempts`](#restart_attempts) failed starts in a
  row, the instance goes **FATAL**: it stops restarting, a `start_failed` run is
  recorded, and a `service.fatal` notification goes to the in-app bell and your
  [notifiers](/notifications/).
- FATAL is kept in memory only. A daemon restart, or **Restart** in the UI or
  API, resets the count and tries again.
- The `start_failed` runs stay in history.

```toml title="runwisp.toml"
[services.flaky]
run              = "exit 1"   # can never come up
healthy_after    = "5s"       # must stay up 5s to count as healthy
restart_attempts = 2          # give up after 2 failed starts in a row
```

## Health checks

### health_check

**type**: `table` **default**: none **since**: `1.3`

A command that decides when an instance is healthy, and stops it when it stops
passing. Without it, uptime ([`healthy_after`](#healthy_after)) is the only
signal.

```toml title="runwisp.toml"
[services.api]
run = "./api-server"

[services.api.health_check]
run = "curl -fsS http://127.0.0.1:8080/healthz"
```

- The check runs on its schedule next to every running instance. A non-zero
  exit fails it.
- The first pass makes the instance healthy. Failures before that are ignored,
  but if nothing passes within [`healthy_after`](#healthy_after), the instance is
  stopped as `unhealthy` and counts as a
  [failed start](#when-a-service-cant-start-fatal).
- Once healthy, a failed check is retried. When the retries run out, the instance
  is stopped as `unhealthy` and [`restart`](#restart) decides what happens next.
- Each failed check, the first pass, and the reason for a stop are written to the
  instance's log. The check gets no runs of its own.

The table takes these task keys, with the same meaning:

| Key                                                                                                                                                                                                                    | Default                                               |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`run`](/configuration/tasks/#run)                                                                                                                                                                                     | required                                              |
| [`cron`](/configuration/tasks/#cron)                                                                                                                                                                                   | `"@every 10s"`                                        |
| [`timezone`](/configuration/tasks/#timezone)                                                                                                                                                                           | the daemon's                                          |
| [`timeout`](/configuration/tasks/#timeout)                                                                                                                                                                             | `[defaults]` timeout, else `5s`; `0` is rejected      |
| [`failures`](/configuration/tasks/#failures)                                                                                                                                                                           | `[defaults]` failures, not the service's              |
| [`retry_attempts`](/configuration/tasks/#retry_attempts)                                                                                                                                                               | `2`; `0` stops the instance on the first failed check |
| [`retry_delay`](/configuration/tasks/#retry_delay), [`retry_backoff`](/configuration/tasks/#retry_backoff)                                                                                                             | as on tasks                                           |
| [`working_dir`](/configuration/tasks/#working_dir), [`shell`](/configuration/tasks/#shell), [`umask`](/configuration/tasks/#umask), [`env_base`](/configuration/tasks/#env_base), [`user`](/configuration/tasks/#user) | the service's                                         |
| [`env`](/configuration/tasks/#env), [`secrets`](/configuration/tasks/#secrets)                                                                                                                                         | merged over the service's, key by key                 |
| [`env_file`](/configuration/tasks/#env_file), [`secrets_file`](/configuration/tasks/#secrets_file)                                                                                                                     | none                                                  |
| [`compose_file`](/configuration/tasks/#compose_file), [`compose_service`](/configuration/tasks/#compose_service), [`compose_mode`](/configuration/tasks/#compose_mode)                                                 | none                                                  |

A check that times out is killed at once. Ticks that fall while a check is still
running are skipped.

To check inside a running compose container, set `compose_file` and
`compose_service`. Only `compose_mode = "exec"` is allowed, and the check then
takes nothing from the service:

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

[services.api.health_check]
run             = "curl -fsS http://127.0.0.1:8080/healthz"
compose_file    = "./compose.yaml"
compose_service = "api"
```

## Startup

### autostart

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

Whether the service starts when the daemon starts. With `false`, it stays
stopped until you start it from the UI or API.

This is read from `runwisp.toml` at every boot, not saved: a manually started
`autostart = false` service is stopped again after a daemon restart, and a
manually stopped `autostart = true` service starts again. A task's
[`autostart`](/configuration/tasks/#autostart) works differently: it applies
only the first time RunWisp sees the task.

```toml title="runwisp.toml"
[services.migration-runner]
# ...
autostart = false
```

### priority

**type**: `integer` **default**: `0`

Start order at boot. Lower starts first; equal values start in name order. It
doesn't wait for a service to be ready. For that, use
[`depends_on`](#depends_on).

```toml title="runwisp.toml"
[services.db]
# ...
priority = 0

[services.api]
# ...
priority = 10
```

## Boot order with `depends_on`

### depends_on

**type**: `string[]` **default**: none

Services that must be healthy (at least one instance up for its
[`healthy_after`](#healthy_after), or passing its
[`health_check`](#health_check)) before this one starts at boot.

```toml title="runwisp.toml"
[services.db]
run           = "postgres -D /var/lib/pg"
healthy_after = "3s"

[services.api]
run        = "./api-server"
depends_on = ["db"]  # start after db is healthy
```

- If a dependency never becomes healthy, the service waits a limited time, then
  starts anyway and logs a warning. If the dependency is stopped, or has
  exited with no restart coming, the service starts right away.
- It applies only to the automatic start at boot. Manual start and restart
  don't wait.
- At shutdown, dependent services stop first.
- Names must be existing services (not tasks). Cycles are rejected at load.
- There are no restart cascades or data passing between services. See
  [Tasks vs Services](/concepts/tasks-vs-services/).

## Concurrency

Services have no [`on_overlap`](/configuration/tasks/#on_overlap),
[`max_concurrent`](/configuration/tasks/#max_concurrent), or
[`max_queued`](/configuration/tasks/#max_queued). The number of running copies
is set by [`instances`](#instances).

## Timeout & failures

### timeout

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

The longest an instance may run. After that it is stopped and recorded as
`timeout`, then [`restart`](#restart) decides what happens next.

```toml title="runwisp.toml"
[services.report-server]
# ...
timeout = "24h"
```

### failures

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

Which outcomes count as a failure: they turn the run red, fire [`notify`](#notify),
and (with `restart = "on_failure"`) cause a restart. Same syntax as on tasks; see
[What counts as a failure](/configuration/tasks/#what-counts-as-a-failure).

```toml title="runwisp.toml"
[services.web]
# ...
failures = ["-missed"]
```

## Graceful shutdown

### 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.

It applies to each instance, on manual stop, **Restart**, and daemon shutdown.
At daemon shutdown, [`shutdown_timeout`](/configuration/daemon/#shutdown_timeout)
still limits it.

To stop cleanly, trap the stop signal in [`run`](#run) and exit. An instance
that exits after `SIGTERM` is recorded as `stopped`:

```bash
trap 'echo "shutting down"; exit 0' TERM INT
while true; do
  # do work
done
```

### 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).

## 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
```

Every crash adds a run, so a service's history can grow faster than a task's.
`200` is a good start for a service that restarts often.

### 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`.

### 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

All instances get the same environment.

[`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"
```

## Working directory & shell

All instances use the same directory, shell, environment base, user, and umask.

### 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 services

A service can run a service from an existing `docker-compose.yml` instead of a
shell command:

```toml title="runwisp.toml"
[services.api]
compose_file    = "./docker-compose.yml"
compose_service = "api"
notify          = ["slack-prod"]
```

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

### 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 service 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`.

## 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/).

For a service, this fires when an instance ends with an outcome that
[`failures`](/configuration/tasks/#failures) counts as a failure, and when an
instance goes [FATAL](#when-a-service-cant-start-fatal).

## What's rejected on services

- [`cron`](/configuration/tasks/#cron), [`catch_up`](/configuration/tasks/#catch_up):
  services don't run on a schedule. A [`health_check`](#health_check) takes its
  own `cron`.
- [`params`](/configuration/tasks/#params): services don't take parameters.
- [`retry_attempts`](/configuration/tasks/#retry_attempts),
  [`retry_delay`](/configuration/tasks/#retry_delay),
  [`retry_backoff`](/configuration/tasks/#retry_backoff): use
  [`restart_delay`](#restart_delay) and [`restart_backoff`](#restart_backoff).
  A [`health_check`](#health_check) takes its own.
- [`on_overlap`](/configuration/tasks/#on_overlap),
  [`max_concurrent`](/configuration/tasks/#max_concurrent),
  [`max_queued`](/configuration/tasks/#max_queued): use [`instances`](#instances).
- A name already used by a `[tasks.*]` entry.
- An empty or missing [`run`](#run) (unless [`compose_file`](#compose_file) or [`sdk`](#sdk) is set).
- [`instances`](#instances) outside `1` to `64`.
