#tasker — the action queue
The tasker stores work in a queue and executes it outside the request that asked for it. The panel validates a form, writes a task, and returns; the daemon picks the task up, runs it, and keeps the output in the task log.
One queue is easier to reason about than a dozen request handlers that each log differently, and it gives every action the same history, retry and cancellation rules.
A task is one row in database/storage/tasker/tasker.db. It owns a name, a group, a type, a target, JSON arguments, a status, output, error output, the attempt counters, an optional parent and position, the actor that queued it and its timestamps. A task with children is a container: it has no work of its own, and its steps are created before anything runs.
Output is human-formatted throughout: these commands print their own lines and tables and never consult the global --json flag. Exit codes follow Conventions: 0 success, 1 failure, 2 usage, 130 Ctrl+C.
#The four types
| Type | target | Behaviour |
|---|---|---|
internal | a name registered in app/modules/tasker/registry.py | calls a Python action; keeps validation and rollback |
command | an argv list, or a list of argv lists | no shell; several lists run in order |
script | an absolute path | args.argv is passed as arguments |
webhook | an http(s) URL | a non-accepted HTTP status is a failure |
internal is what the panel uses. command exists for maintenance that only a shell command can do, and webhook for notifying something outside the host.
#The daemon
#aegis tasker daemon
Runs the queue loop in the foreground. The keeper starts it as the aegis-tasker service, so an install already has it running.
aegis tasker daemon| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
The daemon polls the queue once a second, claims due root tasks and runs each one in a worker; four workers by default. It takes an exclusive lock on <run>/tasker.lock, publishes its pid in <run>/tasker.pid and rewrites <run>/tasker.heartbeat on every poll. A second copy finds the lock taken, leaves the holder's pid in the pid file and exits quietly.
On startup, rows left running by a previous daemon become interrupted: a task cannot be resumed safely when half of it may already be applied to the host. At the same time, done and cancelled tasks older than the retention window are purged.
When the keeper runs it, the daemon's output goes to <logs>/tasker.log. SIGTERM and SIGINT stop the loop without killing a task that is already in flight.
Examples:
aegis tasker daemoncd /etc/aegis && ./bin/aegis tasker daemonThe loop itself prints nothing: the work appears in the task table, and the keeper records the service start in its own log:
2026-11-17 10:36:07 aegis-tasker: started (pid 8123)#Inspecting the queue
#aegis tasker status
Counts the root tasks in each state.
aegis tasker status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Steps are not counted; only rows without a parent appear here.
Examples:
aegis tasker statusaegis tasker status && aegis tasker list --limit 5ℹ cancelled: 1ℹ done: 128ℹ failed: 2ℹ pending: 3ℹ running: 1With an empty history:
ℹ no task has run yet#aegis tasker list
Lists recent root tasks, newest first.
aegis tasker list --limit N| Argument / option | Default | Meaning |
|---|---|---|
--limit | 20 | how many root tasks to show |
Steps are not listed here. The attempts column is retries/max_retries.
Examples:
aegis tasker listaegis tasker list --limit 50id name group status attempts created──────────────────────────────────────────────────────────────────────────58 create vhost example.com web running 0/0 2026-11-17T10:41:02+00:0057 mail.alias.add mail done 0/0 2026-11-17T10:40:11+00:0056 delete vhost old.example web failed 2/3 2026-11-17T10:38:47+00:00With no tasks:
ℹ no task has run yet#aegis tasker show
Shows one task, its steps and its newest log lines.
aegis tasker show ID --lines N| Argument / option | Default | Meaning |
|---|---|---|
ID | required | task id |
--lines | 40 | how many of the newest log lines to print |
The log is printed oldest first, after the header and the steps table. Each line starts with its time of day. A task with output or error output shows that before the steps.
Examples:
aegis tasker show 58aegis tasker show 58 --lines 200ℹ create vhost example.com [done] internalℹ output: vhost written to /aegis/config/nginx/vhosts/example.com.conf pos step type status ────────────────────────────────────── 1 render vhost internal done 2 reload nginx command done10:41:03 writing /aegis/config/nginx/vhosts/example.com.conf10:41:04 nginx reloadedA failed task also prints the error on stderr:
ℹ deploy site [failed] internal✖ nginx -t rejected the configurationAn unknown id exits 1:
✖ no task 999#Changing the queue
#aegis tasker run
Queues one task immediately.
aegis tasker run TYPE TARGET --name NAME --group GROUP --arg K=V --retries N --wait| Argument / option | Default | Meaning |
|---|---|---|
TYPE | required | internal, command, script or webhook |
TARGET | required | callable name, argv JSON, script path or URL |
--name | <type>: <first 40 characters of target> | name shown in the panel and the list |
--group | cli | section that owns the task |
--arg | empty | K=V pair; repeatable |
--retries | 0 | maximum automatic retries |
--wait | off | follow the task until it reaches a final state |
--arg values are decoded as JSON when possible. --arg vhost_id=3 becomes the integer 3, --arg enabled=true becomes a boolean, and --arg domain=example.com stays a string. A pair without a key is ignored. For command, the target is JSON: '["/bin/true"]' for one command, or a list of lists to run several in order. For script, args.argv is the argument list.
Without --wait, the command only queues and returns 0. With --wait, it polls for up to 120 seconds and prints the final status and output; exit code is 0 only when the task ended done.
Examples:
aegis tasker run command '["/bin/true"]' --name smokeaegis tasker run internal web.vhost.create --arg vhost_id=3aegis tasker run internal web.vhost.create --arg vhost_id=3 --wait✔ task 58 queuedWith --wait:
✔ task 58 queueddone: vhost createdA failed task followed with --wait:
✔ task 59 queuedfailed: nginx -t rejected the configurationIf it is still running after 120 seconds:
✖ still running; check `aegis tasker show`#aegis tasker cancel
Destructive. A pending task is cancelled and will never run; a running container is stopped before its next step.
Cancels a pending task, or asks a running container to stop.
aegis tasker cancel ID| Argument | Default | Meaning |
|---|---|---|
ID | required | task id |
A pending row becomes cancelled immediately, and so do its steps. A running container gets cancel_requested; the daemon stops before the next step and marks the rest as never run. A running task without steps is already in flight: interrupting it could leave the host in an unknown state, so the command refuses. Any final state is refused too.
Examples:
aegis tasker cancel 58aegis tasker cancel 59ℹ task 58 cancelledA running container:
ℹ task 58 stops after the current stepRefused:
✖ task 58 is done and cannot be cancelled✖ task 58 is running and cannot be cancelled#aegis tasker retry
Puts a finished task back in the queue.
aegis tasker retry ID| Argument | Default | Meaning |
|---|---|---|
ID | required | task id |
Only a whole task whose status is failed, cancelled or interrupted can be retried. The row keeps its id, the status becomes pending, the steps are reset, and the previous attempt stays in the log with a line saying who asked for another run. done and still-running tasks are refused.
Examples:
aegis tasker retry 56aegis tasker retry 56 && aegis tasker show 56ℹ task 56 queued againRefused:
✖ task 56 did not fail; nothing to retry✖ only a whole task can be run again#The task lifecycle
| Status | Meaning |
|---|---|
pending | queued; it may carry a future scheduled_at |
running | claimed by the daemon, or one step of a running container |
done | finished successfully |
failed | finished with an error |
cancelled | cancelled before or during execution |
interrupted | the daemon stopped while the task was running |
done, failed, cancelled and interrupted are final. A new task starts pending; a due root task is claimed and becomes running. Children are created upfront with the plan, so the steps that are about to run are visible before the first one starts.
A container runs its children in order in one worker, so two tasks that touch the same resource never interleave. A failing step marks the remaining steps cancelled with not run: the previous step failed, and the container fails with step N failed: ….
A step marked on_failure is part of the plan but not part of the normal run. It is created upfront and runs only after an earlier step failed; when everything succeeds it is recorded as cancelled with not needed: every step succeeded. A stop requested during a rollback is ignored on purpose: leaving the host half changed is worse than finishing the undo. A rollback step that fails does not stop the others, and its error is reported together with the original one.
A failed task is retried automatically only when its result says the failure is retryable; a validation error never is. The retry goes back to the queue, not to sleep inside a worker: the row becomes pending with a future scheduled_at, and the worker slot is freed. The delay is 5 seconds times the attempt number, capped at 5 minutes, and nothing is retried more than max_retries times.
An operator can stop a running container between steps with cancel, and can put a failed, cancelled or interrupted task back in the queue with retry. Neither operation deletes the log of the previous attempt.
#Housekeeping
arrive.
done and cancelled tasks older than 48 hours are purged on a schedule.failed and interrupted rows are kept: they are what an operator comesback to.
running becomes interrupted.#Files
| Path | Content |
|---|---|
database/storage/tasker/tasker.db | tasks, steps and their log |
database/migrations/core/tasker | schema, one SQL file per change |
<run>/tasker.lock | exclusive lock that keeps a single daemon |
<run>/tasker.pid | pid the keeper reads |
<run>/tasker.heartbeat | rewritten every poll; a stale one means a hung daemon |
<logs>/tasker.log | daemon output when the keeper runs it |