Use the Codex Adapter

The nvidia.fabric.codex adapter uses the Codex Python SDK and its pinned app-server runtime. NeMo Fabric does not execute codex for agent turns or fall back to the legacy Codex CLI adapter.

Install the Adapter

To install the NeMo Fabric runtime, Codex adapter, and supported Codex Python SDK in one environment:

$
pip install "nemo-fabric[codex]"

To install the adapter and supported Codex SDK without the NeMo Fabric runtime, use the adapter package’s harness extra:

$
pip install "nemo-fabric-adapters-codex[harness]"

The adapter package’s full extra installs the same dependencies as harness; it does not install the NeMo Fabric runtime. Codex Relay integration uses the external nemo-relay CLI, not the Python nemo-relay package, so this adapter does not provide a relay extra. Follow the NeMo Relay CLI installation procedure, then ensure nemo-relay is on PATH.

If the environment already manages a compatible Codex SDK, install only the adapter:

$
pip install nemo-fabric-adapters-codex

The bare adapter package does not install the NeMo Fabric runtime or SDK. Use openai-codex==0.144.4, the constraint supported by this release.

If the existing compatible Codex SDK and NeMo Fabric runtime share an environment, install the runtime and bare adapter together:

$
pip install nemo-fabric nemo-fabric-adapters-codex

For separate environments, set ADAPTER_PYTHON in the runtime environment to the adapter environment’s Python interpreter. Use matching NeMo Fabric release versions for the runtime and adapter package unless a different pairing has been explicitly validated.

Configure the Adapter

Select the Codex harness integration in HarnessConfig:

1
from nemo_fabric import HarnessConfig
2
3
harness = HarnessConfig(adapter_id="nvidia.fabric.codex")

Use normalized FabricConfig fields to configure the model, workspace, skills, MCP servers, and telemetry. The Codex adapter does not support normalized tools.enabled or tools.blocked policy. Configure base instructions through instructions.system; the adapter passes that normalized value to the Codex SDK as base_instructions.

The resolved Codex descriptor accepts the following Codex-specific harness.settings keys. All keys are optional:

Planning rejects unknown keys, empty dotted-key segments, invalid types, and invalid enum values before the Codex runtime starts. Schema defaults document adapter behavior but are not added to harness.settings. Use config_overrides as the intentional adapter-specific escape hatch for Codex configuration that has no normalized NeMo Fabric field.

Configure MCP and Skills

Use normalized NeMo Fabric fields so the same capability configuration can be planned before the adapter starts:

1
from examples.code_review_agent import codex_config
2
3
config = codex_config()
4
config.add_skill_path("./skills/code-review")
5
config.add_mcp_server(
6
    "repo",
7
    transport="stdio",
8
    url="repo-mcp --root .",
9
    exposure="harness_native",
10
)
11
config.add_mcp_server(
12
    "docs",
13
    transport="streamable-http",
14
    url="https://mcp.example.com/mcp",
15
    exposure="harness_native",
16
)

The adapter maps stdio, HTTP, and streamable HTTP servers into the Codex thread’s mcp_servers configuration. It resolves each skill directory, verifies that it contains SKILL.md, and registers it as a process-scoped Codex skill root. Codex uses its normal skill discovery behavior. Invalid skill directories and MCP transports fail before the SDK runtime starts.

For Fabric.start_runtime(...), the model provider, MCP configuration, and skill roots are fixed when the runtime starts and cannot vary between Runtime.invoke(...) calls. Start a new runtime to change them. Fabric.run(...) starts the same runtime, invokes it once, and stops it.

The Codex adapter does not declare tools.enabled or tools.blocked support. Codex can filter individual MCP server tools, but the pinned runtime does not provide one deny mechanism that covers built-in, local, MCP, and hosted tools. NeMo Fabric reports normalized blocked-tool policy as unsupported instead of enforcing only part of the requested policy.

Codex Runtime Ownership

The Codex SDK installs and selects its matching app-server runtime. NeMo Fabric does not declare or select the runtime package separately. A codex command on PATH does not replace the SDK-owned runtime.

Choose an Authentication Mode

Codex supports the following OpenAI authentication modes for local work:

With ChatGPT login, NeMo Fabric can run without OPENAI_API_KEY. With API key login, usage is billed through the OpenAI Platform account instead of ChatGPT plan credits. Refer to the Codex authentication documentation for current plan availability and login commands.

Reuse a Codex Login

Complete the Codex login outside NeMo Fabric. The adapter inherits CODEX_HOME (default: ~/.codex) and the SDK reuses the cached credential. If you select a different credential store, use the same value for login and execution:

$
export CODEX_HOME=/path/to/codex-home
$
codex login

For API key login, provision the credential store according to the current Codex authentication procedure:

$
export CODEX_HOME=/path/to/codex-home
$
printenv OPENAI_API_KEY | codex login --with-api-key

The login command is a credential-provisioning step. NeMo Fabric’s runtime path uses the SDK and does not invoke the command after the credential is cached. The adapter also forwards OPENAI_API_KEY and a selected model’s api_key_env, but the current real-agent acceptance path validates cached Codex authentication.

Treat CODEX_HOME/auth.json as a secret when Codex uses file-based credential storage. Do not commit or copy it into NeMo Fabric configuration or artifacts.

Use a Compatible Custom Provider

Use provider="openai" for Codex’s native authentication and endpoint discovery. For another provider name, set both api_key_env and base_url. The configured endpoint must implement the OpenAI Responses protocol. NeMo Fabric defines a runtime-scoped Codex model provider with the configured name; it does not maintain a provider-name allowlist or reuse the native Codex login for that provider.

Use Authentication with Relay

NeMo Relay does not replace model-provider authentication. A Relay-enabled NeMo Fabric runtime starts one gateway as a supervised sidecar and directs the selected Responses-compatible provider through it. For a configured custom provider, NeMo Fabric passes its explicit base_url to the gateway as the OpenAI-compatible upstream. The runtime reuses the gateway and SDK client across ordered invocations. Fabric.run(...) starts the same runtime, invokes it once, and stops it, so the gateway is scoped to that single invocation. The SDK still obtains credentials from the selected provider configuration.

NeMo Fabric supplies runtime-scoped Relay configuration to the SDK. It does not copy the Codex credential store into Relay configuration or persist credentials in Relay artifacts.

NeMo Fabric supports the external NeMo Relay CLI from 0.6.0 up to, but not including, 0.7.0. The Python package named nemo-relay is a separate library dependency and does not install the CLI. NeMo Fabric owns sidecar supervision and runtime-scoped SDK configuration. Relay owns gateway transport behavior, including decoding Content-Encoding before it constructs managed LLM events. There is no NeMo Fabric compression setting.

Compare Phoenix Trace Modes

Use native Codex OpenTelemetry when you need low-level app-server diagnostics. For Phoenix, send native OTLP/HTTP traces to the collector port, not the Phoenix web port:

1
from examples.code_review_agent import codex_config, with_native_otel
2
3
config = with_native_otel(codex_config())

The native configuration uses http://localhost:4318/v1/traces. Native Codex spans expose internal operations and can be high-volume; they do not provide an OpenInference conversation hierarchy or consistently populated prompt and response fields.

Use Relay OpenInference for semantic Phoenix inspection:

1
from examples.code_review_agent import codex_config, with_relay_openinference
2
3
config = with_relay_openinference(codex_config())

Relay produces a chain root with LLM and tool children, decoded request and response values, and token usage. This is the recommended mode for reviewing an agent turn in Phoenix. Use native Codex OpenTelemetry only when the raw app-server trace is the required diagnostic surface.