1. Configure Codex

Codex CLI now uses two separate configuration layers:

• ~/.codex/config.toml – global settings: the default model, provider definitions, and feature flags
• ~/.codex/<profile-name>.config.toml – one file per profile, selected with --profile <profile-name>, which overrides the default model settings

Step 1a: Add the CBorg provider and default model to ~/.codex/config.toml

# Default model, used when no --profile is given (and always by the Codex App and VSCode Extension)
# Note: a top-level `profile = "..."` key is no longer accepted by Codex
model = "cborg-coder-max"
model_reasoning_effort = "high"
model_context_window = 600000
model_auto_compact_token_limit = 400000
model_provider = "cborg"
personality = "pragmatic"

[model_providers.cborg]
name = "CBorg API"
base_url = "https://api.cborg.lbl.gov/v1"
env_key = "CBORG_API_KEY"
supports_websockets = false
wire_api = "responses"

# Recommended setting - Fast mode costs 2.5x more for 50% speedup
[features]
fast_mode = false

[notice]
fast_default_opt_out = true

The recommended default, cborg-coder-max, is an experimental, free on-prem model with a very large context window. The settings above cap the context Codex uses at 600K tokens and compact the conversation once it reaches 400K, which keeps long sessions responsive. As an experimental model it may occasionally be unavailable; switch to one of the profiles below if requests fail.

Step 1b: Create profile files in ~/.codex/

Each profile is a separate .config.toml file. Create the ones you want to use:

~/.codex/cborg-gpt-mini.config.toml:

model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
model_provider = "cborg"
personality = "pragmatic"

~/.codex/cborg-gpt-large.config.toml:

model = "gpt-5.5"
model_reasoning_effort = "high"
model_provider = "cborg"
personality = "pragmatic"
plan_mode_reasoning_effort = "high"

~/.codex/cborg-gemini-pro.config.toml:

model = "gemini-pro-high"
model_provider = "cborg"
personality = "pragmatic"

~/.codex/cborg-gemini-flash.config.toml:

model = "gemini-flash-high"
model_provider = "cborg"
personality = "pragmatic"

The openai-* profiles below use OpenAI directly via ChatGPT Enterprise sign-on (no CBORG_API_KEY needed):

~/.codex/openai-gpt-large.config.toml:

model = "gpt-5.5"
model_reasoning_effort = "high"
personality = "pragmatic"

~/.codex/openai-gpt-mini.config.toml:

model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
personality = "pragmatic"

Step 1c (optional): Add CBorg MCP servers to ~/.codex/config.toml

CBorg proxies several MCP servers, authenticated with your CBORG_API_KEY. Append the ones you want to ~/.codex/config.toml:

# Web search
[mcp_servers.tavily]
url = "https://api.cborg.lbl.gov/mcp/tavily"
bearer_token_env_var = "CBORG_API_KEY"

# Up-to-date library documentation
[mcp_servers.context7]
url = "https://api.cborg.lbl.gov/mcp/context7"
bearer_token_env_var = "CBORG_API_KEY"

# Scientific literature search (arXiv, bioRxiv, medRxiv)
[mcp_servers.valency]
url = "https://api.cborg.lbl.gov/mcp/valency"
bearer_token_env_var = "CBORG_API_KEY"

Run /mcp inside Codex to confirm the servers are connected. See the MCP servers page for the full list.

Ready-to-use copies of all these files are available in the cborg-client/codex directory.

2. Start Codex

cd my-project
codex

This uses the default model (cborg-coder-max). Switch to a profile using the --profile flag, e.g.:

codex --profile cborg-gpt-mini
codex --profile cborg-gpt-large

Alternative: Launch with a Shell Function

To use CBorg without editing any files in ~/.codex/, pass the provider, model, and MCP settings as -c overrides. Add this function to your ~/.zshrc or ~/.bashrc:

codex-cborg() {
  command codex \
    -c 'model_provider="cborg"' \
    -c 'model_providers.cborg.name="CBorg API"' \
    -c 'model_providers.cborg.base_url="https://api.cborg.lbl.gov/v1"' \
    -c 'model_providers.cborg.env_key="CBORG_API_KEY"' \
    -c 'model_providers.cborg.wire_api="responses"' \
    -c 'model_providers.cborg.supports_websockets=false' \
    -c 'model="cborg-coder-max"' \
    -c 'model_reasoning_effort="high"' \
    -c 'model_context_window=600000' \
    -c 'model_auto_compact_token_limit=400000' \
    -c 'mcp_servers.tavily.url="https://api.cborg.lbl.gov/mcp/tavily"' \
    -c 'mcp_servers.tavily.bearer_token_env_var="CBORG_API_KEY"' \
    -c 'mcp_servers.context7.url="https://api.cborg.lbl.gov/mcp/context7"' \
    -c 'mcp_servers.context7.bearer_token_env_var="CBORG_API_KEY"' \
    -c 'mcp_servers.valency.url="https://api.cborg.lbl.gov/mcp/valency"' \
    -c 'mcp_servers.valency.bearer_token_env_var="CBORG_API_KEY"' \
    "$@"
}

Then start Codex with codex-cborg from your project directory. Any other arguments are passed through to codex. To use a different model for one session, add another override, e.g. codex-cborg -c 'model="gpt-5.5"'.

Tips for Reducing Costs

1. Disable fast mode

Fast mode costs 2.5x more than standard processing, and is only about 50% faster. The configuration above disables it by default via fast_mode = false in [features]. You can also toggle it at runtime using the /fast command.

2. Use a smaller model for most tasks

Only switch to a large model when necessary:

• cborg-coder-max is free – try it first for everyday coding work.
• gpt-5.4-mini with “medium” reasoning is around 1/10th the cost of gpt-5.5 and is very performant – try to use the smaller model for most situations and switch to the large model only for the most challenging coding or debugging tasks.
• gpt-5.3-codex has nearly the same performance as gpt-5.5 and is around 1/2 of the cost
• Use /new for each new task rather than allowing excessive context to accumulate
• Disable any unnecessary MCP servers and Skills
• Keep AGENTS.md files to a reasonable length and do not include instructions that mirror what models already do by default, such as “Write clean code.”

3. Recommended default configuration

The configuration in step 1 above sets the free cborg-coder-max model as the default, with fast mode disabled. Switch to a larger or alternative model only when needed using the --profile flag.