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, an explicit device policy controls TCP forwarding. A policy can export an HTTP service, permit specific additional ports, or permit every port.

Export an HTTP Service

An HTTP export advertises a service in the UI and permits access to its port:

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

Permit Specific Ports

Enable the forwarding allowlist to permit additional TCP ports, such as SSH:

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

Permit Every Port

Permit every TCP destination port when the required ports cannot be listed in advance:

[forwarding]
enabled = true
allow-all-ports = true

Prefer allowed-tcp-ports when the required ports are known so the device exposes only the intended local services.

Policy Behavior

Permitted ports include HTTP export ports and ports granted by an enabled additional forwarding policy. The additional policy grants listed ports and can grant every port with allow-all-ports = true. Missing forwarding configuration or enabled = false grants no additional ports. A missing or empty allowlist also grants no additional ports when allow-all-ports is false or omitted.

Exported ports remain accessible regardless of forwarding.enabled. Remove an export to stop granting access through it. With no exports and no enabled forwarding policy, 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 accepted in allowed-tcp-ports. HTTP exports and enabled additional forwarding policies 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 an enabled forwarding policy. 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.