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. Both extras install the supported nemo-relay CLI. Codex does not import the Relay Python API, so this adapter does not provide a separate relay extra.

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.154.0, 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:

from nemo_fabric import HarnessConfig
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 with mode="replace"; the adapter passes that normalized value to the Codex SDK as base_instructions. The adapter rejects append.

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

ultra uses Codex’s model-specific effort selection. Codex resolves it to a supported provider effort; models without effort metadata fall back to medium.

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:

from examples.code_review_agent import codex_config
config = codex_config()
config.add_skill_path("./skills/code-review")
config.add_mcp_server(
    "repo",
    transport="stdio",
    url="repo-mcp",
    args=["--root", "."],
    exposure="harness_native",
)
config.add_mcp_server(
    "docs",
    transport="streamable-http",
    url="https://mcp.example.com/mcp",
    exposure="harness_native",
)

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:

With a cached login, NeMo Fabric inherits CODEX_HOME (default: ~/.codex) and the SDK reuses the credential. Complete the login before running NeMo Fabric. For a nondefault store, use the same value for login and execution:

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

For runtime API-key login, set models.<role>.api_key_env to the name of the environment variable containing the OpenAI API key. The adapter calls the Codex SDK’s login_api_key during startup. It creates a private, temporary CODEX_HOME outside the artifact root, ignoring a host CODEX_HOME for this run, then removes the temporary store when the runtime stops or startup fails. API-key usage is billed through the OpenAI Platform account rather than ChatGPT plan credits.

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. Refer to the Codex authentication documentation for current plan availability and credential-storage options.

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 wraps Codex PreToolUse checks so Relay launch errors, timeouts, and nonzero exits return exit code 2 with a blocking reason. This includes the exit code 1 used by Relay 0.9.x and 0.10.0. The wrapper allows 35 seconds for Relay, within the harness timeout of 45 seconds. Codex 0.154.0 can still continue if the wrapper itself fails to start or reaches the harness timeout.

NeMo Fabric supports the external NeMo Relay CLI in the >=0.9,<0.12 range. NeMo Fabric’s relay extra installs only the Relay Python library 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:

from examples.code_review_agent import codex_config, with_native_otel
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:

from examples.code_review_agent import codex_config, with_relay_openinference
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.

Runtime Health

Fabric.check() supports live, active, and ready. Liveness observes the owned app-server process. Active reads the selected loaded thread; ready requires a fresh thread status of idle or active.

Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.

Private HTTP model gateways with Relay

Relay-enabled runs can set harness.settings.insecure_http_model_hosts to an explicit list of hostnames or IP addresses, for example ["inference.internal", "10.0.0.10"]. This requires NeMo Relay CLI 0.11.x. Entries have no scheme, port, path, or wildcard; matching ignores DNS case and a trailing dot and permits any port or path on the listed host. An explicit empty list clears inherited HTTP trust. Omitting the setting preserves existing Relay configuration behavior. System Relay configuration takes precedence and can enforce an empty list.

Use this for unauthenticated inference gateways. Relay strips authorization, API-key, cookie, and other credential headers before remote HTTP forwarding, including credentials provided to the harness, and rejects conflicting upstream authorization configuration. Prompts and responses travel unencrypted. HTTPS remains the default, and MCP policy is unchanged. This option applies to Relay-enabled Codex, Claude, and Pi runs.