NeMo Relay

nemo-relay-cli installs the NeMo Relay CLI, the nemo-relay binary for local coding-agent observability. It can configure supported coding-agent hooks, run agents through an ephemeral gateway, and diagnose local agent and exporter readiness.

The CLI is a Rust package in this repository, but most users should interact with the installed nemo-relay command rather than link against the crate.

Why Use It?

The CLI is designed for these tasks:

Observe existing coding agents: Run Claude Code, Codex, or Hermes Agent through a local NeMo Relay gateway without changing the agent itself.
Configure transparent runs interactively: Use the setup wizard to write project or user configuration for supported agents.
Export local sessions: Write ATIF trajectory files, ATOF event JSONL streams, or OpenInference spans from one shared config model.
Diagnose setup readiness: Check config layers, plugins.toml discovery, agent binaries, persistent coding-agent integrations, hook status, observability outputs, and shell completions with nemo-relay doctor.

What You Get

The CLI provides these capabilities:

nemo-relay binary: The executable installed by the nemo-relay-cli Cargo package.
First-run setup: Bare nemo-relay launches setup when no config exists, then runs doctor once config is present.
Agent shortcuts: nemo-relay claude, nemo-relay codex, and nemo-relay hermes start observed agent runs.
Config-driven launch: nemo-relay run resolves config, environment, and CLI overrides for deterministic non-interactive use.
Hook forwarding server: A local gateway accepts agent hook events and provider-shaped OpenAI or Anthropic requests.
Persistent agent integration: nemo-relay install configures Codex, Claude Code, or Hermes Agent with one generated MCP bootstrap and the host's canonical lifecycle hooks.
Shared gateway lifecycle: Every persistent integration launches the same host-neutral nemo-relay mcp client. Concurrent clients share one native gateway on 127.0.0.1:47632.

Installation Options

Cargo:

cargo install nemo-relay-cli

Unix curl:

curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.ps1 | iex

For version pinning, custom installation directories, verification, troubleshooting, and CLI usage, refer to the NeMo Relay installation guide.

After installation, verify the binary with:

nemo-relay --version

Getting Started

Run the first-time setup wizard:

nemo-relay

After setup, inspect local readiness:

nemo-relay doctor

Run a supported agent through the gateway:

nemo-relay codex
nemo-relay claude -- "summarize this repository"

Install persistent integrations for the supported agent CLIs on PATH:

nemo-relay install all

Use run --dry-run to inspect resolved config without spawning the agent:

nemo-relay run --agent codex --dry-run

Configuration

Project config lives at ./.nemo-relay/config.toml; user config lives at ~/.config/nemo-relay/config.toml or $XDG_CONFIG_HOME/nemo-relay/config.toml. The project layer overrides system config, and the user layer overrides the project layer.

General options are configured through the top-level config. Edit the config with:

nemo-relay config

Observability exporters are configured through the plugin config. Edit the user plugin config with:

nemo-relay plugins edit

The top-level editor menu contains one entry per supported built-in, followed by the dynamic plugin references in the selected physical plugins.toml. Dynamic plugins with a manifest-declared JSON Schema provide structured field controls. Other dynamic plugins use a raw JSON object editor.

The canonical plugin file is plugins.toml; user config lives at ~/.config/nemo-relay/plugins.toml or $XDG_CONFIG_HOME/nemo-relay/plugins.toml. Project config lives at .nemo-relay/plugins.toml.

Minimal ATIF example:

version = 1

[[components]]
kind = "observability"
enabled = true

[components.config.atif]
enabled = true
output_directory = "./atif"

Documentation

NeMo Relay Documentation: https://docs.nvidia.com/nemo/relay