Node Credentials
Every self-hosted Nexomatic service — a sink agent on a Linux box, a source engine in your data centre — authenticates to the Hub with a Client ID / Client Secret pair that belongs to a node row on the Nodes screen. The Nodes screen is the only issuer of these credentials: the Hub checks each credential against the rows in the portal database.
If a node row is deleted (for example by the platform janitor after the service stopped heartbeating for a long time), the service’s old credentials stop working and it will fail with UNAUTHENTICATED: Invalid credentials. The fix is to create a new node and point the service at its credentials — this guide covers exactly that.
Create the node
Section titled “Create the node”- Open the Nodes screen in the portal.
- Click Create node and pick the node type your service runs as (a Linux sink runs as
SELF_HOSTED_SINK(the platform’s container images run asPLATFORM_SINK_PYTHON/PLATFORM_SOURCE; match whatever the service was created with)). - Copy the Client ID, Client Secret, and the node type’s UUID from the screen — the UUID goes into the service’s
NODE_TYPE_UUID.
Configure the service
Section titled “Configure the service”All services read their connection settings from environment variables:
| Variable | Meaning |
|---|---|
CLIENT_ID | Client ID of the node you just created |
CLIENT_SECRET | Client Secret of the node |
NODE_TYPE_UUID | UUID of the node type the service registers as |
HUB_HOST / HUB_PORT | Hub address (default localhost:50051) |
SERVER_URL | Controller HTTP URL (for config, binaries, and updates) |
ROOT_FOLDER | Working directory — identity files live in <ROOT_FOLDER>/nexomatic_data/ |
Linux sink (systemd)
Section titled “Linux sink (systemd)”The service unit is installed at:
/etc/systemd/system/nexomatic-sink.serviceTwo ways to update its credentials:
Option A — re-run the installer (rewrites the unit with the new values and restarts the service):
curl -fsSL https://<controller-url>/api/install-linux-service.sh | \ sudo bash -s -- --controller-url https://<controller-url> --client-secret <new-client-secret>Option B — edit the unit directly, then reload and restart:
sudo nano /etc/systemd/system/nexomatic-sink.service# update the CLIENT_ID, CLIENT_SECRET, and NODE_TYPE_UUID Environment= linessudo systemctl daemon-reloadsudo systemctl restart nexomatic-sinkOther services
Section titled “Other services”Set the same variables in whatever environment your service launches from (shell profile, .env file, container environment, or systemd unit), then restart it.
Stale identity file
Section titled “Stale identity file”A service persists its node identity in <ROOT_FOLDER>/nexomatic_data/node_uuid. When moving a service to a brand-new node, deleting this file is recommended so the old identity can’t cause confusion:
sudo rm /opt/nexomatic-sink/nexomatic_data/node_uuid # Linux sink installs(With valid new credentials the Hub’s authentication takes over anyway, but a clean slate avoids revival edge cases.)
Verify
Section titled “Verify”Restart the service and check the Nodes screen. The node should flip to ONLINE within a couple of minutes — the Hub flushes heartbeats to the database every ~2 minutes. Check the service log for errors meanwhile:
journalctl -u nexomatic-sink -fTroubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
UNAUTHENTICATED: Invalid credentials | No node row matches the configured Client ID / Secret — the row was deleted, or a typo | Create a new node and update CLIENT_ID / CLIENT_SECRET |
NOT_FOUND on registration | NODE_TYPE_UUID doesn’t match an existing node type | Copy the UUID from the Nodes screen |
| Node stays OFFLINE | Heartbeats aren’t reaching the Hub | Check HUB_HOST / HUB_PORT, network, and the service log |
| Node disappears after weeks of uptime | The service stopped heartbeating (crash, network cut) and the janitor pruned the stale row — expected behaviour | Re-credential the service using this guide |
See also Sinks & Placement and the platform install guides under Sinks.