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"

Connection to Nexigon Hub

Nexigon Agent connects to Nexigon Hub when it starts. When it cannot connect or loses the connection, for example because the network or Nexigon Hub is unavailable, it keeps trying. Before each attempt after the first, it waits for a random delay between zero and an upper bound. The bound starts at 30 seconds and doubles after each failed attempt, up to 10 minutes. A connection that stays up for 60 seconds resets the bound. When Nexigon Hub asks the agent to retry later, the agent waits at least that long, up to 10 minutes, plus the random delay.

The agent stops trying only if its configuration rules out a connection, for example a plaintext Hub URL without dangerous-allow-plaintext, or if Nexigon Hub reports a different device ID than before. It then exits, and its service manager restarts it.

The random delays matter for fleets. When Nexigon Hub restarts, all devices lose their connections at the same moment. The delays spread their reconnection attempts, so that Nexigon Hub is not flooded with connections while it starts.

Terminal sessions, TCP forwarding, and device commands started from Nexigon Hub end with the connection. System updates, app management, operation polling, and the local API keep running. The local API is a Unix socket through which the agent’s own commands, such as nexigon-agent events emit, reach Nexigon Hub over the running agent’s connection. An installation or a command step of an operation that is in progress runs to completion.

The delays also apply while Nexigon Hub rejects the device, for example while its certificate awaits approval. After the approval, the device can take up to the current bound to connect.

Reconnection Settings

Keep the defaults for large fleets. Shorter delays let a device recover faster from a short outage but increase the load on Nexigon Hub when many devices reconnect at once:

[connection]
connect-timeout-secs = 30

[connection.reconnect]
initial-delay-secs = 30
max-delay-secs = 600
stable-after-secs = 60

Connection Status

nexigon-agent status prints the state of the running agent’s connection and the device ID as JSON:

nexigon-agent status

{
  "deviceId": "d_...",
  "connection": { "state": "Connected", "since": "2026-10-26T09:12:44Z" }
}

While the agent is disconnected, state is Disconnected, and the status includes the number of failed attempts, the time of the next attempt, and the last error. The command uses the agent’s local API, so it requires a running agent. While the agent is disconnected, the device, events, and repositories commands of Nexigon Agent fail instead of connecting to Nexigon Hub on their own.

Feature Configuration

Commands, operation polling, the browser terminal, and system updates 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.

System Updates

The agent can install OTA updates with Rugix Ctrl or RAUC. Enable the integration for the update engine of the image:

[integrations.rugix.system-updates]
enabled = true
path = "my-repo/my-package/stable"

For RAUC, use [integrations.rauc.system-updates] with the same settings, except use-bundle-hash. Only one integration can be enabled.

The agent checks for updates after it connects to Nexigon Hub and then periodically. It also checks when a retry is due, when the maintenance window opens, or when a spread releases the device. Each of these scheduled checks waits for an additional random delay of up to check-jitter-secs, so that devices whose checks are due at the same time do not reach Nexigon Hub at once. With commands enabled, the nexigon.ota.check command triggers an immediate check. Without a path, the device does not update until the configuration property supplies one.

The agent identifies the running system by the build information of Rugix Bakery, if present. Otherwise, it uses IMAGE_ID and IMAGE_VERSION from /etc/os-release. The system name selects the bundle of a package version, <name>.rugixb or <name>.raucb. The device runs a package version when its version string equals metadata.imageVersion of that package version. To find the package version it runs, the agent resolves the version string as a tag of the package.

On Rugix, the agent commits a newly booted system once it has connected to Nexigon Hub. On RAUC, the rauc-mark-good service of RAUC marks booted slots as good.

The status also describes the update engine in updater: its version, its slots, the booted slot, and the slot that the device boots next. See Update System.

Failures of the integration do not stop the agent. With invalid settings, for example when both integrations are enabled, the agent logs an error and runs without system updates. When a check fails or panics, the agent logs the error and retries the check after a delay, or within check-jitter-secs after the agent reconnects to Nexigon Hub.

App Management

The agent can install, update, and remove apps with Rugix Apps. The integration requires a Rugix Ctrl version that supports rugix-ctrl apps install --origin. It can run alongside a system update integration:

[integrations.rugix.apps]
enabled = true

The agent checks the apps after it connects to Nexigon Hub, periodically, and when an attempt is due. With commands enabled, the nexigon.apps.check command triggers an immediate check.

After switching an app to a new version, the agent removes old versions with rugix-ctrl apps gc, which also frees their stored files. gc.keep sets how many previously running versions it keeps, unless the gc policy sets it:

[integrations.rugix.apps.gc]
keep = 2

The architecture defaults to the one the agent was built for, using Rust’s names such as x86_64, aarch64, or arm. Set arch to tell apart variants that share a name, for example armv6 and armv7.

The agent records the package version of every app generation it installs with Rugix Ctrl, so it knows the version an app runs, also after a rollback on the device. The agent does not change apps that the configuration does not list. While a system update installs a new system and reboots into it, the agent does not change apps.

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.