dotprodCodex CLI guide
Persistent Codex CLI Integration · macOS Keychain Auth · Reference catalog tested with Codex CLI 0.169.1

Connect Codex CLI to DotProd

Keep a DotProd model available across Codex CLI sessions using the /v1/responses HTTP/SSE adapter, a saved provider configuration, a Codex-native model-picker catalog, and credentials read from macOS Keychain.

Uses DotProd’s /v1/responses HTTP/SSE endpoint.

Codex sends requests to POST /v1/responses with store: false, streaming SSE events, and function/custom tools. All requests share DotProd’s existing virtual-key auth, tenant isolation, S1–S14 guardrail policy, and deterministic Durable Object credit accounting. WebSockets, server-side store: true, hosted search, and image modalities are not advertised or enabled.

Connection address
Responses base URL ending in /v1 (Codex appends /responses)
Authentication
DotProd virtual key (sk-...) stored in macOS Keychain; upstream secrets stay server-side
Persistent selection
Named profile (dotprod.config.toml) or merged default config.toml + Codex catalog

Generate your configuration

Select a tenant-enabled model ID and enter its verified context limit. Your local macOS home path stays strictly in this browser tab’s memory and is never sent to DotProd. Enter your API key only at the hidden Terminal prompt below.

Store the DotProd virtual key

Run this command in Terminal and paste your DotProd virtual key (sk-...) at the hidden prompt. Keep -w last so the key never appears in shell history. Upstream provider secrets remain server-side on DotProd.

Terminal · hidden password entry
security add-generic-password \
  -U \
  -a "$USER" \
  -s dotprod-codex \
  -w

Create a credential helper

Codex invokes this executable helper when it needs authentication. Inspect any existing file before replacing it. Avoid running the helper directly in a recorded or shared terminal because it prints the key to stdout.

Terminal · create the helper
mkdir -p "$HOME/.local/bin"
cat > "$HOME/.local/bin/dotprod-codex-key" <<'SH'
#!/bin/sh
exec /usr/bin/security find-generic-password \
  -a "$USER" \
  -s dotprod-codex \
  -w
SH
chmod 700 "$HOME/.local/bin/dotprod-codex-key"

Save the provider and model entry

Save or merge this TOML in ~/.codex/dotprod.config.toml.

Back up any existing destination file before editing. When merging into ~/.codex/config.toml, preserve unrelated settings (permissions, MCP servers, other providers), keep top-level keys above TOML table headers, and avoid duplicate [model_providers.dotprod] tables.

~/.codex/dotprod.config.toml

          
Use one authentication method.

This provider uses [model_providers.dotprod.auth]. Do not combine it with env_key, experimental_bearer_token, or requires_openai_auth on the same provider.

Save the Codex-native model-picker catalog

A standard OpenAI GET /v1/models response does not replace Codex’s catalog schema. Save the generated catalog at the exact model_catalog_json path shown below. If you run a scheduled catalog generator, update the generator rather than editing only its output file.

~/.codex/model-catalogs/dotprod.json

          

Create ~/.codex/model-catalogs if needed (mkdir -p ~/.codex/model-catalogs). The reference catalog schema is validated with Codex CLI 0.169.1 and uses conservative text-only capabilities; verify context window and tool support as Codex evolves.

What persists and what it affects
  • Named profiles use a separate ~/.codex/dotprod.config.toml file in Codex CLI 0.169.1 (older [profiles.dotprod] tables do not apply).
  • Default mode merges into ~/.codex/config.toml and also applies to codex app-server, which rejects --profile in CLI 0.169.1.
  • Desktop, editor, and cloud surfaces require independent verification.
  • Keep retries at zero during initial validation; enable production retries only after confirming idempotency and credit accounting.

Launch future sessions

Use the saved profile each time you want DotProd.

Terminal · select DotProd

          

Use /status and /model to inspect the active session. Restart after editing TOML or catalog files.

Manual verification checklist (user notes)

These checkboxes are local user notes only and do not represent automated verification. They reset on reload. Real inference tests may incur workspace charges.

0 of 7 manual notes checked.

Maintain access

Rotate your key

Issue a replacement key in the DotProd Workspace, update the Keychain item, restart and verify Codex, then revoke the previous key.

Switch models

Update both the TOML model ID and the catalog slug/context_window, confirm the model is enabled on your workspace, and restart Codex.

Retire the setup

Revoke the DotProd key, restore or remove the DotProd TOML/catalog entries, and delete unused helper/Keychain entries while keeping other providers intact.

Troubleshooting

Common Codex and DotProd Responses API error codes and remedies
Symptom / HTTP Status What to check
400 Unsupported parameter, store: true, or hosted tool Confirm Codex sends store: false without previous_response_id, hosted search, or image modalities.
400 Content policy blocked A guardrail category triggered; verified Cyber/Bio researchers can request per-tenant S1–S14 guardrail overrides in Staff Operations.
401 / 403 Unauthorized or model denied Verify macOS Keychain access, key revocation status, active workspace status, and that the exact model ID is enabled for your tenant.
402 Insufficient funds Check prepaid credit balance, free-token allowance, and active holds in your DotProd Workspace.
404 on /responses Confirm the base URL ends with /v1 (not /v1/responses) and the Responses adapter is deployed.
429 Rate limit or monthly budget Workspace RPM or UTC monthly spend cap was reached; wait for the retry window or adjust budget.
Model absent from picker Verify the absolute model_catalog_json path, valid JSON, visibility: "list", and that you launched with the matching profile/default config.

Need help? Contact security@dotprod.tech with your request timestamp and workspace ID—never include your sk-... key.

Sanitized test receipts & references

Recorded verification receipts (separate from manual checklist)

  • Local Codex CLI 0.169.1 fixture check: Passed named profile (dotprod.config.toml), command-backed bearer auth, Responses SSE streaming (CODEX_ROUTE_OK), and fresh app-server catalog visibility using equivalent default config.
  • DotProd gateway test suite: Automated unit & integration coverage for POST /v1/responses (JSON + SSE events, function/custom tools, multi-turn function_call_output, store: true rejection, tenant isolation, and Durable Object billing).
  • Scope boundary: Fixture and unit receipts do not substitute for approved staging verification against a live paid upstream provider.