- Route all model traffic through the TrueFoundry AI Gateway for centralized access control, routing, and cost governance.
- Enforce Codex configuration consistently across every developer machine using MDM, including which gateway Codex talks to and how it authenticates.
tfy-local-ai-setup binary this guide deploys also enforces Claude Code and Claude Desktop (Cowork 3P) fleet-wide. Pass --codex to configure Codex only, or omit all tool flags to auto-detect and configure every client that is installed. Prebuilt binaries for every platform are on the releases page.1. Identity (prerequisite)
Before rolling out Codex, enforce SSO and workspace membership in your OpenAI admin console so access is tied to your IdP and employees can’t fall back to personal accounts. See OpenAI’s managed-configuration docs. With TrueFoundry, developers don’t manage personal API keys. Authentication is handled automatically by thetfy-local-ai-setup binary deployed via MDM (see Enforce settings with MDM). It fetches a fresh gateway token scoped to the user’s TrueFoundry identity and writes it into Codex’s managed configuration.
2. Route model traffic through TrueFoundry AI Gateway
Codex reads its model provider fromconfig.toml. Pointing it at the TrueFoundry AI Gateway means every request passes through a single control point before reaching any provider:
3. Enforce settings with MDM
Codex reads configuration in priority order, with the system-levelmanaged_config.toml taking precedence over the developer’s own file:
/etc/codex/managed_config.toml.
The binary writes the gateway provider block and the auth header into managed_config.toml, then locks the file. Because managed_config.toml is reapplied on every launch, a developer editing their own ~/.codex/config.toml cannot move Codex off your gateway. With the default api-key auth mode the result looks like this:
model key is written only when you set CODEX_DEFAULT_MODEL; otherwise model selection stays with the developer. Point it at a virtual model slug so you can change routing centrally without redeploying the script.
Deployment scripts
The scripts below deploy and lockmanaged_config.toml. On every run the script fetches a fresh gateway token for the logged-in user and writes it into the provider’s auth header, so no PAT or manual credentials are needed. Schedule the script to run hourly so the token stays fresh; the browser device flow only appears on first run or after the refresh token expires.
The scripts download the tfy-local-ai-setup binary from the truefoundry/tfy-local-ai-setup GitHub repo. The README there documents all available flags and advanced usage (config templates, manual runs).
How the script works
The script runs as root on a schedule (recommended: hourly) and does four things on every execution:
-
Saves and loads config. On first run, the three required values (
GATEWAY_URL,CONTROL_PLANE_URL,TENANT_NAME) are read from the script’s Config section and written to a root-owned config file (macOS:/Library/Preferences/com.truefoundry.tfy-local-ai-setup.conf; Linux:/etc/tfy/tfy-local-ai-setup.conf). On subsequent runs the file is loaded automatically, so no changes to the script are needed. This is the same config file the Claude MDM script uses, so a machine running both shares one saved configuration. -
Installs or updates
tfy-local-ai-setup. Downloads the binary if it is not present or if the installed version does not matchRELEASE_TAG. On subsequent runs where the version already matches, this step is skipped entirely. -
Detects the logged-in user and fetches a fresh auth token. The binary identifies who is currently logged into the machine, then silently refreshes the token from
~/.tf/refresh-token. The browser device-authorization flow only appears the very first time, or after the refresh token has expired. Every other run completes silently in the background. -
Writes and locks
managed_config.toml. The binary builds the TOML with the AI Gateway URL, the selected auth mode, and the freshly fetched token, then writes it to/etc/codex/managed_config.tomland locks the file so developers cannot modify it (macOS:chflags schg; Linux:chattr +i).
- macOS
- Linux
--codex flag to auto-detect and configure every supported client that is installed (Claude Code, Claude Desktop, Codex), or add --claude-code and --claude-desktop alongside it to manage those explicitly in the same run.Verify the deployment
After the first run, confirm the file was written and locked:- macOS
- Linux
codex and send a prompt. The request should appear in the AI Gateway’s request logs, attributed to the logged-in developer.
To preview the exact TOML without writing anything, which is useful when validating flags before a fleet rollout, add --dry-run:
Using Codex MDM with a ChatGPT Business or Enterprise subscription
If your organization buys Codex through a ChatGPT Business or Enterprise subscription rather than a usage-based OpenAI API key, the MDM setup requires one additional configuration step on TrueFoundry: you create an OpenAI model account that acts as a pass-through, and the OpenAI credentials are supplied at request time by each developer’s own ChatGPT account rather than stored on TrueFoundry. This approach also gives you per-user usage attribution on both sides. TrueFoundry logs which user made each request, and OpenAI attributes usage to the individual ChatGPT seat. Codex sends its own ChatGPT OAuth token upstream, while a separatex-tfy-api-key header authenticates the developer to TrueFoundry, so every request carries their identity end to end.
Create an OpenAI model account on TrueFoundry
https://chatgpt.com/backend-api/codex. This is the endpoint Codex uses for ChatGPT subscription traffic, not the default OpenAI API endpoint.When prompted for authentication credentials, leave the API key field empty. Do not enter any API key or secret. The actual ChatGPT credentials are sent by Codex from the developer’s subscription session and forwarded by the AI Gateway at request time.Copy the model IDs
chatgpt-codex/gpt-5.2-codex). Copy these from the model account detail page, or create a virtual model that fronts them.Set the auth mode in the MDM script
requires_openai_auth = true into the provider block and moves the TrueFoundry token from the Authorization header to x-tfy-api-key:requires_openai_auth = true tells Codex to attach the developer’s own ChatGPT OAuth token as the Authorization header. That frees x-tfy-api-key to carry the TrueFoundry credential, and the AI Gateway reads the two independently: x-tfy-api-key authenticates the developer to TrueFoundry, while the Authorization bearer is treated as the upstream provider credential and used to authenticate against OpenAI. In the default api-key mode there is no ChatGPT token, so the TrueFoundry token travels in Authorization instead.
Using a virtual model with a ChatGPT subscription
The MDM setup works with virtual models as well. Point CODEX_DEFAULT_MODEL at a virtual model slug instead of a direct model ID and you get two immediate benefits:
- Fallbacks: if one target is unavailable, traffic automatically falls through to the next.
- Model changes without touching the MDM script: update the virtual model’s routing on TrueFoundry and the change takes effect across all managed machines with no script redeployment.
401 Unauthorized or 403 Forbidden can come from either side, and the fix differs:
- The developer’s ChatGPT session expired. They need to run
codexand sign in to their ChatGPT account again. - The TrueFoundry token expired. The next hourly MDM run refreshes it silently. To fix it immediately, re-run the binary manually (see the FAQ below).
401, 403 or 429 does not put the shared target into load-balancer cooldown, so one developer exhausting their ChatGPT quota cannot affect anyone else’s routing.
4. Observability with TrueFoundry
When Codex traffic flows through the TrueFoundry AI Gateway, you get built-in observability across both LLM and MCP requests, with no extra instrumentation. Request tracing: every request is traced with full attribution (user, model, token counts, latency, cost).

chatgpt-subscription flow, attribution lands on both sides: TrueFoundry records the developer’s identity from x-tfy-api-key, and OpenAI attributes the usage to that developer’s ChatGPT seat.
5. Data retention and compliance
Retention of prompts and outputs is governed by your agreement with OpenAI and differs between API and ChatGPT subscription plans. Review your enterprise agreement for the full scope, and see OpenAI’s managed-configuration docs for the admin controls available on your plan. On the TrueFoundry side, the AI Gateway is the single point where you control what is logged and where it goes: request tracing with per-user attribution, configurable prompt logging, and OTEL export into your own SIEM. Because all Codex traffic is routed through the gateway, your audit trail does not depend on any client-side setting a developer could change.Frequently asked questions
Why route Codex through TrueFoundry instead of straight to OpenAI?
Why route Codex through TrueFoundry instead of straight to OpenAI?
How does authentication work without distributing API keys?
How does authentication work without distributing API keys?
tfy-local-ai-setup binary and runs it on a schedule (hourly) to fetch a fresh gateway token scoped to the user’s TrueFoundry identity. In api-key mode the token is written into the provider’s Authorization header. In chatgpt-subscription mode it goes into x-tfy-api-key and the developer’s own ChatGPT credentials carry the upstream auth. Either way it is a short-lived token, refreshed automatically, so there are no personal or long-lived API keys on developer machines.How long is the refresh token at ~/.tf/refresh-token valid?
How long is the refresh token at ~/.tf/refresh-token valid?
tfy-local-ai-setup uses the TrueFoundry Auth Server refresh token rather than setting its own expiry. Each successful MDM run rotates the token and writes a new 30-day value. If the script runs at least once within those 30 days, no re-login is required. After 30 days without a refresh, the next run opens the browser device-authorization flow.Does this MDM setup control which MCP servers Codex can use?
Does this MDM setup control which MCP servers Codex can use?
managed_config.toml, which covers the model provider and auth. Codex’s admin enforcement of which MCP servers a developer may enable lives in a separate requirements.toml (/etc/codex/requirements.toml on macOS and Linux) that tfy-local-ai-setup does not write, so deploy it alongside this script if you need that. See OpenAI’s managed-configuration docs for its format, and Codex web search for pointing Codex at a gateway-governed MCP server.Can I manage Codex on Windows?
Can I manage Codex on Windows?
~/.codex/managed_config.toml, while the MDM binary runs as SYSTEM, so it skips Codex on Windows with a warning. Claude Code and Claude Desktop are both supported on Windows; see the Claude MDM guide.I accidentally closed the browser login window. Do I have to wait for the next MDM sync?
I accidentally closed the browser login window. Do I have to wait for the next MDM sync?
- macOS
- Linux
Related
- OpenAI Codex CLI: single-developer setup for both auth modes, plus MCP-based web search through the gateway.
- Securing Claude Code with TrueFoundry: the same MDM binary for Claude Code, including Windows.
- Govern all AI traffic: which AI clients can be enforced via MDM and which need an on-device agent.
- TrueFoundry MCP Gateway: centralized MCP registry, auth, and audit trail.