> 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. 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](/nemo/fabric/getting-started/install#install-nemo-relay),
then ensure `nemo-relay` is on `PATH`.

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

| 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 --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 for local work:

| Mode          | Credential Source                                   | Recommended Use                                         |
| ------------- | --------------------------------------------------- | ------------------------------------------------------- |
| ChatGPT login | Cached Codex login under `CODEX_HOME`               | Local development with an eligible ChatGPT plan         |
| API key login | API key provisioned into the Codex credential store | Usage-based or noninteractive OpenAI Platform workloads |

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](https://developers.openai.com/codex/auth/)
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:

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

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

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

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