﻿RunWisp runs two kinds of work. A **task** runs and exits: a backup, a report,
a health probe. A **service** is meant to stay up: a queue worker, an agent, a
server. If the command exits on its own when it's done, it's a task. If it runs
until you stop it, it's a service.

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

[services.worker]
instances = 2
run       = "node worker.js"
```

If you find yourself writing `while true; do ...; done` in a task, make it a
service (or see [a polling loop](#a-polling-loop) below).

## What's different

Tasks are started by something: a [`cron`](/configuration/tasks/#cron) schedule,
a manual run, or an API call. Only tasks have scheduling
([`catch_up`](/configuration/tasks/#catch_up),
[`jitter`](/configuration/tasks/#jitter),
[`run_on_start`](/configuration/tasks/#run_on_start)),
[parameters](/concepts/parameters/), [overlap rules](/concepts/concurrency/),
and [retries](/concepts/retries/).

Services start with the daemon and, by default, are restarted when they exit. Only
services have [`instances`](/configuration/services/#instances),
[`restart`](/configuration/services/#restart),
[`healthy_after`](/configuration/services/#healthy_after), and boot ordering
([`priority`](/configuration/services/#priority),
[`depends_on`](/configuration/services/#depends_on)).

Putting a key on the wrong kind is a config error. Everything else (logs,
timeouts, environment, [`failures`](/configuration/tasks/#failures),
[`notify`](/configuration/tasks/#notify)) works the same on both, and every
task run and every service instance shows up in run history with its exit code
and output.

Tasks and services share one set of names, so a task and a service can't both
be called `worker`.

## Running several copies

A task uses [`max_concurrent`](/configuration/tasks/#max_concurrent): the most
runs that may overlap. A service uses
[`instances`](/configuration/services/#instances): how many copies are always up.

- **`max_concurrent = 4`** on a thumbnail task that runs every minute. Most runs
  finish in seconds, but during a backlog up to four run at once.
- **`instances = 4`** on a queue worker. Four processes stay connected to the
  queue, and RunWisp restarts any one that exits.

Get this backwards and it goes wrong in a predictable way. A long-lived worker
written as a task holds its slot while the queue backs up. A 30-second job
written as a service gets restarted over and over.

## Choosing on the edge cases

### A polling loop

`while true; do work; sleep 60; done` is usually better as a task with
[`cron = "* * * * *"`](/configuration/tasks/#cron) and [`on_overlap = "skip"`](/configuration/tasks/#on_overlap). Each poll then gets its own run,
exit code, and log, so you can see exactly which one failed.

Keep it a service when the process holds state worth keeping between rounds: a
queue connection, a websocket, a cache it built in memory.

### A job you only start by hand

Still a task. Leave out [`cron`](/configuration/tasks/#cron) and start it with
`runwisp run <name>`, **Run now** in the Web UI, the TUI, or the
REST API.

### A task that must never overlap

Tasks already queue by default: a new run waits for the previous one to finish.
If two runs must never even line up, use `on_overlap = "skip"`. See
[Overlapping runs](/concepts/concurrency/).
