Codex App

Quickstart#

Log in to Stimulir, then configure Codex through the CLI. The Stimulir provider is scoped by the project id you pass to configure and the short-lived key the CLI mints per request. The launcher writes a reversible provider block to your user-level Codex config; sync-models additionally registers the Stimulir models with Codex so they resolve by name.

stimulir login

stimulir codex configure \
  --project <project-id> \
  --model zai-org/GLM-5.2 --yes

stimulir codex sync-models   # models by name in the codex CLI/TUI picker

Restart Codex App after configuring. Use --dry-run to print the exact TOML that would be written, or stimulir codex restore to remove every Stimulir-managed block and return Codex to its previous provider.

stimulir codex configure --model moonshotai/Kimi-K2.6 --project <project-id> --dry-run
stimulir codex restore

Model selection#

Codex runs with one active model at a time. Switch it in place with stimulir codex model, shorthands match, and --relaunch restarts Codex App so the change loads immediately.

stimulir codex model kimi-k2.7 --relaunch
stimulir codex model glm --relaunch
stimulir codex model fusion --relaunch

Vision#

Image inputs route by model. moonshotai/Kimi-K2.6 sees attached images natively. stimulir/fusion accepts images too: a vision perceiver (Kimi K2.6 by default) analyzes them first and its analysis becomes shared grounding for the whole panel, so text-only panelists participate fully. Oversized screenshots are downscaled and context-budgeted by the gateway, so full-resolution attachments cannot overflow a model's context window. See Stimulir Fusion.

Fusion knobs from Codex#

Codex requests always carry tools, and fusion's default tools_mode is "bypass", so out of the box, stimulir/fusion in Codex answers with the judge model alone. Codex cannot set request-body keys, but it can send static headers: add an X-Fusion header to the provider block to turn on the full panel (and any other fusion option) for every Codex request:

[model_providers.stimulir]
# ...existing keys...
http_headers = { "X-Project-Id" = "<project-id>", "X-Fusion" = '{"tools_mode": "panel", "mode": "auto"}' }

tools_mode: "panel" runs the panelists in prose and lets the judge keep Codex's tools; mode: "auto" skips the panel on simple turns so agent loops stay fast and cheap. Expect panel turns to cost and take roughly the size of the panel.

Generated Codex config#

The launcher writes provider config to ~/.codex/config.toml, because Codex does not allow project-local config files to change model providers or provider authentication.

# >>> stimulir codex root
model = "zai-org/GLM-5.2"
model_provider = "stimulir"
model_supports_reasoning_summaries = false
# <<< stimulir codex root

# >>> stimulir codex provider
[model_providers.stimulir]
name = "Stimulir"
base_url = "https://api.stimulir.com/api/v1/inference"
wire_api = "responses"
stream_idle_timeout_ms = 300000
http_headers = { "X-Project-Id" = "<project-id>" }

[model_providers.stimulir.auth]
command = "stimulir"
args = ["codex", "token", "--session-id", "codex-app", "--ttl-seconds", "3600"]
timeout_ms = 10000
refresh_interval_ms = 1800000
# <<< stimulir codex provider

API contract#

Codex speaks the OpenAI Responses API to custom providers (wire_api = "responses"). The gateway serves it as a translation layer over chat completions, so every Stimulir-routed model, including stimulir/fusion, works through Codex with streaming, tool calls, and usage attribution intact. See the Inference API.

codex --strict-config doctor --json --summary
codex exec "Say hello through the configured Stimulir provider"

Team setup

Each teammate runs the same four commands with their own Console login. Auth keys are minted per user; traces attribute to the shared project, no shared secrets to distribute.

pip install stimulir
stimulir login
stimulir codex configure --project <project-id> --model zai-org/GLM-5.2 --yes
stimulir codex sync-models

Manual configuration

For a first trial, generate the config without launching Codex, inspect it, then restart Codex App manually. Add --staging to target the staging environment instead of production.

stimulir codex configure \
  --project <project-id> \
  --model zai-org/GLM-5.2 \
  --dry-run