Choose an implementation
An AWL worker document serves command bodies with typed contracts. The shell worker uses a strict manifest plus the source AWL contract. An agent worker reads the workflow’s queue, action and harness declarations.
Rust, Python and TypeScript SDKs let you implement external activities. The separate MCP worker package bridges declared stdio MCP tools into activities. It validates declared tool arguments and results; URL-based MCP servers are refused by that bridge.
The bridge is an activity implementation. It is distinct from Aion’s public MCP endpoint, which exposes workflow operations to a caller.
Check before connecting
The AWL and agent worker check modes print the resolved advertisement without connecting. Read its queue, namespace, actions, schemas, node and harness settings.
The action contracts must agree with the deployed workflow. A registration refusal names the mismatch. Do not rename an action or weaken a schema to hide it.
Inspect the live registry
List workers connected to the registry the server dispatches against
aion worker connected [OPTIONS]-
--all-namespaces - Include every namespace instead of filtering to the global `--namespace`
-
--task-queue <TASK_QUEUE> - Optional task queue filter
-
--activity-type <ACTIVITY_TYPE> - Optional activity type filter
- Requires a newer main build; the public 18 September 2026 crate lacks this command.
A connected worker must satisfy capacity, contract and placement requirements.
The namespace ceiling caps claimed rows for parallel and collect members dispatched through an enabled durable outbox. Ordinary single activity calls bypass that count.
The typed outbox default is disabled; the generated first-run config enables it. The namespace ceiling defaults to 1024. Pending outbox rows wait for claim capacity; cluster nodes receive a rounded share based on owned shards.
A successful handoff completes the row while its handler may still execute. Use worker concurrency to bound executing handler slots.
-
Run-wide worker cancellation - On main, crates/aion-server/src/worker/cancel_cascade_hook.rs:150 invokes cancellation for the ended run; worker/activity_cancel.rs:268–284 sends each gRPC CancelActivity frame. These frames serve run-wide cancellation, rather than a public single-activity route.
-
Quota commissioning - On main, crates/aion-server/src/run/outbox_commission.rs:160–162 skips a disabled outbox; lines 212–231 install namespace backpressure only on the enabled dispatcher.
-
Counted dispatches - On main, crates/aion/src/runtime/nif_collect.rs:306–316 stages parallel/collect members through the outbox. runtime/nif_activity_dispatch.rs:448 dispatches an ordinary call directly, outside that count.
-
Defaults - On main, crates/aion-server/src/config/defaults.rs:33 sets the namespace ceiling to 1024. config/sections.rs:940–945 defaults outbox.enabled to false; crates/aion-server/templates/first-run-config.toml:77 enables it.
-
Cluster share - On main, crates/aion-server/src/worker/backpressure.rs computes ceil(namespace quota × owned shards / total shards). Rounding can put aggregate claimed capacity slightly above the nominal quota.
-
Handoff and execution - On main, crates/aion-server/src/worker/outbox_dispatcher.rs:650–677 marks a successfully handed-off row done. worker/dispatch.rs:308–319 defines dispatch success as placement with a worker. The claim ceiling therefore bounds claimed rows; worker concurrency bounds executing handler slots.
Managed supervision
The supervision section requires every restart and stop policy field. A missing policy leaves supervision uncommissioned and reports that state.
Report the managed worker fleet the SERVER supervises.
aion worker status [OPTIONS]Start records desired running state and supervises the process. Stop is terminal until started again, and success requires the server to prove the process group empty. Restart retains desired running state.
See every worker command and supervision settings.
Cancellation and side effects
Aion cannot cancel a single ordinary activity. Workflow cancel stops all of a run’s in-flight activities. A single agent attempt whose harness advertises Cancel can be stopped over HTTP with POST /workflows/intervene; there is no CLI command for this.
Workflow cancel also recursively cancels Running or Paused descendants. Its internal control frames ask every live worker attempt in the ended run to stop. Cooperative handlers observe their cancellation handle; contained command processes receive process-group termination. Drain stops new assignment and lets existing work settle.
See activity control for cancellation and agent intervention. Preserve external idempotency and compensation rules when cancelling work.