Skip to main content

Commands

Commands allow you to execute on-demand operations on a device remotely. A command receives a JSON input, runs logic on the device, and returns a JSON output along with a status and log output. Commands can be used for diagnostics, maintenance, deployments, and anything else that requires an imperative action on a device.

Enabling Commands​

Commands are disabled by default. To enable them, add the following to your agent configuration:

/etc/nexigon/agent.toml
[commands]
enabled = true

Custom Commands​

Custom commands are defined as TOML files in the commands directory (by default /etc/nexigon/agent/commands). Each file defines a single command with its metadata, optional input/output schemas, and an executable handler.

/etc/nexigon/agent/commands/uptime.toml
[command]
name = "uptime"
description = "Get system uptime and load average"
category = "diagnostics"

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

The handler is an array where the first element is the executable and the remaining elements are arguments. The timeout specifies the maximum execution time in seconds (defaults to 30).

You can optionally specify JSON Schemas for the input and output:

/etc/nexigon/agent/commands/restart-service.toml
[command]
name = "restart-service"
description = "Restart a systemd service"
category = "services"

[input]
schema = '{"type": "object", "properties": {"unit": {"type": "string"}}, "required": ["unit"]}'

[exec]
handler = ["/usr/libexec/nexigon/commands/restart-service.sh"]
timeout = 30

The schemas are published as part of the command manifest and can be used by the UI and API clients for validation.

Handler Protocol​

The handler executable communicates with the agent via stdin, stdout, and stderr:

  • Stdin: The JSON input is written as a single line. If the input is null, stdin is closed immediately.
  • Stdout: The handler writes NDJSON lines. Each line is a JSON object with a type field. Currently, the only supported type is Output: 
    { "type": "Output", "data": { "uptime_secs": 86400, "load": "0.5 0.3 0.2" } }
    If multiple Output lines are written, the last one is used as the command result. Unknown types are silently ignored for forward compatibility.
  • Stderr: Captured as a log tail (last 8 KB) and included in the result. Use stderr for progress messages and diagnostics.

The exit code determines the command status: zero means success, non-zero means error.

Here is a complete example:

/usr/libexec/nexigon/commands/uptime.sh
#!/usr/bin/env bash
echo "Collecting uptime info..." >&2
uptime_secs=$(cat /proc/uptime | awk '{print int($1)}')
load=$(cat /proc/loadavg | awk '{print $1, $2, $3}')
echo "{\"type\": \"Output\", \"data\": {\"uptime_secs\": ${uptime_secs:-0}, \"load\": \"${load:-unknown}\"}}"

Custom Commands Directory​

The commands directory can be changed in the agent configuration:

/etc/nexigon/agent.toml
[commands]
enabled = true
directory = "/opt/my-commands"
warning

For security, Nexigon Agent skips world-writable command files.

Command Manifest​

When commands are enabled, the agent publishes a manifest of all available commands as the device property dev.nexigon.commands. This makes commands discoverable through the same properties system used for all other device metadata.

Precedence​

If a custom command has the same name as a built-in or integration command, the custom command takes precedence. This allows you to override any built-in behavior with your own implementation.