Skip to content

Core Concepts

This page explains the core entities you will work with when building automations. Understanding these concepts makes the UI and configuration straightforward.


An Event is a single unit of work. It is created when a Source fires and carries:

  • A Flow — what kind of task should run
  • A payload — a JSON document of data passed to the executing module
  • A state — tracks where the event is in its lifecycle
StateMeaning
QUEUEDWaiting for a node to pick it up
RUNNINGA Sink is currently executing the task
SUCCESSCompleted successfully
WARNINGCompleted with warnings
ERRORFailed
TIMED_OUTSuperseded by a newer schedule firing — the event was queued but never dispatched

Events older than your plan’s retention are moved to the long-term archive, where they stay queryable and filterable; events within the retention window can be queried and filtered on the Runs screen. See Data Retention for how retention works on your plan.


A Node is the machine your automations run on — the first-class entity behind every source and sink. You create nodes on the Nodes screen:

  • a node is either a source node (watches for events: files, MQTT, webhooks) or a sink node (executes actions) — never both;
  • each node has its own client ID + secret (shown once, regenerable) — the installed service authenticates with them;
  • the Nodes screen shows each node’s online/offline status from its heartbeat, its attribute sheet (see below), and what it is currently serving.

Every node carries an attribute sheet — key/value pairs that decide where work can run:

  • Reported attributes (os, arch, engine version, libraries) are written by the node itself at registration and are read-only.
  • User-assigned attributes (e.g. zone, tools) are defined by you on the Nodes screen, with value lists you manage. Values are sanitized and deduplicated; renaming a value updates every node and constraint at once.

See the preset catalog for how attributes drive placement.


A Source is a named, reusable trigger endpoint: a platform preset plus its connection config and a placement.

PresetWhat it does
WebhookAn HTTP POST to the source’s address creates an event
Folder watchA file appearing in watched paths creates an event
MQTTA message on a subscribed topic creates an event
Every day at…A cron expression fires the flow on a schedule
Azure EventGridMessages from an Event Grid topic subscription become events
MCPAI agents using the Model Context Protocol create events

Sources are inherently location-bound: a folder watcher watches that folder, a webhook listens on that address. So a source is either pinned to one of your source nodes or runs on the platform — there is no “any node” for sources. Editing a source edits its connection config (broker address, credentials, cron); every flow using it follows.

The full list with per-preset details: preset catalog. Installation: Sources overview.


A Sink is a named, reusable execution target: a placement plus optional attribute constraints. It exists only when it pins or constrains:

  • Pinned to a node — its steps always run on that node.
  • Any matching node — the step runs on whichever of your sink nodes covers its constraints (e.g. zone=ot).

Bare “any matching node” and “platform” are always-available choices in the flow builder’s placement picker — they are never stored as sinks. Install a sink agent with the Installing Sinks guides.


A Flow (the user-facing name for what the API calls an Event Type) is a sentence:

  • WHEN — the sources that fire it: one per source type, each firing the flow independently (watch paths and topics per source, the cron on the schedule source, each with its own config block)
  • DO — the action to run, on a placement (a sink, any matching node, or platform)
  • THEN — follow-up steps: if an action succeeds or fails, run another action on a placement

Create and edit happen on the same full-screen editor (the Flows screen): the grid is the default view, and creating or opening a flow slides the editor in. A new flow saves with its sources, steps, and chain in one go. Test this flow fires one real test event through the flow’s dispatch path — it appears on the Runs screen and counts toward plan usage.

Parameters are configured on the Action, never on the flow — see Actions.


An Action defines the code that executes when a Flow fires. It is a pure, reusable definition:

  • A module — a reference to a Library Module that contains the code to execute
  • Parameters — ordered key/value pairs injected at runtime (STATIC / DATA / SECRET)

An action is pinned to a library version line: it references the module on a specific library row. A patch (bugfix) release updates that row in place, so flows follow bugfixes automatically; a major or minor release is a new row, so flows stay on their line until you switch the action to the newer line explicitly. The flow builder’s action pickers show each action’s line (Action — library v1.2.0).

Chaining is defined per flow, because the same action means different follow-ups in different flows. A chain link is:

(from action, success|failure) → (next action, on …)
  • Fan-out: an action can have several successors per outcome — each runs as an independent branch, in the order you set.
  • On: a named sink, any matching node, or platform — every step carries its own placement.
  • Depth: a chained action can itself chain further.

When an action finishes, the sink reports the outcome and result data. The Hub resolves the flow’s links and creates one chained event per matching link — the result data becomes the payload. No matching link → the run ends.

flowchart TD W["Webhook fires"] S1["copyfile"] S2["process"] S3["sendmail"] W --> S1 S1 -->|success| S2 S1 -->|failure| S3

See the Actions & Libraries guide for a full walkthrough.

Every event of a single trigger run shares a run id, stamped on the root event and inherited by every chained event — including fan-out branches. The Runs screen is one row per run; open a run to see the whole chain as a tree in its trace. The trace’s log search shows the Flow and Action columns so each log entry points at its step.


Placement — how “where does this run” is decided

Section titled “Placement — how “where does this run” is decided”

For every step, the hub checks one thing: the step’s constraints are a subset of a node’s attributes.

  • The step’s needs fall out of the action’s library requirements (the platform library declares them).
  • The sink’s constraints add attribute filters (e.g. zone=ot).
  • Any matching node picks one node from the matching pool and fails over inside the pool; a pinned node never falls back to the platform; work with no match is held and flagged on the flow.

See the preset catalog for the details.


A Library is a named collection of code modules, in a specific version line. Each library declares the runtime requirements its modules need (engine, minimum version, OS families) — an action’s needs fall out of its module’s library.

Platform libraries are consumed directly — actions reference their modules, bugfix patches are picked up automatically, and major/minor lines never auto-bump your flows. Custom libraries are created and edited on the Libraries screen (see Actions & Libraries).

A Library Module is a single importable code unit within a library — the entity an Action references as its executable code. Modules can carry a description, shown as helper text in pickers.

The relationship chain is:

Library → Module → Action → Flow step

Scheduling happens through the Every day at… source preset — there is no separate Schedules screen. Create a source from the preset, set its cron expression in the source’s connection config, and every flow using that source fires on the schedule. Editing the source’s cron updates every flow using it at once.

Cron expressions follow standard 5-field format:

┌───── minute (0-59)
│ ┌──── hour (0-23)
│ │ ┌─── day of month (1-31)
│ │ │ ┌── month (1-12)
│ │ │ │ ┌─ day of week (0-6, Sunday=0)
* * * * *
ExpressionMeaning
0 9 * * 1-5Every weekday at 09:00
*/15 * * * *Every 15 minutes
0 0 1 * *First day of every month at midnight

Secrets are tenant-scoped key/value pairs stored securely in Nexomatic. Values are write-only — they cannot be retrieved through the UI after creation.

Sink modules access secrets at runtime via the Hub. This means credentials never need to be embedded in code or passed in event payloads.

Reference a secret in an Action parameter by setting the parameter type to SECRET and the value to the secret’s key name. Source connection configs resolve SECRET values the same way.


Every task execution produces a Log — structured records written by the module during execution, plus a raw log file containing full stdout output.

Logs are retained for a configurable period. Older logs are transparently archived to blob storage and remain queryable from the global log search (the search all records mode, reachable from the Runs screen header — see the Traces page).