alt text

Codex CLI Setup Guide

This guide will walk you through the setup of Codex CLI on your CNH machine. We currently support:

Windows 10+
Windows Subsystem for Linux (WSL/WSL2) w/ Ubuntu
macOS

Prerequisites

Node.js*
npm*
Python 3.12+*
Our Python authentication script <-- Download script and save to your computer
You must be part of an approved user group, such as EDP_Developer_AIMLCollaborators or a lab group that has an Azure AD entry

*May require admin approval

Installation

1. Set up Codex CLI executable

In a terminal window:

npm install -g @openai/codex

You can also install Codex from official distribution platforms such as brew in macOS and the official shell script for WSL.

2. Install the authentication dependency

WindowsWSLmacOS

py -m pip install --user msal msal-extensions

sudo apt install python3-msal python3-msal-extensions gir1.2-secret-1 wslu -y

python3 -m pip install --user msal msal-extensions

3. Create the MSAL Authentication Script

Download the Python script and save it to a known location.

Link to Script

We suggest the following paths to store the file:

WindowsWSLMacOS

C:\Tools\cnh-token.py

/home/<username>/Tools/cnh-token.py

/Users/<username>/Tools/cnh-token.py

4. Configure Codex

Create a folder for Codex in your home directory if it does not already exist.

Windows: C:\Users\<username>\.codex
WSL: ~/.codex
Mac: /Users/<username>/.codex

Here, you will need to create a file called config.toml that controls some of the underlying behavior of Codex. Use one of the following options. For all options, if you changed where the authentication script is stored, remember to change the path under the [model_providers.azure.auth] block.

WindowsWSLMacOS

In C:\Users\<username>\.codex\config.toml:

model = "gpt-6-luna"
model_provider = "azure"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://aiml-apim-dev.azure-api.net/ai/coding-assistants/codex"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

[model_providers.azure.auth]
command = "py"
args = [
    "C:\\Tools\\cnh-token.py"
]
timeout_ms = 120000

[profiles.fast]
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[windows]
sandbox = "elevated"

In ~/.codex/config.toml:

model = "gpt-6-sol"
model_provider = "azure"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://aiml-apim-dev.azure-api.net/ai/coding-assistants/codex"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

[model_providers.azure.auth]
command = "python3"
args = [
    "/home/<username>/Tools/cnh-token.py"
]
timeout_ms = 120000

[profiles.fast]
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

In /Users/<username>/.codex/config.toml:

model = "gpt-6-sol"
model_provider = "azure"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://aiml-apim-dev.azure-api.net/ai/coding-assistants/codex"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

[model_providers.azure.auth]
command = "python3"
args = [
    "/Users/<username>/Tools/cnh-token.py"
]
timeout_ms = 120000

[profiles.fast]
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

5. Start Codex

Open a new terminal window and start Codex CLI:

codex

Codex will open a window for you to sign in with your Microsoft credentials. Once you've signed in, the token should be good for a while.

Troubleshooting

Python Environments

If you use pyenv or the Python used by your CLI is not the included version from your operating system, you will need to install any dependent packages to that Python environment/version. For example, in WSL2 with Ubuntu 24.04:

pip install pycairo PyGObject

Codex Hang

If your Codex starts up, but does not make it to the point where you can start typing in the chat box, it is likely that it has failed the authentication step in some way. Usually, it will open a browser for you to authenticate with your Microsoft credentials, so check any open windows you have first to see if it popped up with a login screen.

WSL users will have the additional step of needing to install wslview (included from wslu) on their machine. Otherwise, WSL will not be able to use your Windows default browser to open the authentication page link. You may also need to add export BROWSER='/mnt/c/Program\ Files/Google/Chrome/Application/chrome.exe' or export BROWSER='/mnt/c/<path-to-browser>' to your .bashrc file. This is especially important for users of Ubuntu 26.04 through WSL.

Unable to Install WSLU

In the event 'wslu' is deprecated on your distribution of Linux, you may be unable to initialize because the libsecret tooling is missing. Install it and retry:

sudo apt update
sudo apt install libsecret-tools

WSL Authentication Timeout

If browser authentication opens but does not complete, set a fixed callback port in cnh-token.py:

interactive_parameters["port"] = 8400
token_result = application.acquire_token_interactive(**interactive_parameters)

Certificate and Credential Management

If you are asked to authenticate frequently (e.g. every time you boot up Codex), your machine may not be storing your authentication token properly. Ensure that you have dependencies related to certificate management installed on your machine.

Windows/MacOSWSL

Managed by the CNH enterprise. If this does not work by default, please contact us at AI_ML_Advanced_Analytics@childrensnational.org. We will likely ask you to wait for an Intune update to go out.

Perform a system update to ensure all package repositories are refreshed.

sudo apt update -y

Then make sure you have GNOME Keyring:

sudo apt install gnome-keyring -y

Agents and Skills

For details on AGENTS.md, custom agents, and skills, see Agents and Skills for Codex.

MCP Servers

For details on MCP servers and Codex configuration, see MCP Servers for Codex.

Happy coding!