> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # Codex with MDM > Configure Codex CLI and the Codex desktop app through MDM: models, Windows enforcement, ChatGPT subscriptions, and how to verify the TrueFoundry AI Gateway setup. This page covers the Codex-specific parts of an MDM rollout. Start with the [MDM overview](https://www.truefoundry.com/docs/ai-gateway/mdm-setup.md) to create the deployment script, then use these options in its TOML block. One configuration covers both the Codex CLI and the Codex desktop app, on macOS, Linux, and Windows. ## What gets written | Platform | File | Precedence | | - | - | - | | macOS, Linux | `/etc/codex/managed_config.toml` | Overrides the employee's `~/.codex/config.toml` and is reapplied on every launch | | Windows | `C:\ProgramData\OpenAI\Codex\requirements.toml` | Enforced; overrides the employee's config. Requires Codex 0.156.0 or later | | Windows | `C:\ProgramData\OpenAI\Codex\config.toml` | Machine defaults, including MCP servers. Lowest precedence | The binary writes a `truefoundry` model provider that points at your gateway with `wire_api = "responses"`, the employee's sign-in, your default model, and gateway MCP servers. It locks each file. On Windows, it also locks the `C:\ProgramData\OpenAI\Codex` directory so that only administrators can create files there, because Codex loads any configuration it finds in that directory. Do not relax that permission. > [!WARNING] > > **On Windows, enforcement requires Codex 0.156.0 or later.** Older versions ignore the provider in `requirements.toml` and use only `config.toml`, which an employee can override in their own configuration. Check `codex --version` across your fleet. Sign-in depends on the [method you chose](https://www.truefoundry.com/docs/ai-gateway/mdm-setup.md#choose-how-employees-sign-in): | Method | What is written | | - | - | | Device login | `[model_providers.truefoundry.http_headers]` with `Authorization = "Bearer "`, refreshed on every run | | OIDC | `[model_providers.truefoundry.auth]` with a `command` that runs the binary with `--_print-oidc-token`. No token is stored; Codex asks the binary when it needs one | | ChatGPT subscription | `x-tfy-api-key = ""` and `requires_openai_auth = true`. See [below](#use-a-chatgpt-business-or-enterprise-subscription) | ## Choose a model Codex needs a [Virtual Model whose slug is a bare OpenAI model ID](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli.md#why-you-need-a-virtual-model), such as `gpt-5.4`, rather than a provider-prefixed ID: ```toml theme={"dark"} [agents.codex] model = "gpt-5.4" ``` If you omit `model`, no default model is set. Because the model is a Virtual Model, you can change its routing or add fallbacks in TrueFoundry without redeploying the script. ## Use a ChatGPT Business or Enterprise subscription Use this when your organization pays for Codex through ChatGPT seats instead of an OpenAI API key. Codex sends each employee's own ChatGPT credential to OpenAI, and the gateway authenticates the employee separately, so usage is attributed to the employee on both sides. **1. Create the OpenAI model account** In TrueFoundry, add an OpenAI model account with the base URL `https://chatgpt.com/backend-api/codex` and an **empty API key**, as described in the ChatGPT tab of [Configure Codex](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli.md#1-configure-codex). Create a Virtual Model for it or copy its model ID. > [!WARNING] > > Keep the API key empty. If the account has a key, the gateway uses it instead of the employee's ChatGPT credential and bills the wrong account. **2. Update the Codex table** ```toml theme={"dark"} [agents.codex] auth = "api-key" auth_mode = "chatgpt-subscription" model = "gpt-5.4" ``` Replace `model` with the Virtual Model or model ID from the previous step. This mode needs device login; it does not work with OIDC. **3. Tell employees about the two sign-ins** Employees complete the TrueFoundry sign-in from the MDM run, and sign in to their ChatGPT account the first time they open Codex. * A Virtual Model can have only **one** ChatGPT subscription target, because each employee's credential is valid for one ChatGPT account. Targets backed by an OpenAI API key can sit alongside it. * One employee reaching their ChatGPT limit does not affect anyone else's routing. * For a `401` or `403`: if the ChatGPT session expired, the employee runs `codex` and signs in again; if the TrueFoundry sign-in expired, trigger the MDM script again. ## Restrict MCP servers Gateway MCP servers from `[mcp]` are added alongside servers the employee configures. To allow only approved servers, Codex uses an MCP allowlist in `requirements.toml`, which the binary does not write: * **macOS and Linux:** deploy `/etc/codex/requirements.toml` with your MDM alongside the script. See OpenAI's [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration) for the format, and the [MCP example](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli.md#fleet-wide-enforcement). * **Windows:** the binary rewrites `requirements.toml` on every run to enforce the gateway, so a separately deployed allowlist in that file is replaced. ## Windows Subsystem for Linux Codex running inside WSL reads the distribution's own `/etc/codex`, not the Windows configuration. To also configure WSL, add `--wsl` to the binary's command in your script. It applies the Claude Code and Codex managed settings to each of the employee's WSL distributions. * It is off by default because reaching a stopped distribution starts it. * Running distributions are updated on every run; stopped ones at most once a day, so they can be up to 24 hours behind. * Container distributions, such as `docker-desktop`, `rancher-desktop`, and `podman-machine-*`, are skipped. * Inside WSL this routes traffic but does not enforce it: anyone who can run `wsl.exe` is root in the distribution. * WSL does not inherit Windows VPN or proxy routes, so check that the gateway is reachable from inside. Verify with `wsl.exe -d Ubuntu cat /etc/codex/managed_config.toml`. ## Data retention Retention of prompts and outputs on OpenAI's side is governed by your agreement with OpenAI, and differs between API usage and ChatGPT subscription plans. See OpenAI's [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration) documentation for the admin controls on your plan. On the TrueFoundry side, the gateway controls request logging and audit, independent of any setting on the device. ## Verify the deployment 1. **Check the files are locked.** See [Check that the settings are locked](https://www.truefoundry.com/docs/ai-gateway/mdm-setup.md#deploy-to-a-pilot-device). 2. **Check the sign-in block.** With device login, look for `Authorization = "Bearer ...` under `[model_providers.truefoundry.http_headers]`. With OIDC, look for `[model_providers.truefoundry.auth]` with `--_print-oidc-token` and no token. On Windows, the default model is under `[models.new_thread]`. 3. **Send a test request.** Run `codex`, send a prompt, and find it in **AI Gateway → Request Logs** under the employee. ```bash macOS and Linux theme={"dark"} cat /etc/codex/managed_config.toml ``` ```powershell Windows theme={"dark"} Get-Content C:\ProgramData\OpenAI\Codex\requirements.toml Get-Content C:\ProgramData\OpenAI\Codex\config.toml codex --version # 0.156.0 or later for enforcement ``` ## Troubleshooting | Symptom | Likely cause | Fix | | - | - | - | | Codex prints `Ignoring deprecated managed config file` on Windows | A `managed_config.toml` from an older setup is in `%USERPROFILE%\.codex` | Delete it. Windows Codex no longer reads that file | | An employee moved Codex off the gateway on Windows | Codex is older than 0.156.0, so only `config.toml` applies | Update Codex | | Model errors on every request | `model` is a provider-prefixed ID instead of a Virtual Model with a bare OpenAI slug | [Use a Virtual Model](#choose-a-model) | | `401` or `403` with a ChatGPT subscription | The ChatGPT session or the TrueFoundry sign-in expired | See [the subscription section](#use-a-chatgpt-business-or-enterprise-subscription) | | Codex prompts to trust a hook | You deployed `--block-agent` restrictions | The employee reviews the hook in `/hooks` | ## Related * [Codex integration](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli.md): manual configuration, Virtual Models, and web search * [Set up OIDC sign-in](https://www.truefoundry.com/docs/ai-gateway/mdm/oidc.md) * [Configuration reference](https://www.truefoundry.com/docs/ai-gateway/mdm/configuration-reference.md): every `mdm.toml` field This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.