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.
How a Sink Works
Section titled “How a Sink Works”When you start a Sink agent it:
- Authenticates with the Hub using its credentials
- Registers itself and announces what types of tasks it can handle
- Opens a persistent outbound stream to the Hub and waits for tasks
- 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 can run
Section titled “What a sink can run”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.
Deployment Options
Section titled “Deployment Options”Choose the deployment model that fits your environment:
| Platform | Guide | Notes |
|---|---|---|
| Windows | Install on Windows | Runs as a Windows Service; supports self-updating |
| Linux | Install on Linux | Runs as a systemd unit; supports self-updating |
| Kubernetes / Docker | Container Orchestration | Runs 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.
Sink Status
Section titled “Sink Status”Once a sink agent is running and connected, it appears on the Sinks screen in the UI. Status values:
| Status | Meaning |
|---|---|
ONLINE | Connected and accepting tasks |
OFFLINE | Not connected |
RESETTING | Graceful restart in progress |
KILLING | Graceful shutdown in progress |
KILL | Shut down — the graceful shutdown completed and the row is retired |
FORCE_KILLING | Immediate shutdown in progress |
What You Need Before Installing
Section titled “What You Need Before Installing”Before installing a sink agent, several things must be set up in Nexomatic. Work through these in order:
1. Create a sink node
Section titled “1. Create a sink node”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.
2. Have the libraries you need
Section titled “2. Have the libraries you need”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.
3. Gather Connection Details
Section titled “3. Gather Connection Details”You will need the following values during installation:
| Item | Where to find it |
|---|---|
| Hub hostname and port | Provided by your admin (e.g. hub.example.com:50051) |
CLIENT_ID | From the Nodes screen — the node you created for this host (see the Nodes reference) |
CLIENT_SECRET | The 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 |
4. Create Actions and Flows
Section titled “4. Create Actions and Flows”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.