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.
/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 defaultconfig.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.
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.
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.
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.
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.tomlfile in Codex CLI 0.169.1 (older[profiles.dotprod]tables do not apply). - Default mode merges into
~/.codex/config.tomland also applies tocodex app-server, which rejects--profilein 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.
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
| 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 freshapp-servercatalog visibility using equivalent default config. - DotProd gateway test suite: Automated unit & integration coverage for
POST /v1/responses(JSON + SSE events, function/custom tools, multi-turnfunction_call_output,store: truerejection, 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.