Configuration

By default, Nexigon Agent loads its configuration from /etc/nexigon/agent.toml. To configure Nexigon Agent, you need to provide the URL to your Nexigon Hub instance as well as a project-specific deployment token. Furthermore, you need to provide a path to a device fingerprint script. The agent will use the output of that script to compute a device-specific fingerprint.

Here is an example:

hub-url = "https://eu.nexigon.cloud"
token = "deployment_UvsBJTcAKWo6LfPXMyDUXA2UvvTjHozDfMT3suY4SosZk2JrgH5JRzCYzX2yPEsRuC"

fingerprint-script = "/usr/libexec/nexigon/nexigon-device-fingerprint"

Device Fingerprints

Device fingerprints are meant to be hardware-specific and never change over the lifetime of a device. If the storage of a device is never replaced and /etc/machine-id is persisted, then you may use the following script:

#!/usr/bin/env bash

set -euo pipefail

cat "/etc/machine-id"

Feature Configuration

Several agent features are optional. Enable only the capabilities you want a device to expose.

To allow Nexigon to run device commands, enable commands and point the agent at a directory of command definition files:

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

To let the agent pick up device-executable operation steps, configure operation polling:

[operations]
enabled = true
poll-interval-secs = 60

Operation polling and commands are both disabled by default. DeviceCommand steps only work when both are enabled and the referenced command exists on the device. The bundled agent does not execute DeviceTask steps.

TCP Forwarding

Starting with Agent 0.6, devices permit TCP forwarding only to explicitly configured ports. Declaring an HTTP export both advertises the service in the UI and permits access to its port:

[[exports]]
name = "Web UI"
protocol = "http"
port = 80

To allow additional TCP ports, such as SSH, enable the forwarding allowlist:

[forwarding]
enabled = true
allowed-tcp-ports = [22]

The permitted ports are the HTTP export ports plus the enabled additional allowlist. Missing forwarding configuration, enabled = false, or a missing or empty allowlist grants no additional ports. Exported ports remain accessible regardless of forwarding.enabled. Remove an export to stop granting access through it. With no exports and no enabled allowlist, all forwarding is denied.

Targets are restricted to 127.0.0.1, and destination ports must be integers from 1 through 65535. Wildcards and ranges are not supported. Both exports and the additional allowlist permit raw TCP access, including CLI forwarding. An export’s HTTP protocol and URL path do not restrict traffic on that port. Hub remote-access permissions also apply; generating a URL in the Hub does not change the device’s policy. The browser terminal is configured separately and does not require forwarding port 22.

Upgrading from Agent 0.5

Deploy the new binary and configuration together, then restart the Agent. Existing exports keep their ports accessible, while other ports require the additional allowlist. Older Agents do not enforce this policy; rolling back restores their unrestricted forwarding behavior.

TCP Forwarding Capacity

Agent 0.6 defaults to 512 multiplex channels. It advertises 480 channels for forwarding, leaving 32 available for RPC, commands, terminals, and control work. For device HTTP proxy requests, Hub 2026.3.2 or later opens channels immediately up to the lower of its configured limit and the advertised capacity, then queues overflow requests before opening a device channel.

Configure Capacity

Keep the defaults unless a device has tighter file-descriptor or local-service concurrency limits:

[multiplex]
max-channels = 512
reserved-channels = 32
max-channel-requests-per-second = 2048

max-channels must be between 32 and 4096. reserved-channels must be positive and lower than max-channels. It reduces advertised forwarding capacity but does not partition transport channels by feature. max-channel-requests-per-second must be between 32 and 65536 and at least as large as max-channels. An incoming channel-open request beyond that rate is rejected without disconnecting the Agent.

Nexigon-provided systemd units set the Agent’s open-file limit to 8192. A custom service definition must provide enough file descriptors for the configured capacity and the Agent’s other work.

Upgrade Order

Upgrade a Hub to 2026.3.2 before upgrading its Agents to 0.6. The Hub applies the lower of its configured limit and a legacy device HTTP proxy cap of 24 to older Agents. An older Hub ignores capacity metadata, so Agent 0.6 remains compatible but does not gain the higher forwarding limit.