> This page is for NeMo Fabric, version v0.5.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.4.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.0/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/fabric/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/fabric/_mcp/server.

# Use the Codex Adapter

> Configure capabilities, authentication, and telemetry for the NeMo Fabric 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```python
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:

| Setting                  | Type                                                                                | Static Default |
| ------------------------ | ----------------------------------------------------------------------------------- | -------------- |
| `sandbox`                | One of `read-only`, `workspace-write`, or `danger-full-access`                      | `read-only`    |
| `approval_mode`          | One of `auto_review` or `deny_all`                                                  | `auto_review`  |
| `developer_instructions` | Nonempty string                                                                     | No default     |
| `personality`            | One of `none`, `friendly`, or `pragmatic`                                           | No default     |
| `reasoning_effort`       | One of `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`                       | No default     |
| `service_tier`           | Nonempty string                                                                     | No default     |
| `output_schema`          | JSON Schema object for the final assistant message                                  | No default     |
| `config_overrides`       | Object that maps nonempty dotted Codex configuration keys to JSON-compatible values | `{}`           |

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:

```python
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:

| Mode                  | Credential Source                                         | Recommended Use                                    |
| --------------------- | --------------------------------------------------------- | -------------------------------------------------- |
| Cached ChatGPT login  | Existing Codex login under `CODEX_HOME`                   | Local development with an eligible ChatGPT plan    |
| Cached API key login  | Existing Codex credential store under `CODEX_HOME`        | OpenAI Platform workloads with a provisioned store |
| Runtime API key login | Environment variable named by `models.<role>.api_key_env` | Noninteractive OpenAI Platform workloads           |

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:

```bash
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](https://developers.openai.com/codex/auth/)
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 supports the external NeMo Relay CLI in the `>=0.9,<0.10` 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:

```python
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:

```python
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.