Configuration

Nexigon Agent reads TOML configuration from /etc/nexigon/agent.toml by default. This page describes credentials, device identity, and optional features. For installation, follow Getting Started.

Connection Settings

Every device needs an executable fingerprint script that identifies it consistently. Static deployments also set a Nexigon Hub URL and a deployment token:

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

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

Server Certificates

Nexigon Agent verifies the certificate of Nexigon Hub and of every other HTTPS endpoint, such as storage URLs for repository assets, against the operating system’s trust store. On Linux, the ca-certificates package usually provides this trust store, so keep it up to date in your device images. To connect to a self-hosted Nexigon Hub that uses a certificate from your own certificate authority, add that certificate authority to the system trust store.

Before version 0.6.1, pairing-key provisioning, repository asset uploads, and OTLP export also trusted a list of root certificates compiled into Nexigon Agent. See the Nexigon Agent releases for details.

Credentials

Set both hub-url and token to configure static credentials, or omit both to use provisioned credentials. Setting only one is an error.

Static credentials take precedence over saved credentials. With neither field set, the agent loads credentials.json from data-path, which defaults to /var/lib/nexigon/agent. A relative data-path is resolved from the configuration file’s directory.

The TLS certificate defaults to /etc/nexigon/agent/ssl/cert.pem and the private key to /etc/nexigon/agent/ssl/key.pem. Set ssl-cert and ssl-key only to use different paths.

Provisioning

Nexigon Agent 0.6 and later supports a local HTTP endpoint for one-use provisioning tokens. The listener runs only when provisioning is enabled and no static or saved credentials are available:

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

[provisioning]
enabled = true
bind = "0.0.0.0:6947"
endpoints = ["https://eu.nexigon.cloud", "https://us.nexigon.cloud"]
device-name = "Factory Gateway"

A token containing a Nexigon Hub domain selects that HTTPS Nexigon Hub directly and overrides the fallback endpoints list. For a bare pairing key on a self-hosted instance, set endpoints to your Nexigon Hub’s HTTPS URL.

The listener uses plaintext HTTP. Use a trusted provisioning network and limit access to the configured port. Set bind = "127.0.0.1:6947" when submitting tokens from the device itself.

After successful pairing, the agent saves its credentials, closes the listener, and connects to the Nexigon Hub. It writes credentials.json with mode 0600 on Unix and protects its parent directory with mode 0700. Keep data-path and the device’s TLS certificate and private key on persistent storage, and exclude them from shared device images.

Enable provisioning in a dedicated enrollment image. In the production image, set enabled = false in [provisioning] or omit that table, while preserving the saved credentials and TLS identity. This keeps credential loss from reopening the enrollment endpoint.

With provisioning disabled, Nexigon Agent reuses saved credentials on restart. Without static or saved credentials, the production agent fails to start instead of reopening the provisioning listener. Invalid or unreadable saved credentials also cause startup to fail.

Follow the provisioning guide to obtain a token and submit it to the device.

Device Fingerprints

Nexigon Agent computes the device fingerprint from the fingerprint script’s standard output. Keep that output stable across reboots, updates, and credential changes, and unique to each device. Send diagnostics to stderr so they do not change the identity input.

For example, the following script uses /etc/machine-id. It requires a unique machine ID generated for each device and preserved across updates. Cloning the same populated machine-ID file into several devices would give them the same fingerprint. If storage can be replaced, use an identity source that survives that replacement, such as a hardware-specific identifier:

#!/usr/bin/env bash

set -euo pipefail

cat "/etc/machine-id"

Feature Configuration

Commands, operation polling, and the browser terminal are disabled by default. Enable the capabilities required by your device integration.

Commands

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"

Operation Polling

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.

Browser Terminal

The browser terminal opens a shell on the device independently of SSH forwarding:

[terminal]
enabled = true
user = "root"

Set user to the account that should run terminal sessions. Enable the feature only on devices where remote shell access is intended.

TCP Forwarding

Starting with Nexigon 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.

HTTP Exports

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

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

Additional Ports

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

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

All-Port Access

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 Nexigon CLI forwarding. An export’s HTTP protocol and URL path do not restrict traffic on that port. Nexigon Hub remote-access permissions also apply; generating a URL in the Nexigon Hub does not change the device’s policy. The browser terminal is configured separately and does not require forwarding port 22.

Upgrading from Nexigon Agent 0.5

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

TCP Forwarding Capacity

Nexigon 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, Nexigon 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.

Capacity Settings

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 Nexigon Agent.

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

Upgrade Order

To use the higher proxy capacity on a self-hosted instance, upgrade Nexigon Hub to 2026.3.2 or later before upgrading devices to Nexigon Agent 0.6. Nexigon Hub caps older agents at the lower of its configured limit and 24 forwards. Older Nexigon Hub versions remain compatible with Nexigon Agent 0.6 but ignore its capacity metadata.