How Mono Agent
Is Actually Built

Trigger

A run starts from the CLI, the desktop app, an MCP tool or the HTTP API, from a cron schedule, or from a webhook on 127.0.0.1:9321/webhook/<path>. Scheduled and webhook triggers only fire while monoagentcli daemon is running. workflow run --input passes trigger data.

Queue and DAG

The request enters the execution queue (capacity 1,000) and a worker picks it up; the engine runs 3 at once by default and never more than 20. The workflow graph is loaded, sorted topologically by in-degree, and a cycle is rejected when the DAG is built. workflow validate runs these checks without saving or running anything.

monoagentcli workflow validate <id>

Sequential execution loop

Nodes run in topological order on a single goroutine per execution. There is no parallel branch fan-out, and merge nodes are driven by waiting counters in that loop. A disabled node is skipped.

Expressions

String config fields go through text/template with a function map. $json is the current item, $node["Name"].json.field reads a named node's first output item, and $workflow.id and $execution.id are available. $env.VAR resolves to empty unless MONOAGENT_ALLOW_ENV_TEMPLATES=1.

{{$json.username}}
{{$node["Search"].json.title}}
{{upper $json.name}} {{default "n/a" $json.email}}

Node execution

The registry resolves the node type. Browser and social nodes run an action definition through the extension bridge, with three selector tiers: Go bot code, XPath alternatives, then an opt-in Jev element picker. The old ai.* nodes are deprecated stubs that fail with a hint to use agent.ask or ai.choose.

Human-in-the-loop

core.human_in_loop pauses each incoming item into a durable SQLite queue that survives restarts, and the run shows WAITING. Approve or reject from the CLI, the desktop app, MCP or the HTTP API. You can mark fields editable, set a timeout (expiry counts as a rejection), and the node releases its worker slot while it waits.

monoagentcli hil list | approve | reject

Errors

Each node has an on_error policy: stop, continue, skip, or an error branch. A run with non-fatal failures finishes as SUCCESS_WITH_ERRORS. Per-node outputs are saved in workflow_execution_nodes, and executions are pruned to the last 500 per workflow hourly. WAITING executions are never pruned.

Resume and recovery

Paused executions persist their resume state. The engine runs resume, stale-reap and webhook-retry loops, and workflow cancel and retry are available from the CLI.