Create a Device Command

Expose a Linux device’s uptime as a command that operators can run through Nexigon. A command consists of a TOML definition and an executable handler. The handler receives JSON input and returns newline-delimited JSON output. Nexigon Agent loads the definition, advertises the command to Nexigon Hub, and starts the handler when an authorized client invokes it. The definition is the contract operators see; the handler connects that contract to your device’s own tools.

You need root access to a connected Linux device with Nexigon Agent, Bash, and systemd. The handler uses Linux’s /proc filesystem; the setup and troubleshooting commands use systemd.

Install the Handler

Create /usr/libexec/nexigon/commands and save this script there:

#!/usr/bin/env bash
set -euo pipefail

read -r uptime_secs _ </proc/uptime
printf '{"type":"Output","data":{"uptime_secs":%s}}\n' "${uptime_secs%.*}"

Make it executable:

chmod 755 /usr/libexec/nexigon/commands/uptime.sh

Run the script directly. It should print an Output object containing the uptime in seconds. Write diagnostic messages to stderr so they do not interfere with the JSON result.

This example accepts no input and reads Linux’s /proc/uptime. The data field of the Output record becomes the command result. When adapting the handler, keep stdout for protocol records and send human-readable diagnostics to stderr. Exit successfully only when the requested work succeeded, so operators and fleet operations can distinguish success from failure.

Define the Command

Create /etc/nexigon/agent/commands and save:

[command]
name = "uptime"
description = "Get system uptime in seconds"
category = "diagnostics"

[exec]
handler = ["/usr/libexec/nexigon/commands/uptime.sh"]
timeout = 5

Keep the definition, handler, and their resolved parent directories owned by root or the agent user and protected from group or world writes. Nexigon Agent skips definitions that fail these checks. The definition limits this handler to five seconds. These checks matter because command handlers run with the agent’s privileges; an untrusted write to the definition or executable could change what a remote invocation runs.

Enable and Verify the Command

Add this to the agent configuration:

[commands]
enabled = true
directory = "/etc/nexigon/agent/commands"

Restart Nexigon Agent. From a workstation with Nexigon CLI configured, check the device’s published commands:

nexigon-cli devices commands list <device-id>

Confirm that uptime appears, then invoke it from the device’s command interface in Nexigon. A successful result contains uptime_secs. If it is missing, inspect journalctl -u nexigon-agent for loading errors.

See Device Commands for definition fields, input and output schemas, timeouts, and the handler protocol. To run this command across several devices, follow Run a Fleet Operation.