CH·02CLI reference

deeprelay setup codex

Point Codex CLI at deeprelay (provider in config.toml, profile in deeprelay.config.toml)

Synopsis

Points Codex CLI at deeprelay. After it runs, codex sends its requests to deeprelay's OpenAI-compatible /v1/responses endpoint and uses a deeprelay model.

What it writes

Setup writes two files in the Codex directory (~/.codex/, or $CODEX_HOME). It edits them one key at a time, keeps your comments, formatting and every other table exactly as they are, and never rewrites a file.

config.toml always gets the deeprelay provider:

[model_providers.deeprelay]
name = "deeprelay"
base_url = "https://api.deeprelay.ai/v1"
env_key = "DEEPRELAY_API_KEY"
wire_api = "responses"

deeprelay.config.toml holds the deeprelay profile as four top-level keys. Current Codex loads /.config.toml for codex --profile , so this is the file codex -p deeprelay reads:

model = "deeprelay/deepseek-v4-pro"
model_provider = "deeprelay"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"

By default setup also makes deeprelay Codex's default by setting five top-level keys in config.toml:

Key	Value
`model_provider`	`"deeprelay"`
`model`	the model (`--model`)
`model_reasoning_effort`	the same effort as the profile
`model_reasoning_summary`	`"auto"`
`model_context_window`	95% of the model's context length in the deeprelay catalog, so Codex compacts the conversation before the model runs out of room

The effort and summary appear at the top of config.toml as well as in the profile because plain codex does not read the profile. Without them Codex would send no reasoning effort and would not ask for reasoning summaries.

Setup never writes model_max_output_tokens: current Codex has no such key. Every key setup writes is checked in CI against Codex's own generated config schema, pinned to the Codex version deeprelay supports.

base_url is the API base setup runs against (--api-base, or DEEPRELAY_API_BASE). model_reasoning_effort comes from --effort, or else from the efforts the catalog lists for the model. When the catalog lists none, setup uses medium, Codex's own default.

Your key never lands in a file

env_key holds only the name of an environment variable, DEEPRELAY_API_KEY. Codex reads the key from that variable whenever it starts. The setup diff shows this value as , because the key name contains "key". The value is just the variable name.

To set the variable, add this line to your shell rc (~/.zshrc, ~/.bashrc). Setup and --print print it with the absolute path of your deeprelay binary:

export DEEPRELAY_API_KEY="$('/usr/local/bin/deeprelay' auth token)"

Each new shell runs deeprelay auth token, which reads your key from the deeprelay credentials file (deeprelay login). The key is never stored in your rc file, config.toml or deeprelay.config.toml. If you rotate the key, the next shell picks up the new one. If DEEPRELAY_API_KEY is not set when you run setup, setup prints this line and tells you to add it.

There is no flag that takes a key, and setup never writes one into http_headers or anywhere else in the file.

Codex started from an IDE or another GUI app may not read your shell rc, so it will not see DEEPRELAY_API_KEY. The Codex guide at deeprelay.ai/docs/codex explains how to set the variable for each OS and IDE.

Modes

Default: writes the provider and the five top-level keys to config.toml, and the profile to deeprelay.config.toml. Start Codex with plain codex. All Codex usage then goes to deeprelay, including sessions that would otherwise use your ChatGPT plan. Setup prints this warning every time, even with --yes, and suggests --profile-only.
--profile-only: writes only the provider to config.toml and the profile to deeprelay.config.toml, and leaves Codex's default provider, model and reasoning settings alone. Run codex --profile deeprelay (or codex -p deeprelay) to use deeprelay. Codex reads model_context_window only at the top level, not from a profile, so the deeprelay profile uses Codex's default context window. Setup warns about this. Set model_context_window yourself, or switch defaults, if you need it.
--print: writes nothing and makes no API call. It prints the export line above. The line contains a command, never the key itself.
--refresh: updates the keys setup owns in both files from the current catalog: base_url, the model, model_reasoning_effort and model_context_window. It keeps the model already in the deeprelay profile unless you pass --model. It keeps your earlier choice between the default switch and --profile-only. It needs an earlier setup, and it shows a diff and backs up the files like setup does.
--remove: undoes a previous setup (see below).

Why there is no `--scope project`

Codex also reads a project-level .codex/config.toml, but that file cannot define providers or profiles. The deeprelay profile covers the per-project case: run codex --profile deeprelay in the projects where you want deeprelay.

Before anything is written

Setup resolves your key the way deeprelay auth token does: from DEEPRELAY_API_KEY if it is set, or else from the credentials file. It checks that the model exists on deeprelay and supports tool calling.

Setup then shows each file it will change, a key-by-key diff and the undo command, and asks you to confirm. --yes skips the prompt for scripts. If stdin is not a terminal and you did not pass --yes, setup stops without writing. If nothing would change, setup says Codex is already configured and stops there.

Only after you confirm does setup make its one real test call to /v1/responses: one input word, one output token, nothing stored. If any check fails, nothing is written and the command exits non-zero. If the API you are targeting does not serve /v1/responses yet, setup prints a note, skips the test call and continues.

If config.toml still has the [profiles.deeprelay] table an earlier setup wrote, the diff also shows the keys setup wrote there being removed: current Codex refuses codex -p deeprelay while that table exists. Keys in it you changed yourself are left alone, with a warning to move them into deeprelay.config.toml or delete them.

Warnings print to stderr, even with --yes:

the default switch routes all Codex usage to deeprelay (try --profile-only first);
model_provider already names another provider, which setup replaces;
with --profile-only, the profile uses Codex's default context window;
DEEPRELAY_API_KEY is not set in this shell, followed by the line to add to your shell rc;
config.toml has [profiles.deeprelay] keys or a top-level profile = "deeprelay" that setup does not own.

If the file already defines model_providers.deeprelay or profiles.deeprelay as dotted keys, an inline table or an [[array of tables]], setup stops with an error. The same happens if it cannot read the file. Rewrite that part as a normal [table] section and run setup again.

Backups and undo

Before each write, setup copies each file it is about to change to backups/. in the Codex directory, so both config.toml and deeprelay.config.toml are backed up. A later run never overwrites an earlier backup. For each file setup also records which keys it added or changed, and their earlier values, in .deeprelay-setup-codex-manifest.json (for config.toml) and .deeprelay-setup-codex-profile-manifest.json (for the profile file) in the same directory. No key is ever in them.

deeprelay setup codex --remove replays both records key by key:

keys setup added are deleted, the deeprelay provider table is removed once it is empty, and deeprelay.config.toml is deleted once nothing else is in it;
keys setup changed get their earlier values back;
keys you edited yourself after setup are left alone, with a warning naming each key and its file.

--remove shows one diff covering both files and asks for confirmation like setup does. Running it again, or running it when setup never ran, reports "nothing to remove" and exits 0. After removing, you can delete the DEEPRELAY_API_KEY line from your shell rc.

Upgrading from an earlier setup that wrote [profiles.deeprelay] into config.toml: run deeprelay setup codex again or --refresh. It removes the keys setup wrote in that table and writes deeprelay.config.toml.

Default model

The default is deeprelay/deepseek-v4-pro, from deeprelay's list of models tested with Codex. Override it with --model. The model must exist on deeprelay and support tool calling.

Examples

# Try deeprelay in a profile first (asks before writing)
deeprelay setup codex --profile-only
codex --profile deeprelay

# Make deeprelay Codex's default, no prompt
deeprelay setup codex --yes

# Pick a model and a reasoning effort
deeprelay setup codex --model deeprelay/deepseek-v4.1-flash --effort high

# Print the shell rc line
deeprelay setup codex --print

# Update the model settings from the catalog
deeprelay setup codex --refresh

# Undo
deeprelay setup codex --remove

deeprelay setup codex [flags]

Options

      --effort string   model_reasoning_effort: none|minimal|low|medium|high|xhigh|max (default: from the catalog, else medium)
  -h, --help            help for codex
      --model string    deeprelay model for the profile (and Codex's default model unless --profile-only) (default "deeprelay/deepseek-v4-pro")
      --print           Print the DEEPRELAY_API_KEY export line for your shell rc and write nothing
      --profile-only    Write only the deeprelay provider and the deeprelay profile file; leave Codex's default provider and model alone
      --refresh         Update the setup-owned keys (model, effort, context window, base_url) in config.toml and the deeprelay.config.toml profile file from the catalog
      --remove          Undo a previous setup key by key
      --yes             Apply without the confirmation prompt (warnings still print)

Options inherited from parent commands

      --api-base string   API base URL (override with DEEPRELAY_API_BASE env) (default "https://api.deeprelay.ai/v1")
      --debug             Enable debug logging to stderr
      --no-preflight      Skip the plan/credit check before inference requests (override with DEEPRELAY_NO_PREFLIGHT env)
  -o, --output string     Output format: table|json (default table on TTY, json otherwise) (default "table")