Skip to navigation
Getting StartedQuick StartsAgent Harnesses

Codex Quick Start

View as Markdown

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.

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 and follow the agent’s persistent integration setup.

For administrator-managed deployments, use daemon mode 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:

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.

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.

1

Install

Install the NeMo Relay CLI version for these docs:

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"
2

Configure

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

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:

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:

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"

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

3

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:

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

The workspace-write sandbox permits the marker file in your working directory; it does not disable sandboxing.

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.

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

4

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.

Run the verification checks

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

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'

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

RELAY_QUICKSTART_TOOL_OK
RELAY_QUICKSTART_EVENTS_OK

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

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

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:

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

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: