Install on Linux
The Linux sink runs as a systemd service and starts automatically on boot. It uses a single pre-built binary — no Python runtime or virtual environment needed. It supports self-updating: new versions are applied automatically when signalled by the Hub.
Prerequisites
Section titled “Prerequisites”- Linux with systemd (Ubuntu 20.04+, Debian 11+, RHEL 8+, or equivalent)
curlinstalled — the installer auto-installs it on Debian/Ubuntu; other distros must install curl manually- Network connectivity to the Hub host and port (outbound TCP — no inbound rules needed)
- Network connectivity to the controller URL (for downloading the binary and updates)
sudoprivileges- A node created on the Nodes screen, with its Client ID and Client Secret (see Node Credentials)
Quick Install
Section titled “Quick Install”The installer script handles everything: creating the service user, downloading the binary, writing the systemd unit, and starting the service.
curl -fsSL https://<controller-url>/api/install-linux-service.sh | \ sudo bash -s -- --controller-url https://<controller-url> --client-secret <your-client-secret>Replace <controller-url> with your Nexomatic controller hostname and <your-client-secret> with the secret of the node you created on the Nodes screen.
Changing Credentials
Section titled “Changing Credentials”If the node row for this service was deleted (the platform prunes nodes that stopped heartbeating for a long time), the service fails with UNAUTHENTICATED: Invalid credentials. Create a new node on the Nodes screen and re-run the installer with the new --client-secret, or edit /etc/systemd/system/nexomatic-sink.service directly — see Node Credentials for the full procedure.
Step-by-Step Installation
Section titled “Step-by-Step Installation”Step 1 — Obtain the installer
Section titled “Step 1 — Obtain the installer”Download the installer script from your controller or from your organisation’s release server:
curl -O https://<controller-url>/api/install-linux-service.shchmod +x install-linux-service.shAlternatively, your administrator may provide a zip bundle containing the binary and installer together.
Step 2 — Run the installer
Section titled “Step 2 — Run the installer”At minimum you need --controller-url and --client-secret. All other flags have sensible defaults.
sudo ./install-linux-service.sh \ --controller-url https://controller.example.com \ --client-secret <your-client-secret>The installer will:
- Check dependencies (
curl,systemd) - Create the
nexomaticsystem user and group - Create
/opt/nexomatic-sink/with data and logs directories - Download the
nexomatic-sink-linux-x86_64binary from the controller’s downloads API - Create the systemd unit file at
/etc/systemd/system/nexomatic-sink.service - Copy
uninstall.shinto the install dir for later use - Set permissions and enable the service
- Optionally start the service immediately
Step 3 — Confirm in the UI
Section titled “Step 3 — Confirm in the UI”Check the service is running:
systemctl status nexomatic-sinkWithin a few seconds the sink should appear as ONLINE on the Sinks screen in Nexomatic.
Installer Options Reference
Section titled “Installer Options Reference”| Flag | Default | Description |
|---|---|---|
--controller-url | (platform controller) | Controller URL; used to fetch the binary and as the service’s self-update channel |
--client-secret | (required) | Client secret from your node (Nodes screen) |
--client-id | REMOTE:LINUX | Client ID from your node (Nodes screen) |
--hub-host | (platform’s public hub) | Hub gRPC hostname — only override for special setups |
--hub-port | 50051 | Hub gRPC port |
--hub-tls | true | Use TLS for the gRPC connection (the platform’s public hub requires it) |
--no-hub-tls | — | Disable TLS (only for local/plaintext debugging) |
--auth-method | client_credentials | Authentication method: client_credentials, entra_id, google, github, or none |
--max-processes | 4 | Maximum concurrent task processes |
--update-base-url | (none) | Base URL for self-update packages (e.g. https://releases.example.com/nexomatic-sink) |
--node-version | (auto-detected) | Version string written to the VERSION file |
--node-type-uuid | (seeded UUID) | NodeType UUID |
--scripts-folder | (none) | Host folder with your own shell scripts — the script modules resolve bare filenames from it |
--storage-folders | (none) | Space-separated absolute folders the sink’s file actions write — source folders (lock/track files land next to the source) and destinations |
The service runs with a strict sandbox (ProtectSystem=strict): everything outside the install dir and the --storage-folders you list is read-only to the sink. If a file action fails with Read-only file system on a folder you know is writable, that folder is missing from --storage-folders (or from the unit’s ReadWritePaths= line — see Managing the Service).
Environment Variables Reference
Section titled “Environment Variables Reference”These are written to the systemd unit file by the installer. If you need to change them later, edit /etc/systemd/system/nexomatic-sink.service and run sudo systemctl daemon-reload && sudo systemctl restart nexomatic-sink.
| Variable | Required | Description |
|---|---|---|
HUB_HOST | Yes | Hub gRPC hostname or IP |
HUB_PORT | Yes | Hub gRPC port (default 50051) |
HUB_TLS | Yes | true to use TLS, empty for plaintext |
CLIENT_ID | Yes | Node client ID from the Nodes screen |
CLIENT_SECRET | Yes | Node client secret from the Nodes screen |
CLIENT_TYPE | Yes | The node’s kind (REMOTE:LINUX for sink installs) |
AUTH_METHOD | Yes | client_credentials, entra_id, google, github, or none |
ROOT_FOLDER | Yes | Installation root (/opt/nexomatic-sink) |
NODE_TYPE_UUID | Yes | NodeType UUID for identity |
LOOP_INTERVAL | No | Polling interval in seconds (default 10) |
MAX_PROCESSES | No | Maximum concurrent tasks (default 4) |
LOG_RETENTION_DAYS | No | Days to retain local logs (default 7) |
SCRIPTS_FOLDER | No | Host folder with your own shell scripts |
NODE_VERSION | No | Installed version string |
UPDATE_BASE_URL | No | Base URL for self-update downloads |
How the Binary Is Obtained
Section titled “How the Binary Is Obtained”The installer downloads the sink binary from the controller’s Downloads API:
- The installer calls
GET /api/v1/downloads/latest/linux/nexomatic-sink-linux-x86_64/url - The controller returns a presigned URL (time-limited download link)
- The installer downloads the binary from the presigned URL
- The binary is placed at
/opt/nexomatic-sink/nexomatic-sink-linux-x86_64and made executable
If you have a bundled zip (binary + installer), the installer uses the local binary instead of downloading.
Automatic Updates
Section titled “Automatic Updates”When --update-base-url is configured, the sink checks for newer versions at startup and when signalled by the Hub. The update process:
- Finish any in-progress tasks
- Download the new package zip from the update base URL
- Extract it over the existing installation
- Call
sys.exit(0)— systemd’sRestart=alwaysrestarts the service with the new code
No manual action is required. The service will be briefly offline during the update.
Managing the Service
Section titled “Managing the Service”# View status and recent logssystemctl status nexomatic-sink
# Follow live logsjournalctl -u nexomatic-sink -f
# Stop / start / restartsudo systemctl stop nexomatic-sinksudo systemctl start nexomatic-sinksudo systemctl restart nexomatic-sinkTo grant the service access to another folder after install (for file actions), add it to the unit’s ReadWritePaths= line and reload:
sudo systemctl edit nexomatic-sink# [Service]# ReadWritePaths=/opt/nexomatic-sink /opt/filewatch /opt/filedestsudo systemctl daemon-reload && sudo systemctl restart nexomatic-sinkUninstalling
Section titled “Uninstalling”The installer copies an uninstall script into the install dir — the clean path is:
sudo /opt/nexomatic-sink/uninstall.sh # removes the service and filessudo /opt/nexomatic-sink/uninstall.sh --keep-data # same, but keeps logs and dataTo uninstall by hand:
sudo systemctl stop nexomatic-sinksudo systemctl disable nexomatic-sinksudo rm /etc/systemd/system/nexomatic-sink.servicesudo systemctl daemon-reloadsudo rm -rf /opt/nexomatic-sinksudo userdel nexomaticTo keep logs and data files, back up /opt/nexomatic-sink/nexomatic_data/ before removing.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Service fails to start | Binary not executable or missing | Check /opt/nexomatic-sink/nexomatic-sink-linux-x86_64 exists and has execute permissions |
OFFLINE in UI | Cannot reach Hub | Test connectivity: nc -zv <hub-host> 50051 |
| Immediately restarts | Bad credentials | Check journalctl -u nexomatic-sink -n 50 for auth errors |
| Tasks not appearing | Node not registered | Confirm CLIENT_ID/CLIENT_SECRET match the node on the Nodes screen |
| TLS errors | Wrong TLS setting | If connecting to a plaintext port, use --no-hub-tls |
File action fails with Read-only file system on a writable folder | The folder is outside the unit’s sandbox | Add it to --storage-folders (installer) or to ReadWritePaths= in the unit — see Installer Options Reference |