Skip to content

Sink Agents

A Sink is an agent process that runs inside your infrastructure and executes automation tasks dispatched by the Hub. Sinks connect outbound to the Hub over a persistent connection — no inbound firewall rules are required on your network.


When you start a Sink agent it:

  1. Authenticates with the Hub using its credentials
  2. Registers itself and announces what types of tasks it can handle
  3. Opens a persistent outbound stream to the Hub and waits for tasks
  4. Receives Task Requests, executes the configured module, and sends results back

The Hub tracks which sink nodes are online and routes events only to nodes whose attributes cover the step’s needs and constraints. If no matching node is online, events are held safely until one becomes available — never moved to the platform.


What a sink node can execute is determined by its attributes — the runtimes and libraries its engine reports at registration (e.g. PowerShell 5.1, Python 3.11) plus the attributes you assign (e.g. zone=ot). An action’s needs fall out of its library’s declared requirements; the hub matches the two. See Sinks & Placement and the preset catalog.


Choose the deployment model that fits your environment:

PlatformGuideNotes
WindowsInstall on WindowsRuns as a Windows Service; supports self-updating
LinuxInstall on LinuxRuns as a systemd unit; supports self-updating
Kubernetes / DockerContainer OrchestrationRuns as a Deployment; managed by Helm or docker-compose

A sink row’s placement is pool by default (balanced across your live sink nodes) or pinned to one node. The platform placement is offered only when your plan carries platform capacity; otherwise the option is hidden. Your plan also caps how many sinks and how many self-hosted sink nodes you can attach — see Billing & Subscription.


Once a sink agent is running and connected, it appears on the Sinks screen in the UI. Status values:

StatusMeaning
ONLINEConnected and accepting tasks
OFFLINENot connected
RESETTINGGraceful restart in progress
KILLINGGraceful shutdown in progress
KILLShut down — the graceful shutdown completed and the row is retired
FORCE_KILLINGImmediate shutdown in progress

Before installing a sink agent, several things must be set up in Nexomatic. Work through these in order:

A sink node must exist before you can connect any agent — create one on the Nodes screen; its client id + secret are what the agent authenticates with (shown once). The node’s attributes (its engine’s runtimes and libraries, reported at registration) decide which actions it can run. See Sinks & Placement for a step-by-step guide.

The platform libraries (nexo-shell, nexo-file) are ready to use — actions reference their modules directly, and each library declares the runtime requirements its modules need. See Actions & Libraries for details.

You will need the following values during installation:

ItemWhere to find it
Hub hostname and portProvided by your admin (e.g. hub.example.com:50051)
CLIENT_IDFrom the Nodes screen — the node you created for this host (see the Nodes reference)
CLIENT_SECRETThe one-time secret displayed when you created the node. If lost, regenerate it from the Nodes screen
TENANT_UUID (optional)Your tenant’s UUID — only needed to pin the sink to a single tenant
TENANT_SECRET (optional)Registration secret — required if your tenant enforces node auth

Actions (referencing Library Modules) and Flows (linking triggers to Actions) define what the agent does when it receives a task. These can be created before or after installation, but the agent won’t execute anything until they exist. See Getting Started for the full workflow.