[](https://github.com/NVIDIA/NeMo-Relay/blob/main/LICENSE)
[](https://github.com/NVIDIA/NeMo-Relay/)
[](https://github.com/NVIDIA/NeMo-Relay/releases)
[](https://app.codecov.io/gh/NVIDIA/NeMo-Relay)
[](https://pypi.org/project/nemo-relay/)
[](https://www.npmjs.com/package/nemo-relay-node)
[](https://crates.io/crates/nemo-relay)
[](https://crates.io/crates/nemo-relay-adaptive)
[](https://crates.io/crates/nemo-relay-cli)
[](https://deepwiki.com/NVIDIA/NeMo-Relay)
# 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 typed OpenTelemetry 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
Install the prebuilt CLI from PyPI:
```bash
pip install nemo-relay-cli-bin
```
Install the Python API and matching CLI with the optional extra:
```bash
pip install "nemo-relay[cli]"
```
Build and install the CLI from crates.io with Cargo:
```bash
cargo install nemo-relay-cli
```
Unix curl:
```bash
Windows PowerShell:
```powershell
For version pinning, custom installation directories, verification,
troubleshooting, and CLI usage, refer to the
[NeMo Relay installation guide](https://docs.nvidia.com/nemo/relay/getting-started/installation).
After installation, verify the binary with:
```bash
nemo-relay --version
```
## Getting Started
Run the first-time setup wizard:
```bash
nemo-relay
```
After setup, inspect local readiness:
```bash
nemo-relay doctor
```
To troubleshoot a specific configuration file, pass it explicitly. Doctor reports a missing or
invalid file in its configuration checks instead of stopping before diagnostics:
```bash
nemo-relay --config /path/to/config.toml doctor
```
Run a supported agent through the gateway:
```bash
nemo-relay codex
nemo-relay claude -- "summarize this repository"
```
Install persistent integrations for the supported agent CLIs on `PATH`:
```bash
nemo-relay install all
```
Use `run --dry-run` to inspect resolved config without spawning the agent:
```bash
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`.
Runtime files layer from lowest to highest precedence as explicit-or-user,
nearest project, then system. An explicit `--config` replaces the ambient user
file without suppressing project or system configuration.
Set up agent entries in the top-level config with:
```bash
nemo-relay config
```
Edit gateway limits, provider upstreams, and operational logging with the
structured user-config editor:
```bash
nemo-relay config edit
```
Use `--project` for the nearest project `config.toml`, or `--global` for
`/etc/nemo-relay/config.toml`. Global saves are system-readable (`0644` on
Unix) and reject authorization headers; use the corresponding environment
variables or a user config for credentials.
When the top-level CLI receives `--config path/to/config.toml`, the config
editor uses that exact file as its user target, so the default editor and
`config edit --user` both open it. Use `--project` or `--global` to edit the
other active layers.
Observability exporters are configured through the plugin config. Edit the user
plugin config with:
```bash
nemo-relay plugins edit
```
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 runtime selection. The explicit file
replaces the user layer, so `--user` keeps that inherited target.
`--project` and `--global` edit the other active layers.
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`. Use `nemo-relay plugins edit --global` to edit
`/etc/nemo-relay/plugins.toml`; it is system-readable (`0644` on Unix), so do
not store credentials there. The editor rejects schema-declared secret values
in global plugin configuration.
Runtime plugin files layer from lowest to highest precedence as
explicit-or-user, nearest project, then system. An explicit
`--plugin-config-path`, or a `plugins.toml` beside `--config`, replaces the
ambient XDG user file without suppressing project or system policy. Missing
files are skipped, and symlink aliases to one physical file are loaded once.
Minimal ATIF example:
```toml
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