Aegis documentation

#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

TypetargetBehaviour
internala name registered in app/modules/tasker/registry.pycalls a Python action; keeps validation and rollback
commandan argv list, or a list of argv listsno shell; several lists run in order
scriptan absolute pathargs.argv is passed as arguments
webhookan http(s) URLa 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.

bash
aegis tasker daemon
Argument / optionDefaultMeaning
——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:

bash
aegis tasker daemoncd /etc/aegis && ./bin/aegis tasker daemon

The loop itself prints nothing: the work appears in the task table, and the keeper records the service start in its own log:

text
2026-11-17 10:36:07 aegis-tasker: started (pid 8123)

#Inspecting the queue

#aegis tasker status

Counts the root tasks in each state.

bash
aegis tasker status
Argument / optionDefaultMeaning
——no arguments or options

Steps are not counted; only rows without a parent appear here.

Examples:

bash
aegis tasker statusaegis tasker status && aegis tasker list --limit 5
text
ℹ cancelled: 1ℹ done: 128ℹ failed: 2ℹ pending: 3ℹ running: 1

With an empty history:

text
ℹ no task has run yet

#aegis tasker list

Lists recent root tasks, newest first.

bash
aegis tasker list --limit N
Argument / optionDefaultMeaning
--limit20how many root tasks to show

Steps are not listed here. The attempts column is retries/max_retries.

Examples:

bash
aegis tasker listaegis tasker list --limit 50
text
id  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:00

With no tasks:

text
ℹ no task has run yet

#aegis tasker show

Shows one task, its steps and its newest log lines.

bash
aegis tasker show ID --lines N
Argument / optionDefaultMeaning
IDrequiredtask id
--lines40how 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:

bash
aegis tasker show 58aegis tasker show 58 --lines 200
text
ℹ 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 reloaded

A failed task also prints the error on stderr:

text
ℹ deploy site [failed] internal✖ nginx -t rejected the configuration

An unknown id exits 1:

text
✖ no task 999

#Changing the queue

#aegis tasker run

Queues one task immediately.

bash
aegis tasker run TYPE TARGET --name NAME --group GROUP                         --arg K=V --retries N --wait
Argument / optionDefaultMeaning
TYPErequiredinternal, command, script or webhook
TARGETrequiredcallable name, argv JSON, script path or URL
--name<type>: <first 40 characters of target>name shown in the panel and the list
--groupclisection that owns the task
--argemptyK=V pair; repeatable
--retries0maximum automatic retries
--waitofffollow 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:

bash
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
text
✔ task 58 queued

With --wait:

text
✔ task 58 queueddone: vhost created

A failed task followed with --wait:

text
✔ task 59 queuedfailed: nginx -t rejected the configuration

If it is still running after 120 seconds:

text
✖ 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.

bash
aegis tasker cancel ID
ArgumentDefaultMeaning
IDrequiredtask 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:

bash
aegis tasker cancel 58aegis tasker cancel 59
text
ℹ task 58 cancelled

A running container:

text
ℹ task 58 stops after the current step

Refused:

text
✖ 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.

bash
aegis tasker retry ID
ArgumentDefaultMeaning
IDrequiredtask 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:

bash
aegis tasker retry 56aegis tasker retry 56 && aegis tasker show 56
text
ℹ task 56 queued again

Refused:

text
✖ task 56 did not fail; nothing to retry✖ only a whole task can be run again

#The task lifecycle

StatusMeaning
pendingqueued; it may carry a future scheduled_at
runningclaimed by the daemon, or one step of a running container
donefinished successfully
failedfinished with an error
cancelledcancelled before or during execution
interruptedthe 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

  • A task keeps at most 2000 log lines; older lines are dropped as new ones
  • 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 comes
  • back to.

  • On daemon start, every row left running becomes interrupted.
  • #Files

    PathContent
    database/storage/tasker/tasker.dbtasks, steps and their log
    database/migrations/core/taskerschema, one SQL file per change
    <run>/tasker.lockexclusive lock that keeps a single daemon
    <run>/tasker.pidpid the keeper reads
    <run>/tasker.heartbeatrewritten every poll; a stale one means a hung daemon
    <logs>/tasker.logdaemon output when the keeper runs it