#Tasker — every action as a task
The panel never performs a write in the request that asked for it. It validates the form, stores a task, and the tasker daemon executes it. The page returns immediately, the work appears in the task window, and its output stays in the task log afterwards.
That is not an abstraction for its own sake: a vhost render, a mail domain with a DKIM key, a zone rewrite and a database restart all fail in ways that must be reported somewhere the operator can read afterwards. One queue is easier to reason about than a dozen request handlers that each log differently.
#What a task is
A task is one row in database/storage/tasker/tasker.db. It owns:
| Field | Meaning |
|---|---|
name | what the panel shows |
group_name | section that queued it (web, mail, dns, ftp, database, sys) |
type | how it runs: internal, command, script, webhook |
target | callable name, argv JSON, script path or URL |
args | JSON parameters |
status | pending, running, done, failed, cancelled, interrupted |
output / error_output | what the action answered, or why it failed |
data | JSON the action returned for its caller |
retries / max_retries | attempts made and the limit |
parent_id / position | the step tree |
resource | what is being touched, for reading the queue |
actor | panel account that asked |
| timestamps | created_at, started_at, scheduled_at, completed_at, failed_at |
A task with children is a container: it has no work of its own. The children are created with the plan, before anything runs, so the panel can show the steps that are about to happen instead of a list that grows while you watch.
#The four types
| Type | target | Notes |
|---|---|---|
internal | a name registered in app/modules/tasker/registry.py | calls a Python function, 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 | non-accepted status is a failure |
internal is what the panel uses. A command task exists for maintenance that only a shell command can do, and a webhook task for notifying something outside the host.
#Steps, failure and rollback
Children run in order, in one worker, so two tasks that touch the same resource never interleave. A failing step marks the remaining ones 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 visible), runs only after an earlier step failed, and is recorded as cancelled with not needed: every step succeeded when the task worked. That is how a task that created half a zone before failing can undo it:
store.create( name="create zone example.com", type="internal", group="dns", plan=[ {"name": "write the zone", "type": "internal", "target": "dns.zone.create", "args": {...}}, {"name": "publish the records", "type": "internal", "target": "dns.record.add", "args": {...}}, {"name": "delete the zone again", "type": "internal", "target": "dns.zone.delete", "args": {...}, "on_failure": True}, ],)A stop requested during the 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.
#Retries
A failed task is retried only when its result says the failure is retryable (a validation error never is). Retries go back to the queue, not to sleep inside a worker: the row becomes pending again with a future scheduled_at, the worker slot is freed, and the panel shows a queued task rather than a stuck one.
The delay is 5s × attempt, capped at 5 minutes. Nothing is retried more than max_retries times; after that the task fails and stays in the history.
#Cancel and retry from the panel
The floating window offers two buttons per row:
| Status | Button | What happens |
|---|---|---|
pending | Cancel | the row becomes cancelled immediately, its steps too |
running (with steps) | Stop | cancel_requested is set; the daemon stops before the next step and marks the rest as never run |
failed, cancelled, interrupted | Retry | the same row goes back to pending, its steps reset, the previous attempt stays in the log |
A running task without steps cannot be stopped: the call is already in flight and interrupting it would leave the host in an unknown state. The API answers that plainly instead of pretending.
#The window and the bell
Every page carries the same component (js/components/tasker.js):
/api/tasker/feed once every 1.2 s, for the window and the belltogether;
otherwise end between two polls and never be seen;
its position in localStorage;
1 task: deleting vhost) instead ofshowing a bare count, and a click expands it again;
Clicking a row opens the task: status, type, group, actor, attempts, steps, and the log.
#The task page is live
Each stored log line and each status change is published on the private Bird topic tasker (see live.md). The task page subscribes and prepends new lines, then reloads once when the task reaches a final status — the steps table, the output block and the Retry button are rendered server-side, and one reload keeps them correct.
#Command line
aegis tasker status # counts per stateaegis tasker list --limit 20 # recent tasksaegis tasker show 42 --lines 40 # one task with its logaegis tasker run command '["/bin/true"]' --name smokeaegis tasker run internal web.vhost.create --arg vhost_id=3aegis tasker cancel 42 # stop a pending task, or a running containeraegis tasker retry 42 # queue a failed task againaegis tasker daemon # run the loop in the foregroundrun --wait follows the task in the foreground and exits with its status.
#Files and supervision
| Path | Content |
|---|---|
database/storage/tasker/tasker.db | tasks and their log |
database/migrations/core/tasker | schema, one file per change |
<run>/tasker.lock | the lock that keeps a single daemon |
<run>/tasker.pid | pid the keeper reads |
<run>/tasker.heartbeat | rewritten every tick; a stale one means a hung daemon |
<logs>/tasker.log | daemon output |
The daemon is a keeper service like any other: writes_pid=True, so it publishes its own pid, and a heartbeat the keeper judges. A closed daemon is restarted like any dead service; a hung one (alive pid, stale heartbeat for 90 s) is killed and restarted too. See keeper.md.
#Housekeeping
done and cancelled tasks older than 48 hours are purged on a schedule.failed and interrupted rows are not purged: they are what an operatorcomes back to. Management → Tasker → Clear failed removes them on purpose.
running become interrupted — a task cannot beresumed safely, and saying so is honest.
#Adding an action
app/modules/tasker/actions/<area>.py: @registry.action("mail.alias.add") def alias_add(context, args) -> ActionResult: ... return success("alias added", data={"source": source})app/modules/tasker/actions/__init__.py;The function receives ActionContext (config, actor, task_id) and the task's args, and returns success(...), failure(...) or partial(...) from app/helpers/result.py. Raising is allowed: the runner turns the exception into a failed task with the traceback in its error output.