> This page is for NeMo Relay, version dev.
> For other versions, use one of these documentation indexes:
> - Latest (v0.10.3) (default): https://docs.nvidia.com/nemo/relay/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/relay/dev/llms.txt
> - v0.10.3: https://docs.nvidia.com/nemo/relay/v0.10.3/llms.txt
> - v0.10.2: https://docs.nvidia.com/nemo/relay/v0.10.2/llms.txt
> - v0.9.4: https://docs.nvidia.com/nemo/relay/v0.9.4/llms.txt
> - v0.8.4: https://docs.nvidia.com/nemo/relay/v0.8.4/llms.txt
> - v0.7.3: https://docs.nvidia.com/nemo/relay/v0.7.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/relay/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/relay/_mcp/server.

# Codex Quick Start

> Run one local Codex CLI task through NeMo Relay and write ATOF events.

## Goal

Run one local Codex CLI task through NeMo Relay and write its turn, model, and
tool lifecycle to a local Agent Trajectory Observability Format (ATOF) file.

> **Note**
>
> This path observes local Codex processes. Cloud or remote Codex tasks are only
> partially observable because their provider traffic does not cross the local
> Relay gateway.

> **Trial configuration**
>
> This guide uses disposable local files and wrapped execution to try Relay for
> one run. It is a trial configuration, not an ongoing deployment setup.

> **For regular use**
>
> For personal use, configure [user or system settings](/nemo-relay-cli/basic-usage#shared-configuration)
> and follow the agent's [persistent integration setup](/nemo-relay-cli/codex).
>
> For administrator-managed deployments, use [daemon mode](/daemon/about) for a
> shared service and centrally managed configuration.

Use the event relationships to follow model and tool work through a run and
check where the expected activity occurred.

## Prerequisites

Before you start, make sure you have:

* Codex CLI 0.143.0 or newer
* Inference access: an [OpenAI API key](https://platform.openai.com/api-keys), a supported Codex login, or credentials for an [OpenAI Responses-compatible gateway](/nemo-relay-cli/basic-usage#provider-upstreams)
* A trusted Git working directory where Codex is permitted to create a file
* A [supported NeMo Relay CLI platform](/getting-started/installation#supported-platforms)
* Permission to download the NeMo Relay version used by this guide

On Unix, the verification step also uses `jq` 1.6 or newer; check your version
with `jq --version`. PowerShell uses its built-in JSON parser.

> **Note**
>
> Use Codex's configured model; Relay does not select or require one. For example,
> authenticate with `codex login`, or set `OPENAI_API_KEY` for an API-key-backed
> Relay-wrapped run. Relay replaces Codex's model provider with its gateway
> provider, so `CODEX_API_KEY` or a custom provider's `env_key` alone is insufficient.
> A custom gateway must provide the OpenAI Responses
> API; configure its credentials, base URL, and model in Codex before wrapping
> the run. Also add an `[upstream]` section with
> `openai_base_url = "https://YOUR_GATEWAY/v1"` to the Relay `config.toml` below;
> Codex's custom base URL is not carried over when Relay replaces its provider.
> Refer to [Codex authentication](https://developers.openai.com/codex/auth).

## Install

Install the NeMo Relay CLI version for these docs:

#### Unix shell

```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | NEMO_RELAY_VERSION=0.11.0 sh
export PATH="$HOME/.local/bin:$PATH"
```

#### Windows PowerShell

```powershell
$env:NEMO_RELAY_VERSION = '0.11.0'
irm https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.ps1 | iex
```

## Configure

Create a disposable Git repository and permit Codex to write files there:

```bash
mkdir relay-codex-quickstart
cd relay-codex-quickstart
git init
```

Save and run the remaining files from this directory.

Save this file as `config.toml` in the directory where you will run the agent:

```toml title={"config.toml"}
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

[agents.codex]
command = "codex"

```

The agent entry in `config.toml` tells Relay which executable to launch.
Save this sibling file as `plugins.toml` to enable ATOF export to
`logs/events.jsonl`:

```toml title={"plugins.toml"}
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

version = 1

[policy]
unknown_component = "error"
unknown_field = "error"
unsupported_value = "error"

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

[components.config]
version = 4
enable_full_payloads = false

[components.config.atof]
enabled = true

[[components.config.atof.sinks]]
type = "file"
output_directory = "logs"
filename = "events.jsonl"
mode = "overwrite"

```

> **Warning**
>
> ATOF output can contain sensitive prompts, responses, tool arguments, and tool
> results. Protect `logs/events.jsonl` even when full payload export is disabled.

## Run

The prompt asks the agent to create a known file so you can distinguish a
successful tool action from an ordinary text reply. Relay records the turn,
model calls, and tool activity while the agent completes the task.

From the directory containing both files, clear the previous example outputs
and run the validation prompt:

#### Unix shell

```bash
rm -f -- relay-check.txt logs/events.jsonl &&
nemo-relay --config "$PWD/config.toml" codex -- exec --sandbox workspace-write "Use a file-writing tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK."
```

#### Windows PowerShell

```powershell
foreach ($path in @('relay-check.txt', 'logs/events.jsonl')) {
  if (Test-Path -LiteralPath $path) { Remove-Item -LiteralPath $path -Force -ErrorAction Stop }
}
nemo-relay --config (Join-Path $PWD "config.toml") codex -- exec --sandbox workspace-write "Use a file-writing tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK."
```

> **Note**
>
> The [workspace-write sandbox](https://learn.chatgpt.com/docs/non-interactive-mode#permissions-and-safety)
> permits the marker file in your working directory; it does not disable sandboxing.

> **Tip**
>
> To choose a model for this invocation, use
> `nemo-relay --config "$PWD/config.toml" codex -- --model MODEL_ID exec --sandbox workspace-write "YOUR_PROMPT"`.
> Replace `MODEL_ID` with an ID your provider supports. Put this Codex option
> before `exec`, preserving the prompt and sandbox from the command above.

> **Note**
>
> Relay starts a temporary local gateway and injects Codex hooks for this run. It
> does not modify your persistent Codex plugin configuration.

## Verify

The tool marker proves that the agent created the requested file. The event
marker proves that Relay recorded matching start/end records for the required
turn or agent, tool, and model work. The response marker is the agent's reply;
it is checked separately from the captured lifecycle.

The verification command prints `RELAY_QUICKSTART_TOOL_OK` and `RELAY_QUICKSTART_EVENTS_OK`.

<details>
  <summary>
    Run the verification checks
  </summary>

  After the task exits, confirm that Relay wrote the local event stream:

  #### Unix shell

  ```bash
  jq -eRs 'gsub("^\\s+|\\s+$"; "") == "RELAY_QUICKSTART_TOOL_OK"' relay-check.txt > /dev/null &&
  jq -se '
    . as $events |
    def closed($category):
      any($events[]; . as $end_event |
        .kind == "scope" and .scope_category == "end" and
        .category == $category and
        ($category != "custom" or .name == "codex-turn") and
        any($events[]; .kind == "scope" and .scope_category == "start" and
          .uuid == $end_event.uuid and .name == $end_event.name and
          .category == $end_event.category and .parent_uuid == $end_event.parent_uuid));
    length > 0 and
    all(.[]; .atof_version == "0.1" and (.kind == "scope" or .kind == "mark")) and
    closed("custom") and closed("tool") and closed("llm")
  ' logs/events.jsonl > /dev/null &&
  printf 'RELAY_QUICKSTART_TOOL_OK\nRELAY_QUICKSTART_EVENTS_OK\n'
  ```

  #### Windows PowerShell

  ```powershell
  if ((Get-Content .\relay-check.txt -Raw -ErrorAction Stop).Trim() -ne 'RELAY_QUICKSTART_TOOL_OK') {
    throw 'Expected tool-created marker file is missing'
  }
  $events = @(Get-Content .\logs\events.jsonl -ErrorAction Stop | ForEach-Object { ConvertFrom-Json -InputObject $_ -ErrorAction Stop })
  if (-not $events.Count -or @($events | Where-Object {
    $_.atof_version -ne '0.1' -or $_.kind -notin @('scope', 'mark')
  }).Count) { throw 'Expected nonempty ATOF 0.1 records' }
  foreach ($category in @('custom', 'tool', 'llm')) {
    $paired = @($events | Where-Object {
      $end = $_
      $end.kind -eq 'scope' -and $end.scope_category -eq 'end' -and
      $end.category -eq $category -and
      ($category -ne 'custom' -or $end.name -eq 'codex-turn') -and @($events | Where-Object {
        $_.kind -eq 'scope' -and $_.scope_category -eq 'start' -and
        $_.uuid -eq $end.uuid -and $_.name -eq $end.name -and
        $_.category -eq $end.category -and $_.parent_uuid -eq $end.parent_uuid
      }).Count -gt 0
    })
    if (-not $paired.Count) { throw "Missing paired $category records" }
  }
  Write-Output 'RELAY_QUICKSTART_TOOL_OK'
  Write-Output 'RELAY_QUICKSTART_EVENTS_OK'
  ```

  The verification command prints the following output when its checks pass:

  ```text
  RELAY_QUICKSTART_TOOL_OK
  RELAY_QUICKSTART_EVENTS_OK
  ```
</details>

The agent's final reply should include `RELAY_QUICKSTART_RESPONSE_OK`;
its surrounding wording can vary.

> **Note**
>
> The verification markers confirm the tool-created file and matching start/end
> records for custom turn, tool, and LLM work.

> **Note**
>
> If Codex reports that approval requests are unsupported in `exec` mode, run
> the same command interactively by removing only `exec`. Keep
> `--sandbox workspace-write`, approve the file write if prompted, and exit
> Codex after the reply before running the verification checks. Existing Codex
> settings and tool policies can still require approval inside the workspace.

### Inspect the Recorded Activity

Read the completed model calls from the same event file:

#### Unix shell

```bash
jq 'select(.kind == "scope" and .scope_category == "end" and .category == "llm") |
  {name, category, category_profile, uuid, parent_uuid, timestamp, metadata}' logs/events.jsonl
```

#### Windows PowerShell

```powershell
Get-Content .\logs\events.jsonl |
  ForEach-Object { ConvertFrom-Json -InputObject $_ } |
  Where-Object { $_.kind -eq 'scope' -and $_.scope_category -eq 'end' -and $_.category -eq 'llm' } |
  Select-Object name, category, category_profile, uuid, parent_uuid, timestamp, metadata |
  ConvertTo-Json -Depth 10
```

`category` and `name` identify the recorded work. The same `uuid` pairs its
start and end records; `parent_uuid` connects it to its enclosing scope.
`timestamp` records when this event occurred. For model calls, `category_profile`
and `metadata` can include the model identity and completion status, depending
on the integration. These fields let you follow a call through the run without
requiring full prompt or response capture.

## For More Details

For more details, refer to:

* [Codex guide](/nemo-relay-cli/codex)
* [Installation Overview](/getting-started/installation#cli)