Plugin Configuration Files

Use plugins.toml when Relay should activate plugins from file configuration. The runtime discovers and layers this generic plugin document for direct Rust, Python, and Node.js integrations as well as for the nemo-relay CLI gateway. The file encodes the same document that binding APIs accept, but uses TOML at the file root.

This guide documents runtime file discovery, precedence, merge behavior, and conflict rules. It also identifies gateway-only editor, explicit-config, and discoverable-plugin workflows. Each component guide documents its component-specific fields.

Shortest Path Example

Use this minimal plugins.toml when you want Relay to start with one plugin-managed observability exporter and no extra layering:

1
version = 1
2
3
[[components]]
4
kind = "observability"
5
enabled = true
6
7
[components.config]
8
version = 3
9
10
[components.config.atof]
11
enabled = true
12
13
[[components.config.atof.sinks]]
14
type = "file"
15
output_directory = "logs"
16
filename = "events.jsonl"
17
mode = "append"

For the most deterministic CLI-gateway verification path, keep plugins.toml in the same directory as the gateway config.toml file for this run, then launch the wrapper with that explicit config path. For example:

path/to/
  config.toml
  plugins.toml

Run the gateway with the following command:

$
nemo-relay --config path/to/config.toml run -- codex

This uses the colocated plugins.toml instead of the ambient user plugin file. The nearest project file and the system file still layer on top, so run from a directory without a project plugin file and ensure the system layer does not override the exporter you want to verify. The plugin file is the configuration being demonstrated here; --config only tells the gateway which low plugin layer to use for this run. If you prefer implicit discovery, place the file at ./.nemo-relay/plugins.toml or another discovered location. Refer to CLI Basic Usage for the wrapper command shapes.

What Success Looks Like

The shortest-path setup is working when:

• nemo-relay starts without plugin validation or activation errors.
• The observability component activates the ATOF exporter configured in this file.
• An instrumented gateway run writes ATOF JSONL output to logs/events.jsonl.

After that path works, expand the config with additional components, policies, or higher-precedence files as needed.

File Shape

plugins.toml uses the canonical plugin document shape:

1
version = 1
2
3
[[components]]
4
kind = "observability"
5
enabled = true
6
7
[components.config]
8
version = 3
9
10
[components.config.atof]
11
enabled = true
12
13
[[components.config.atof.sinks]]
14
type = "file"
15
output_directory = "logs"
16
filename = "events.jsonl"
17
mode = "append"
18
19
[policy]
20
unknown_component = "warn"
21
unknown_field = "warn"
22
unsupported_value = "error"

The top-level fields are:

Each built-in component has:

Gateway Discoverable Plugin Records

Use [[plugins.dynamic]] only for a gateway-managed manifest-backed native or worker plugin. These records remain separate from [[components]]. During gateway activation, Relay loads each enabled dynamic adapter, synthesizes its internal component, and validates the component configuration.

The following record configures a dynamic plugin:

1
[[plugins.dynamic]]
2
manifest = "./plugins/acme/relay-plugin.toml"
3
4
[plugins.dynamic.config]
5
mode = "audit"

manifest is required and resolves relative to this file. config is optional. Run nemo-relay plugins validate <plugin-id> to validate it against the manifest’s optional static JSON Schema before you enable or run the plugin. Use nemo-relay plugins add, validate, inspect, and enable to manage the dynamic-plugin lifecycle. Refer to Configure Discoverable Plugins for manifest, trust, and policy requirements.

Embedded Python Compatibility Helper

Python hosts that already own plugin activation can convert the dynamic records from one explicitly selected file into the activation specs accepted by the 0.7 host API:

1
import asyncio
2
3
from nemo_relay import plugin
4
5
6
async def main() -> None:
7
    dynamic_plugins = plugin.load_dynamic_plugin_activation_specs(
8
        "path/to/plugins.toml"
9
    )
10
    activation = await plugin.initialize_with_dynamic_plugins({}, dynamic_plugins)
11
    async with activation:
12
        # Run your host application while dynamic plugins are active.
13
        ...
14
15
16
asyncio.run(main())

The helper resolves each manifest relative to plugins.toml and reads the plugin ID and execution lane from the manifest. It does not perform discovery, consult CLI lifecycle state, provision a Python worker environment, or change enablement.

On success, the helper returns every [[plugins.dynamic]] declaration in file order; it does not skip invalid entries. A missing plugins.toml or referenced manifest raises FileNotFoundError. Malformed TOML, invalid records or required manifest fields, duplicate plugin IDs, and non-JSON configuration raise ValueError. The helper does not apply an optional manifest-declared static JSON Schema.

Passing the result to initialize_with_dynamic_plugins() is explicit consent to load those trusted native libraries or worker processes.

This helper is a 0.7 compatibility surface for embedded integrations and is planned for deprecation after Relay provides a unified file-backed initializer. Keep its use localized so migration is straightforward.

The runtime reads only files named plugins.toml during default discovery.

Runtime Discovery

The runtime resolves plugin configuration from plugins.toml files and an optional code-driven layer. Direct Rust, Python, and Node.js calls to their plugin-initialization APIs use this same discovery and layering behavior.

File configuration comes from plugins.toml:

The runtime does not read plugin configuration from config.toml.

Gateway Explicit Config

When the CLI gateway receives --config path/to/config.toml, it scopes plugin file discovery’s low layer to path/to/plugins.toml. An explicit --plugin-config-path selects that low layer directly. Either explicit form replaces the ambient user plugin file; the nearest project file and the system file still apply.

Default Discovery Locations

The runtime checks these plugins.toml locations from lowest to highest precedence:

1. Explicit or user:
   • --plugin-config-path, or the plugins.toml beside --config, when supplied
   • otherwise $XDG_CONFIG_HOME/nemo-relay/plugins.toml, or ~/.config/nemo-relay/plugins.toml when XDG_CONFIG_HOME is not set
2. Project: the nearest .nemo-relay/plugins.toml found by walking upward from the current directory
3. System: /etc/nemo-relay/plugins.toml

The runtime skips missing files and loads a physical file only once when multiple paths or symlinks select it. If no plugin config source exists, initialization continues without process-level plugin activation. The user-only bootstrap scope suppresses project discovery but still applies the system layer.

Gateway Editing Files

Use the interactive editor for Observability, Adaptive, NeMo Guardrails, and PII Redaction configuration. The editor also updates the configuration of manifest-backed dynamic plugins that plugins add has registered:

$
nemo-relay plugins edit

By default, the editor writes the user plugin file:

$XDG_CONFIG_HOME/nemo-relay/plugins.toml

or:

~/.config/nemo-relay/plugins.toml

When the top-level CLI receives --plugin-config-path, the editor uses that exact file. Otherwise, --config path/to/config.toml makes the editor use the sibling path/to/plugins.toml, matching the runtime selection for that configuration. This explicit file replaces the user editor target, so plugins edit --user keeps the inherited explicit target. Use --project or --global to edit the other active layers. These rules only select the file opened by the editor; they do not change runtime discovery, layering, or merge precedence.

Use a scope flag to edit another location:

$
nemo-relay plugins edit --project
$
nemo-relay plugins edit --global

Scope flags are mutually exclusive.

--project writes the nearest existing .nemo-relay/plugins.toml. If none exists, it writes next to the nearest .nemo-relay/config.toml. If neither file exists in the parent directories, it writes ./.nemo-relay/plugins.toml from the current directory.

--global writes /etc/nemo-relay/plugins.toml and usually requires elevated filesystem permissions.

The editor menus support these controls:

Text and JSON value prompts use normal line editing. Use the surrounding field menu to reset, clear, preview, or save.

Precedence and Merge Behavior

When more than one plugins.toml file is discovered, later files have higher precedence. System config overrides project config, and project config overrides the selected explicit-or-user config.

TOML tables merge recursively. Top-level lists inside a component’s config concatenate, as do the declared observability destination lists. Entries from the higher-precedence layer are placed before entries from the lower-precedence layer. Other nested lists replace. For example, the following user configuration enables one ATOF file sink:

1
# user plugins.toml
2
[[components]]
3
kind = "observability"
4
5
[components.config]
6
version = 3
7
8
[components.config.atof]
9
enabled = true
10
11
[[components.config.atof.sinks]]
12
type = "file"
13
output_directory = "~/.local/state/nemo-relay"
14
mode = "append"

The system scope can add a fleet sink without repeating the user sink:

1
# system plugins.toml
2
[[components]]
3
kind = "observability"
4
5
[components.config.atof]
6
7
[[components.config.atof.sinks]]
8
type = "file"
9
output_directory = "/var/log/nemo-relay"
10
mode = "overwrite"

The effective Agent Trajectory Observability Format (ATOF) configuration keeps version and enabled from the user file. Its sinks list contains the system sink first, followed by the user sink.

The top-level components array is special. Relay matches enabled components by kind across files. A higher-precedence component with the same kind merges into the lower-precedence component. Relay adds a component with a different kind to the effective configuration.

A component entry that explicitly sets enabled = false is skipped before matching and merging. It does not change a lower-precedence component’s enabled state or contribute any config fields or list entries. If every layer for a component kind sets enabled = false, that kind is absent from the effective configuration.

This behavior applies to list fields declared at the top level of a component’s config. It also applies to the observability destination lists atof.sinks, opentelemetry.endpoints, and atif.storage. For example, pricing.sources and PII redaction profiles are top-level component config lists and concatenate across layers. Higher-precedence pricing sources can therefore override one model while still retaining lower-precedence project or user pricing sources.

Lists nested inside arbitrary structured values are not treated as top-level plugin lists; a higher-precedence value replaces those lists.

Declare each kind at most once inside one plugins.toml file. Duplicate component kinds in the same file fail before merge. Duplicate singleton components that reach plugin validation also fail validation.

Outside component config objects, higher-precedence arrays and scalar values replace lower-precedence values. Tables continue to merge recursively.

Configuration Layering

Plugin settings come from files and code. Files form the base layer, and code sits on top. When the two conflict, code takes precedence. Layering works as follows:

1. Discover and merge the plugins.toml files from lowest to highest precedence (explicit-or-user → project → system), using the Precedence And Merge Behavior rules above.
2. Layer the config object you pass to initialize over that merged base. Any setting it specifies overrides the file value, and the result is the effective config that Relay validates and activates.

Programmatic lists participate in the same concatenation rules. For example, a programmatic config.opentelemetry.endpoints list appears before endpoints inherited from system, project, and explicit-or-user files; it does not remove those file entries.

When library initialization discovers plugins.toml files, Relay emits one plugin.configuration_inherited warning per file. Each warning is written to the operational log and included in the initialization result and active plugin report. It names only the source path and does not include configuration values or credentials. Discovery itself does not block initialization, but validation or activation errors in the effective layered configuration still fail normally.

Files and code differ only in how they treat a setting you omit:

Lower-precedence files fill fields that higher-precedence files omit. Typed code fields always have values, so they override file values. Only component selection and keys inside component config merge with files.

When a component declared in code resolves enabled = true over a discovered enabled = false, initialization and the active plugin report include a plugin.component_reenabled warning that names the contributing file.

Without filesystem access, no files are read, so the base is empty and only your initialize config applies.

Explicit Defaults and Overrides

The editor writes explicit defaults for edited Observability and Adaptive sections. It writes NeMo Guardrails, PII Redaction, and dynamic-plugin fields only when readers configure them. In a layered config model, omitting a field means “inherit a lower precedence value”; it does not mean “delete that value.” Use the dedicated nemo-relay model-pricing commands to manage model-pricing catalog sources.

For example, this system file disables ATOF even if a project or user file enables it:

1
[[components]]
2
kind = "observability"
3
4
[components.config.atof]
5
enabled = false

The merged configuration can still contain an inherited ATOF sinks array, but the runtime ignores the section because enabled = false.

To override an inherited non-default scalar field with its default value, write the default explicitly in the higher-precedence file. List entries are not merged item by item: higher-precedence entries are added before inherited entries. To change or remove an inherited sink, profile, source, or other list entry, edit the layer that declares it.

There is no tombstone syntax for deleting an inherited nested field while keeping the rest of the lower-precedence component. To remove inherited settings entirely, edit the lower-precedence file or override the behavior with another field such as enabled = false.

Validation

Plugin validation runs before activation. Invalid plugin config blocks gateway startup instead of starting with a partially installed plugin set.

Common validation failures include:

• Unknown component kinds when policy treats them as errors.
• Unknown fields when policy treats them as errors.
• Unsupported field values, such as an invalid exporter mode or transport.
• Duplicate singleton components.
• Enabled components whose build-time features are unavailable.
• Component-specific semantic failures, such as an Agent Trajectory Interchange Format (ATIF) filename template that does not contain {session_id}.
• Dynamic manifests that have an incompatible Relay version, unsupported capability, invalid load contract, or failed trust evidence. Run nemo-relay plugins validate <plugin-id> to check optional static schema validation for dynamic component config.

Use nemo-relay doctor to inspect the resolved gateway configuration and plugin diagnostics. For Observability, doctor also reports enabled exporter sections, checks writable file exporter directories, probes configured ATOF stream sinks, and checks reachable OTLP endpoints when those settings are present. For model pricing, doctor validates enabled file and inline sources and fails when a source is unreadable or the catalog schema is invalid. For dynamic-plugin validation, lifecycle state, and trust diagnostics, use nemo-relay plugins validate, inspect, and list; doctor reports only the resolved manifest references and host configuration status.

Relationship to config.toml

config.toml owns gateway and agent setup, such as upstream provider base URLs and agent command configuration. plugins.toml owns reusable runtime behavior installed by the plugin system.

Keep all long-lived plugin setup in plugins.toml. config.toml owns gateway and agent setup only.

Legacy observability config sections in config.toml, such as [exporters], [observability], and [export.openinference], are not supported. Configure Observability exporters through plugins.toml.

Component Guides

Use the component guides for field-level configuration:

• Observability Configuration
• Adaptive Configuration
• Adaptive Cache Governor (ACG)
• Adaptive Hints
• NeMo Guardrails Configuration
• PII Redaction Configuration
• Model Pricing