Plugin Configuration Files

Use plugins.toml when the nemo-relay CLI gateway should activate plugins at startup. The file contains the same generic plugin configuration document used by the Rust, Python, and Node.js plugin APIs, but encoded as TOML at the file root.

This page documents file discovery, precedence, merge behavior, editor behavior, and conflict rules for the CLI gateway. Component-specific fields are documented in the guide for each plugin component.

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 = 1
9
10
[components.config.atof]
11
enabled = true
12
output_directory = "logs"
13
filename = "events.jsonl"
14
mode = "append"
15
16
[policy]
17
unknown_component = "warn"
18
unknown_field = "warn"
19
unsupported_value = "error"

The top-level fields are:

Each component has:

The gateway reads only files named plugins.toml.

Discovery

The gateway can receive plugin configuration from three source classes:

Use only one source class for a given gateway run. The gateway fails clearly if file-based plugin config and --plugin-config are both present, or if plugins.toml and [plugins].config are both present.

When --config path/to/config.toml is supplied, plugin file discovery is scoped to path/to/plugins.toml. Implicit system, project, and user plugin files are not loaded for that run.

When no explicit --config path is supplied, the gateway checks these plugins.toml locations from lowest to highest precedence:

1. System: /etc/nemo-relay/plugins.toml
2. Project: the nearest .nemo-relay/plugins.toml found by walking upward from the current directory
3. User: $XDG_CONFIG_HOME/nemo-relay/plugins.toml, or ~/.config/nemo-relay/plugins.toml when XDG_CONFIG_HOME is not set

Missing files are skipped. If no plugin config source exists, the gateway starts without process-level plugin activation.

Editing Files

Use the interactive editor for Observability and Adaptive plugin configuration:

$
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

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. User config overrides project config, and project config overrides system config.

TOML tables merge recursively:

1
# system plugins.toml
2
[[components]]
3
kind = "observability"
4
5
[components.config.atof]
6
enabled = true
7
output_directory = "/var/log/nemo-relay"
8
mode = "append"

1
# user plugins.toml
2
[[components]]
3
kind = "observability"
4
5
[components.config.atof]
6
mode = "overwrite"

The effective Agent Trajectory Observability Format (ATOF) config keeps enabled and output_directory from the system file and uses mode = "overwrite" from the user file.

The top-level components array is special. Components are matched by kind across files. A higher-precedence component with the same kind merges into the lower-precedence component. A component with a different kind is added to the effective configuration.

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.

Arrays inside component config are replaced by the higher-precedence value. Tables inside component config merge recursively.

Explicit Defaults And Overrides

The editor writes explicit defaults for edited Observability and Adaptive sections. This is intentional. In a layered config model, omitting a field means “inherit a lower precedence value”; it does not mean “delete that value.”

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

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

The merged config may still contain inherited ATOF sibling fields such as output_directory, but the runtime ignores the section because enabled = false.

To override an inherited non-default field with its default value, write the default explicitly in the higher-precedence file. For example, use mode = "append" to override a lower-precedence mode = "overwrite".

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}.

Use nemo-relay doctor to inspect the resolved gateway configuration and plugin diagnostics. For Observability, doctor also reports enabled exporter sections and checks writable file exporter directories or reachable OTLP endpoints when those settings are present.

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 long-lived plugin setup in plugins.toml. Use [plugins].config in config.toml only when a generated or embedded config must keep all gateway settings in one file. Use --plugin-config for automation that should not write files.

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