NVIDIA · rapids-bot · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
@@ -42,7 +42,7 @@ trajectory file, you have concrete data to inspect, debug, and build on.
 ### Local Agent Trajectory
 
 This walkthrough shows an end-to-end quick success setup. Install the
-`nemo-relay-cli`, turn on local exporters, run either Codex or Claude Code
+`nemo-relay-cli`, turn on local exporters, run Codex, Claude Code, or Hermes
 through Relay, and check that Relay wrote both raw events and normalized
 trajectories.
 
@@ -83,13 +83,12 @@ The editor creates or updates the nearest project plugin file at
 then configure these sections:
 
 1. Toggle the Observability component on.
-2. Open `ATOF`. Toggle the section `[on]`.
+2. Open **ATOF**. Toggle the section **[on]**.
 
-   Optionally set:
-   - `output_directory` to `.nemo-relay/atof`
-   - `filename` to `events.jsonl`
-   - `mode` to `overwrite`
-3. Open `ATIF`. Toggle the section `[on]`.
+   Add a file sink. You can set its `output_directory` to
+   `.nemo-relay/atof`, `filename` to `events.jsonl`, and `mode` to
+   `overwrite`. Add stream sinks to send the same events to remote collectors.
+3. Open **ATIF**. Toggle the section **[on]**.
 
    Optionally set:
    - `output_directory` to `.nemo-relay/atif`
@@ -101,29 +100,45 @@ then configure these sections:
 > Run `nemo-relay plugins edit` without `--project` only when you want
 > user-level exporter settings that apply across projects.
 
-#### 3. Run Codex or Claude Code Through Relay
+#### 3. Run a Coding Agent Through Relay
 
 Run the Relay wrapper for the host CLI installed on your machine. For example:
 
 ```bash
 nemo-relay codex -- exec "Summarize this repository."
 ```
 
+For Claude Code, run:
+
 ```bash
 nemo-relay claude -- "Summarize this repository."
 ```
 
+For Hermes, run:
+
+```bash
+nemo-relay hermes -- -z "Summarize this repository."
+```
+
 Refer to the full [Quick Start CLI](https://docs.nvidia.com/nemo/relay/nemo-relay-cli/about) docs for more options.
 
 The transparent wrapper starts a local Relay gateway, injects host-specific hook
 and provider settings for that launched process, then shuts the gateway down
 when the agent exits.
 
 > [!WARNING]
-> If generated hooks are inactive, Codex users must review and activate them
-> before events appear. The Codex Desktop App has additional limitations.
-> Refer to the [Codex CLI guide](https://docs.nvidia.com/nemo/relay/nemo-relay-cli/codex) for the
-> current hook activation caveat and troubleshooting steps.
+> The transparent wrapper trusts only the Codex hooks that it generates for the
+> launched process. A persistent `nemo-relay install codex` trusts only the
+> hooks owned by `nemo-relay-plugin@nemo-relay-local`; manual and source
+> marketplace installs can still require review. Restart an open Codex app after
+> persistent installation.
+>
+> On Windows, a restrictive host Job Object can keep the shared Relay gateway
+> within the host process lifetime. If the host also rejects the required nested
+> assignment, persistent bootstrap stops and explains the conflict. The Codex
+> desktop app has additional limitations. Refer to the
+> [Codex CLI guide](https://docs.nvidia.com/nemo/relay/nemo-relay-cli/codex) for
+> lifecycle, startup, and troubleshooting details.
 
 #### 4. Verify the Run
 
@@ -287,8 +302,8 @@ coverage.
 | Agent | Observability | Security | Optimization | Notes |
 |:--|:--:|:--:|:--:|:--|
 | Claude Code | Yes | Yes | Partial | Hook forwarding, pre-tool blocking, and gateway-routed LLM observability are supported. |
-| Codex | Yes | Yes | Partial | Hook activation is required; missing session-end behavior limits trajectory finalization and full optimization coverage. |
-| Hermes Agent | Yes | Yes | Partial | Hook forwarding, pre-tool blocking, and gateway-routed or hook-backed LLM observability are supported. |
+| Codex | Yes | Yes | Partial | Persistent install verifies the exact plugin hooks. Each `Stop` finalizes a turn snapshot; the supported generated schema does not install `SessionEnd`. |
+| Hermes Agent | Yes | Yes | Partial | User config installs the shared native MCP gateway lifecycle plus exact trusted hooks; gateway-routed or hook-backed LLM observability is supported. |
 
 ### Public API Integrations
 

@@ -26,19 +26,23 @@ 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 hooks interactively**: Use the setup wizard to write project or
-  user config and install the hook files needed by supported agents.
+- **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 host-plugin installs, hook status, observability
-  outputs, and shell completions with `nemo-relay doctor`.
+  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,
@@ -49,6 +53,12 @@ with the installed `nemo-relay` command rather than link against the crate.
   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
 
@@ -101,6 +111,12 @@ 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

@@ -211,6 +211,14 @@ print(f"sha256:{sha256(artifact.read_bytes()).hexdigest()}")
 PY
 ```
 
+The module in `load.entrypoint` must resolve directly under
+`source.manifest_root` to exactly one Python source file: either
+`module/path.py` or `module/path/__init__.py`. That file must also be the
+integrity-checked `source.artifact`. Relay rejects ambiguous modules and custom
+build-backend mappings, including `src/` layouts that it cannot derive from the
+manifest. This check prevents an unsigned sibling module from becoming the
+executed entrypoint.
+
 ## Register the Plugin
 
 Run the following commands from the project directory:
@@ -227,6 +235,13 @@ the `source.manifest_root` project into it. Relay uses that recorded environment
 when it starts the worker. Do not start the worker directly: Relay supplies its
 worker socket, host socket, activation ID, and activation token.
 
+Relay records a digest of the installed environment in a locally authenticated
+marker that is bound to the integrity-checked entrypoint artifact. The marker
+detects changes between provisioning and activation. It is not a security
+boundary against another process running as the same operating-system user,
+because that process can access the same user-owned keys and files. Worker
+process isolation is not a security sandbox.
+
 ## Configure the Plugin
 
 After `plugins add` registers the worker, edit

@@ -61,16 +61,17 @@ inherit the persistent `PATH` change. Verify that the command is available:
 nemo-relay --version
 ```
 
-After installation, `nemo-relay` can also install persistent Claude Code and
-Codex host plugins:
+After installation, `nemo-relay` can also install persistent Claude Code,
+Codex, and Hermes Agent integrations:
 
 ```bash
 nemo-relay install claude-code
 nemo-relay install codex
+nemo-relay install hermes
 ```
 
-Refer to [Plugin Installation](/nemo-relay-cli/plugin-installation) for the host
-plugin workflow.
+Refer to [Coding Agent Installation](/nemo-relay-cli/plugin-installation) for
+the persistent integration workflow.
 
 <Note>
 The installers download the published SHA-256 checksum for the selected release
@@ -230,17 +231,18 @@ configuration and verification steps.
 
 ### Hermes Agent
 
-Install the latest NeMo Relay Python package in the environment that runs
-Hermes, then enable the bundled Hermes plugin:
+After installing the NeMo Relay CLI, install and diagnose the Hermes user
+integration:
 
 ```bash
-pip install nemo-relay
-hermes plugins enable observability/nemo_relay
+nemo-relay install hermes
+nemo-relay doctor --plugin hermes
 ```
 
-The plugin ID is `observability/nemo_relay`. See the
-[Hermes NeMo Relay plugin guide](https://github.com/NousResearch/hermes-agent/tree/main/plugins/observability/nemo_relay)
-for configuration and verification steps.
+Relay adds a native stdio MCP entry and trusts only the lifecycle hooks that it
+installs. The MCP process acquires the shared user-level gateway when it starts.
+Refer to the [Hermes Agent guide](/nemo-relay-cli/hermes) for provider routing,
+lifecycle, and removal steps.
 
 ### Python Framework Integrations
 

@@ -26,7 +26,7 @@ not yet know which guide owns the working path.
 | Layer | Use When | Start Here | Success Check |
 |---|---|---|---|
 | CLI and gateway | A coding-agent harness owns invocation and provider routing | [CLI Basic Usage](/nemo-relay-cli/basic-usage) | The wrapped agent runs with Relay active and emits hook output, plus gateway-routed LLM lifecycle output when provider routing is active. |
-| Persistent host-plugin installs | You want the maintained install path for Codex or Claude Code instead of the transparent wrapper | [Plugin Installation](/nemo-relay-cli/plugin-installation) | `nemo-relay doctor --plugin <host>` confirms the installed host plugin is registered and ready. |
+| Persistent coding-agent installs | You want the maintained install path for Codex, Claude Code, or Hermes Agent instead of the transparent wrapper | [Coding Agent Installation](/nemo-relay-cli/plugin-installation) | `nemo-relay doctor --plugin <host>` confirms the installed integration is ready. |
 | Direct Python or Node.js application APIs | Your application owns the tool or LLM callback | [Python Quick Start](/getting-started/quick-start/python) or [Node.js Quick Start](/getting-started/quick-start/nodejs) | The sample prints event lines plus tool and LLM results. |
 | Direct Rust application APIs | Your Rust application owns the tool or LLM callback | [Rust Quick Start](/getting-started/quick-start/rust) | The sample prints scope, tool, and LLM lifecycle output plus the `initialized` mark event. |
 | Plugin-managed runtime setup | You need process-level exporter or plugin behavior from `plugins.toml` | [Plugin Configuration Files](/configure-plugins/plugin-configuration-files) | The selected plugin path activates and writes the expected output or behavior. |

@@ -20,15 +20,22 @@ model traffic through the gateway, and diagnose local configuration. The
 `nemo-relay-cli` Cargo package remains available for source-based installation
 and unsupported platforms.
 
+Persistent integrations use one lifecycle path:
+
+`Codex / Claude Code / Hermes Agent` → `nemo-relay mcp` → `shared Relay gateway`
+
+The host-specific layer installs and emits canonical lifecycle hooks. The MCP
+process is host-neutral and keeps the shared user-level gateway available.
+
 ## Start Here When
 
 Use these guides when you need to:
 
 - Observe Claude Code, Codex, or Hermes Agent sessions locally.
 - Configure coding-agent hooks for NeMo Relay lifecycle events.
 - Route model-provider traffic through the local NeMo Relay gateway.
-- Install persistent Claude Code or Codex host plugins without wrapping the
-  agent command.
+- Install persistent Claude Code, Codex, or Hermes Agent integrations without
+  wrapping the agent command.
 - Validate and install model pricing catalog sources for local cost estimates.
 - Export local sessions to Agent Trajectory Interchange Format (ATIF), Agent
   Trajectory Observability Format (ATOF) JSONL, OpenTelemetry, or
@@ -49,25 +56,24 @@ controls.
 | Agent | Observability | Security | Optimization | Notes |
 | --- | --- | --- | --- | --- |
 | Claude Code | Yes | Yes | Partial | Pre-tool hook responses are supported. LLM optimization uses gateway-routed traffic; full coverage depends on loaded Claude Code hooks. |
-| Codex | Yes | Yes | Partial | Hook forwarding and gateway-routed LLM optimization are supported after hooks are reviewed and activated. The missing session-end hook limits full coverage. |
-| Hermes Agent | Yes | Yes | Partial | Hook forwarding, pre-tool guardrails, and Hermes API-request telemetry are supported. Optimization depends on Hermes shell and API-request hook coverage. |
+| Codex | Yes | Yes | Partial | Persistent install verifies all 10 hooks in the supported schema. Each `Stop` finalizes a turn snapshot because the plugin schema does not expose `SessionEnd`. |
+| Hermes Agent | Yes | Yes | Partial | User config installs the shared native MCP gateway lifecycle plus exact trusted hooks. Optimization depends on Hermes shell and API-request hook coverage. |
 
 ## Guides
 
 Use these guide links to move from CLI setup into agent-specific instructions.
 
 - [Basic Usage](/nemo-relay-cli/basic-usage) explains gateway routes, transparent runs,
   shared configuration, hook forwarding, and runtime mapping.
-- [Plugin Installation](/nemo-relay-cli/plugin-installation) covers persistent
-  Claude Code and Codex plugin setup through host marketplaces.
+- [Coding Agent Installation](/nemo-relay-cli/plugin-installation) covers
+  persistent Claude Code, Codex, and Hermes Agent setup.
 - [Claude Code](/nemo-relay-cli/claude-code) covers transparent Claude Code
   runs, Anthropic gateway routing, ATIF verification, and unsupported Claude
   application modes.
 - [Codex](/nemo-relay-cli/codex) covers transparent Codex CLI runs, local
   GUI/app caveats, model provider routing, and remote-task limits.
-- [Hermes Agent](/nemo-relay-cli/hermes) covers Hermes shell hook installation,
-  dynamic gateway URL handling, session-finalize behavior, and hook consent
-  caveats.
+- [Hermes Agent](/nemo-relay-cli/hermes) covers Hermes MCP lifecycle setup,
+  exact hook trust, provider routing, and session-finalize behavior.
 
 Start with [Basic Usage](/nemo-relay-cli/basic-usage), then use the guide for the coding
 agent that you want to observe.