The nvidia.fabric.codex adapter uses the official Codex Python SDK behind
NeMo Fabric's normalized invocation contract. It does not resolve or execute a
separately installed codex command. The SDK package owns its pinned
app-server runtime and typed JSON-RPC protocol.
The following table shows which components each installation provides:
| Installation | Runtime | Adapter | Harness | NeMo Relay CLI |
|---|---|---|---|---|
pip install "nemo-fabric[codex]" |
Yes | Yes | Yes | Yes |
pip install "nemo-fabric-adapters-codex[harness]" |
No | Yes | Yes | Yes |
pip install nemo-fabric-adapters-codex |
No | Yes | No | No |
For an environment-managed SDK, use openai-codex==0.154.0. For split runtime
and adapter environments, configure ADAPTER_PYTHON and use matching NeMo
Fabric release versions. Refer to the
installation guide.
The full extra is equivalent to harness. Both install the supported NeMo
Relay CLI so Relay telemetry and Runtime.invoke_stream() work without a
separate CLI installation.
For a cached ChatGPT or Codex API-key login, NeMo Fabric reuses the
authentication state under CODEX_HOME (default: ~/.codex). Sign in with
Codex before running NeMo Fabric. Set CODEX_HOME to the same location for login
and execution if you use a nondefault credential store.
For noninteractive OpenAI API-key authentication, set
models.<role>.api_key_env to the name of an environment variable containing
the key. The adapter calls the Codex SDK's login_api_key during startup. It
creates a private, temporary CODEX_HOME outside Fabric artifacts for this
login, even if the host has another CODEX_HOME, and removes it after the
runtime stops or startup fails. This mode uses OpenAI Platform billing rather
than ChatGPT plan credits.
Treat any Codex CODEX_HOME/auth.json as a secret when Codex uses file-based
credential storage. Do not copy it into NeMo Fabric configuration or artifacts.
Refer to the
Codex authentication documentation
for login and credential-storage options.
The native openai provider retains Codex authentication and endpoint
discovery. For another provider name, configure both
models.<role>.api_key_env and models.<role>.base_url. The endpoint must
implement the OpenAI Responses protocol. The adapter defines a runtime-scoped
Codex model provider with that name and isolates its Codex state under the
NeMo Fabric artifact root, so execution does not depend on or modify a user's
Codex login. Provider names identify configuration; the adapter does not
maintain a provider allowlist.
The adapter uses the Codex SDK, which installs and selects its matching app-server runtime. NeMo Fabric does not declare the runtime package directly or treat it as a user-installed command or adapter descriptor requirement.
A codex command on PATH is not selected implicitly.
Each NeMo Fabric runtime currently starts one local adapter host and retains one
AsyncCodex client and one Codex thread. The Codex starts and controls its
pinned local codex app-server subprocess over JSON-RPC. Ordered
Runtime.invoke(...) calls reuse that client and thread directly; the adapter
closes the SDK client and app-server transport during Runtime.stop(). Codex
owns the transcript; NeMo Fabric owns runtime-to-thread correlation, timeout,
cancellation, and cleanup.
The result includes the SDK's typed terminal response, turn status, token usage, timing, and completed thread items. It does not expose CLI commands, return codes, stdout, or stderr.
Normalized usage contains invocation-local token counts from the SDK's cumulative thread totals, including cached input tokens. Input tokens already include cached tokens (input_tokens_include_cache=True). Reused threads report the difference from the previous invocation rather than counting the thread total again. Missing, invalid, or reset counters remain unknown; a missing snapshot requires a new baseline before differences can be reported. The adapter preserves native usage in output.usage, does not infer cost, and retains available usage on unsuccessful results. If the SDK raises before returning usage, normalized usage remains unavailable.
Use Fabric.check(environment=..., request=...) with a runtime ID and live, active, or ready. Checks run during an invocation and report busy or idle for NeMo Fabric activity.
livechecks whether the owned Codex app-server process has exited.activereads the selected native thread through the app-server request interface and confirms the thread is loaded.readyuses the same fresh native response as a readiness equivalent: the initialized thread must reportidleoractive. NativesystemErrorfails readiness;notLoadedreports a closed session.
Each check uses the caller's deadline. A pending native health request remains the only request in flight after a caller timeout. Later checks wait within their own deadlines, then obtain a fresh response after the pending request completes.
Run the credential-free native qualification with uv run --no-sync pytest tests/e2e/test_codex_checks.py -q. The tests use the SDK-pinned app-server and a local mock provider before, during, and after an invocation.
Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.
Use normalized FabricConfig fields for portable configuration:
modelsselects the Codex model. The nativeopenaiprovider retains Codex authentication and endpoint discovery. Any other provider name must configure a Responses-compatiblebase_urlandapi_key_env.instructions.systemsupportsreplaceand maps to Codex base instructions. Codex rejectsappendduring planning and direct adapter startup.runtime.timeout_secondssets the NeMo Fabric invocation deadline.environment.workspacesets the working directory, andenvironment.envsupplies explicit harness-visible variables.mcpmaps stdio, HTTP, and streamable HTTP servers into the Codex thread'smcp_serversconfiguration. For stdio, seturlto the executable and pass each command-line argument as a separateargselement.- Codex starts the configured MCP servers itself when the runtime starts and
leaves out the tools of a server that fails; the runtime starts with the
tools of the remaining servers. Every result from that runtime reports the
servers whose latest Codex startup status is failed under
output.mcp.unavailable_servers(name,transport, andreasonoffailed, orauthentication_requiredwhen Codex reports that stored OAuth credentials need reauthentication), and the adapter writes a warning to standard error. Codex error messages are omitted because they can carry credentials. A server that is still starting is not reported, and a new runtime starts every server again. Invalid server configuration, such as an unsupported transport or authentication mode, still fails startup. skills.pathsnames skill directories that containSKILL.md. The adapter registers each directory as a process-scoped Codex skill root so Codex can select matching skills through its normal discovery behavior.telemetryenables native OpenTelemetry or NeMo Relay observability.
Invocation deadlines return the normalized error code timeout, including when the deadline expires during MCP authentication; a Codex SDK request that times out earlier returns codex_timed_out. The adapter interrupts the active turn and closes the SDK before returning either outcome. With a timeout under 10 seconds, NeMo Fabric's own timeout can stop the adapter host before the interrupt finishes, which fails the invocation with a core host_timeout error instead.
The Codex adapter does not declare tools.blocked support. The current Codex
runtime has per-MCP-server tool filters, but it does not provide one complete
deny boundary for built-in, local, MCP, and hosted tools. NeMo Fabric therefore
routes normalized blocked-tool policy as unsupported instead of applying a
partial policy.
Only Codex-specific controls belong in harness.settings:
| Setting | Type | Required | Static Default |
|---|---|---|---|
sandbox |
One of read-only, workspace-write, or danger-full-access |
No | read-only |
approval_mode |
One of auto_review or deny_all |
No | auto_review |
developer_instructions |
Nonempty string | No | No default |
personality |
One of none, friendly, or pragmatic |
No | No default |
reasoning_effort |
One of none, minimal, low, medium, high, xhigh, max, or ultra |
No | No default |
service_tier |
Nonempty string | No | No default |
output_schema |
JSON Schema object for the final assistant message | No | No default |
config_overrides |
Object that maps nonempty dotted Codex configuration keys to JSON-compatible values | No | {} |
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 validates these settings against the schema in the resolved Codex
descriptor. Unknown keys, empty dotted-key segments, invalid types, and invalid
enum values fail before the adapter starts. Schema defaults are documentation
only; planning preserves the supplied settings without adding defaults.
config_overrides is the intentional adapter-specific escape hatch for Codex
configuration that has no normalized NeMo Fabric field.
Set model selection and endpoints through models, system instructions through
instructions.system, the invocation deadline through
runtime.timeout_seconds, and the working directory and explicit environment
through environment. In particular, the SDK's base_instructions value comes
from instructions.system, not harness.settings.
For Fabric.start_runtime(...), the model provider, MCP configuration, skill
roots, and config_overrides 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 adapter filters the inherited environment. It retains portable OS and
Codex state variables, the selected model's api_key_env, explicit
environment.env values, and variables named by environment.env_names
while clearing unrelated parent-process secrets.
Relay requires a NeMo Relay CLI in the >=0.9,<0.12 range on PATH. The
Codex adapter does not provide a separate relay extra; its harness and
full extras install the compatible CLI through nemo-relay-cli-bin. The root
nemo-fabric[relay] extra installs only the Relay Python package.
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.
Enable Relay with FabricConfig.enable_relay(...). The adapter starts the
installed nemo-relay CLI as a supervised sidecar; do not start the gateway
separately. The 30-second readiness wait starts after gateway launch and covers
required worker initialization. The Relay CLI check and plugin configuration
writing happen before launch and are outside this wait. Startup fails on early
process exit or an expired budget, and the gateway log is retained for diagnosis.
NeMo Fabric routes the selected Responses-compatible provider through the
gateway and passes its explicit base_url to Relay as the upstream endpoint.
For Relay-enabled runs, NeMo Relay CLI 0.11.x supports explicit trust for
HTTP model hosts. Set harness.settings.insecure_http_model_hosts to the exact
hostnames or IP addresses of your private inference gateways:
config.harness.settings["insecure_http_model_hosts"] = ["inference.internal", "10.0.0.10"]Entries contain no scheme, port, path, or wildcard. Matching ignores DNS case
and a trailing dot, permits any port or path on that host, and does not infer
trust from DNS resolution. The adapter passes this list to Relay's runtime
[upstream] configuration. An explicit empty list clears inherited HTTP trust;
omitting the setting preserves Relay's existing configuration behavior. System
Relay configuration takes precedence and can enforce an empty list.
This path is for unauthenticated model endpoints: Relay strips authorization, API-key, cookie, and other credential headers before remote HTTP forwarding, including model credentials supplied to the harness. Relay rejects conflicting upstream authorization configuration. Prompts and responses still travel over plaintext HTTP. HTTPS remains the default. This setting affects Relay-enabled Codex, Claude, and Pi model forwarding; MCP policy is unchanged. Older Relay CLIs reject the setting with an upgrade message.
Run the unit and opt-in real SDK tests separately:
uv run pytest tests/adapters/test_codex_adapter.py -q
RUN_FABRIC_CODEX_INTEGRATION=1 uv run pytest tests/e2e/test_codex.py -q
RUN_FABRIC_CODEX_RELAY_INTEGRATION=1 \
FABRIC_TEST_NEMO_RELAY_COMMAND=/path/to/nemo-relay \
uv run pytest tests/e2e/test_codex.py -qSet FABRIC_TEST_CODEX_BIN=/path/to/codex on either opt-in command to validate
an explicit app-server override instead of the SDK-pinned runtime.
The SDK test uses the current Codex authentication state and exercises both the single-invocation convenience API and multiple turns against one started runtime. The Relay test additionally requires an external gateway binary and verifies model responses, stable thread identity across turns, Agent Trajectory Observability Format (ATOF), and Agent Trajectory Interchange Format (ATIF); gateway startup alone is not a passing result. The semantic regression requires the LLM request content to be decoded. It also requires ATIF to contain the model, token usage, and expected agent response.