Codex

Codex connects to Actualyze as a custom model provider. You point it at the OpenAI-compatible endpoint and give it your Actualyze API key through an environment variable. Codex speaks the OpenAI Responses API, so the model you use must be served over that API.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your Codex usage draws down.
• A model in your workspace that your key can call and that is served over the OpenAI Responses API. See Choose a model.

#Install

If Codex isn't installed yet, use OpenAI's standalone installer. On macOS and Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows, from PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Codex also installs with npm install -g @openai/codex or brew install --cask codex. The Codex repository lists the release binaries.

#Connect to Actualyze

#Option 1: config.toml

Add Actualyze as a model provider and make it the default:

model_provider = "actualyze"
 
[model_providers.actualyze]
name = "Actualyze"
base_url = "https://app.actualyze.ai/openai/v1"
env_key = "ACTUALYZE_API_KEY"

Then set the key and start Codex:

export ACTUALYZE_API_KEY="<your-actualyze-api-key>"
codex

• env_key names the environment variable that holds your key. Codex reads the key from it and sends it as a bearer token. The name ACTUALYZE_API_KEY is a convention; any name works if both places match.
• If the file already has other settings, keep model_provider (and model, below) above the first [table] header. A key placed after a table header belongs to that table, so Codex won't read it as a top-level setting.
• Put this in your user-level ~/.codex/config.toml. Codex ignores model_provider and model_providers in a project's .codex/config.toml.
• To keep the key across sessions, add the export line to your shell profile (~/.zshrc or ~/.bashrc).

Inside Codex, run /status to check that the provider is actualyze and see which model is active.

#Option 2: command-line overrides

To try Actualyze without editing config.toml, pass the same settings with -c on each run:

export ACTUALYZE_API_KEY="<your-actualyze-api-key>"
 
codex \
    -c 'model_providers.actualyze={ name = "Actualyze", base_url = "https://app.actualyze.ai/openai/v1", env_key = "ACTUALYZE_API_KEY" }' \
    -c model_provider="actualyze"

• Keep the whole model_providers.actualyze={ … } value on one line. A backslash inside single quotes is literal, so a wrapped value hands Codex a string it can't parse.
• The provider name after model_providers. must match the model_provider value. Both are actualyze here.

#Choose a model

Codex uses its own built-in default model unless you set model. If your workspace doesn't serve that name, set one explicitly:

model = "<model-id>"
model_provider = "actualyze"
 
[model_providers.actualyze]
name = "Actualyze"
base_url = "https://app.actualyze.ai/openai/v1"
env_key = "ACTUALYZE_API_KEY"

With command-line overrides, add -c model="<model-id>", or pass -m <model-id>.

• Use a catalog model ID or a Virtual Model slug, written exactly as Actualyze lists it, without adding a provider/ prefix of your own.
• The model must be served over the OpenAI Responses API. Codex asks for encrypted reasoning on every request, which only a same-protocol Responses route can return, so any other model fails with a 400.
• In the Actualyze app, the Connect app dialog on each model in the Model Catalog dims Codex for models that aren't served over the Responses API. Use it to check a model before you set it.
• Codex doesn't discover models from Actualyze: its /model picker keeps showing Codex's own built-in list. Name the model in config.toml, with -c, or with -m.

#Troubleshooting

• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. Check that ACTUALYZE_API_KEY holds the right key; an unset variable fails in Codex before any request is sent. The key may also be revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Codex says Missing environment variable: `ACTUALYZE_API_KEY`.: the variable named in env_key is unset or empty in the shell that runs Codex, so no request was sent. Export it and start Codex again.
• Codex says Model provider `actualyze` not found: the model_provider value doesn't match the name under [model_providers.…]. They must be identical.
• 400 with the code no_fidelity_preserving_route, saying the request needs a same-protocol Responses endpoint: the model isn't served over the Responses API. Pick one that is, or ask your administrator which models are.
• 404 saying Model "<model-id>" not found: the model value doesn't match a catalog model or Virtual Model your workspace serves.
• Codex warns Model metadata for `<model-id>` not found. Defaulting to fallback metadata: Codex doesn't recognize the name (common for a Virtual Model slug) and assumes a 272,000-token context window. Requests still go through. If the model's context window is smaller, set model_context_window near the top of config.toml to that size, so Codex compacts the conversation before it overflows.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed. Actualyze labels this traffic as Codex in the Client column of the Observability Activity tab, which Workspace Admins, FinOps Managers and Auditors can see.

For everything config.toml accepts and the -c override syntax, see OpenAI's Codex configuration reference. OpenAI's guide to connecting Codex through a gateway covers the same provider setup from Codex's side.