KinuxOTA Client

The KinuxOTA client is a small agent that connects a Linux device to your KinuxOTA dashboard. It is a single program, kinuxota, installed as a standard Debian package with a systemd service.

Requirements

  • Ubuntu 22.04 or 24.04 (other Debian-based distributions with the same libraries usually work)

  • amd64 (x86-64). ARM builds (Raspberry Pi and similar) are planned.

  • Outbound internet access to back.kinuxota.com (HTTPS) and mqtt.kinuxota.com (port 27202, TLS)

  • sudo rights for installation

Install

  1. In the dashboard, open Devices → Add Device and create the device. Copy its API key; it is shown only once. The dialog also shows the commands below with the key filled in.

  2. On the device:

curl -fsSLO https://github.com/yaswanthsk04/kinuxota_client/releases/latest/download/kinuxota_amd64.deb
sudo apt install ./kinuxota_amd64.deb
sudo kinuxota enroll --key <API_KEY>

enroll checks the key with the server, saves the configuration and starts the agent. The device appears as Online in the dashboard within a few seconds.

To verify the download first, get SHA256SUMS from the same release and run sha256sum -c SHA256SUMS --ignore-missing.

Commands

Command What it does
sudo kinuxota enroll --key <API_KEY> Connect this device to your account (again) and start the agent
kinuxota status Version, service state and connection to the dashboard (sudo shows more)
kinuxota health CPU, memory, disk and uptime of this device
sudo kinuxota logs [-f] Agent logs (-f to follow)
sudo kinuxota update Install the latest release (--version X.Y.Z for a specific one)
kinuxota version Installed version
kinuxota help All commands

The agent runs as the systemd service kinuxota:

sudo systemctl status kinuxota
sudo systemctl restart kinuxota

Update

Either run sudo kinuxota update on the device, or install a newer .deb with apt as above. Updates keep the device’s enrollment.

Uninstall

sudo apt remove kinuxota          # remove the program, keep the enrollment
sudo apt purge kinuxota           # remove everything, including the API key

Files

Path Contents
/usr/bin/kinuxota The program
/etc/kinuxota/config.json Enrollment: API key, server addresses (readable by root only)
/usr/share/kinuxota/ca.crt Certificate used to verify the KinuxOTA MQTT broker
/etc/kinuxota/ca.crt Optional override of that certificate (self-hosted brokers)
/lib/systemd/system/kinuxota.service The service definition
systemd journal Logs: kinuxota logs or journalctl -u kinuxota

Security

  • All traffic to KinuxOTA is encrypted (HTTPS and MQTT over TLS). The client verifies the server certificates.

  • Each device has its own API key and can only receive its own commands.

  • The agent runs as root because it executes the commands, scripts and package operations you send from the dashboard. Only your account can send them.

Troubleshooting

  • kinuxota status says “API key rejected”: the device was deleted in the dashboard or the key is wrong. Create the device again and re-run sudo kinuxota enroll --key <NEW_KEY>.

  • “unreachable”: check that the device can reach https://back.kinuxota.com (curl -I https://back.kinuxota.com/api/health) and that outbound port 27202 is allowed.

  • The device shows Offline: run sudo kinuxota logs -n 50 and look for Connected to broker successfully.