Why Codex CLI 0.158 should be treated as a controlled upgrade
OpenAI’s stable Codex CLI 0.158.0 release, published on September 28, 2026, is not just a small terminal convenience update. The release touches authentication for Model Context Protocol servers, bearer-token protection for direct exec-server WebSocket connections, terminal approval behavior for elevated-permission commands, fullscreen terminal copy and paste behavior, image-generation options, transcript copying, completion-event reporting, and sandbox behavior across Windows, Linux, and macOS. For a solo developer on a local repository, that means the update deserves a quick Git checkpoint and a smoke test. For a company using Codex across managed workstations, IDEs, MCP connectors, or agent infrastructure, it should be handled as a normal change-management event with inventory, canaries, evidence capture, redaction, rollback, and accountable approval.
The core reason is scope. OpenAI’s release notes say 0.158 adds support for MCP servers whose OAuth clients use pre-registered secrets through codex mcp add --oauth-client-secret, and adds bearer-token protection for direct exec-server WebSocket connections. Those two items directly affect how Codex authenticates to surrounding systems. The same release enables terminal input approval by default for elevated-permission commands, which affects how a human reviews privileged operations. The release also fixes platform-specific sandbox failures on Windows, Linux, and macOS, which is operationally important because sandbox and permission behavior can differ by operating system, path layout, workspace trust status, and local policy.
The practical upgrade stance for this tutorial is conservative: install the stable release only on systems you own or are explicitly authorized to administer; verify behavior in a non-production canary before broader rollout; keep secrets out of prompts, shell history, screenshots, repositories, issue trackers, and generated reports; and require human approval for consequential operations. Codex can assist with planning, inspection, patch generation, and evidence organization, but the release notes are not a security certification, and the new approval behavior does not make unsafe commands safe. If an operation would require approval from a platform owner, repository maintainer, security reviewer, legal reviewer, finance owner, or customer-data steward outside Codex, it still requires that approval after the upgrade.
OpenAI’s Codex CLI documentation recommends Git checkpoints before and after tasks, and the CLI page documents common commands such as /status, /permissions, /model, and /review. Treat those as operational tools rather than decorative commands. Before changing a workstation, capture the current repository state, current Codex version, relevant configuration files, enabled MCP servers, local sandbox assumptions, and rollback method. After the upgrade, capture the same evidence again and compare the deltas. The point is not to create paperwork for its own sake; the point is to know whether an authentication, approval, or sandbox behavior changed in a way that matters to your team.
This article explains how to treat Codex stable and 0.154 alpha channels as separate release tracks, with guidance on canary repositories, permissions, checkpoints, and rollback planning. The Codex Stable vs 0.154 Alpha Playbook: Release Channels, Canary Repositories, Permissions, Checkpoints, and Rollback article is a focused companion for Codex Release Channel Rollout because it is the closest match for a marker about release-channel rollout discipline because it directly covers stable versus alpha Codex channels and controlled adoption practices.
What changed in Codex CLI 0.158, in operational terms
OpenAI’s 0.158.0 release notes describe several categories of change. The first category is terminal usability: configurable copy-on-select and right-click paste in the fullscreen TUI, plus preservation of Markdown when copying transcripts. This matters for developers who paste review transcripts into pull requests, incident notes, design reviews, or internal tickets. It also creates a new redaction requirement: copied transcripts may preserve structure better, but they may also preserve sensitive content more faithfully if secrets, internal hostnames, customer identifiers, or privileged logs were present in the session.
The second category is MCP authentication. OpenAI’s MCP documentation says the ChatGPT desktop app, Codex CLI, and IDE extension share MCP configuration for the same Codex host. The MCP documentation also describes supported Streamable HTTP authentication, including bearer tokens and OAuth, and documents a pre-registered OAuth client flow using codex mcp add with a client ID. The 0.158 release notes add support for the corresponding pre-registered OAuth client secret flag, --oauth-client-secret. That is useful for environments where an OAuth provider requires a pre-registered confidential client, but it also increases the need for secret-handling discipline. The command must never be demonstrated with a real secret, stored in a repository, pasted into a model prompt, or included in final evidence without redaction.
The third category is direct exec-server WebSocket protection. OpenAI says the 0.158 release supports bearer-token protection for direct exec-server WebSocket connections. The precise security value depends on correct configuration, secure token issuance, secure storage, transport protections, network exposure, monitoring, and revocation procedures. This tutorial therefore treats bearer-token support as a capability to validate, not a blanket guarantee. If an exec-server endpoint is reachable by systems that should not reach it, a bearer token may reduce unauthorized access only if it is actually required, sufficiently protected, rotated when necessary, and not leaked through logs or command history.
The fourth category is approval and permission behavior. OpenAI’s release notes say terminal input approval is enabled by default for elevated-permission commands, and that runtime-only grants should no longer trigger unnecessary repeat reviews. The operational interpretation is narrow: teams should verify that elevated commands still require human review in their workflows and that unnecessary repeat prompts are reduced where the release notes say they should be. Do not treat fewer repeated reviews as permission broadening, and do not disable approvals to speed up rollout. Approval review remains the line between suggested automation and accountable action.
The fifth category is cross-platform reliability. OpenAI says 0.158 fixes Windows sandbox failures involving Windows 10 paths, stored credentials, and large permission policies; Linux startup with nested writable roots; macOS system path aliases; approval reviews interrupted by new user input; Mermaid quoted labels and ampersands; and command completion events that lacked early output or launch-failure detail. Those fixes are excellent candidates for explicit regression tests because they map to concrete failure modes. A team that supports Windows, Linux, and macOS should not validate the release on only one operating system and assume the others are covered.
Prerequisites before you install or update
Begin with authorization. You should perform this upgrade only on a workstation, repository, project, MCP server, or agent host that you own or are explicitly authorized to administer. If a system belongs to an employer, client, school, or regulated environment, use the organization’s approved change process. If you are not permitted to view a configuration file, modify an MCP connector, inspect a credential store, or change sandbox permissions, Codex should not be used to bypass that restriction. The upgrade can be technically simple and still be administratively unauthorized.
Confirm that your team has access to the official OpenAI documentation needed for this release: the 0.158.0 release notes, the Codex CLI guide, the Codex MCP guide, the Codex configuration reference, and OpenAI’s Codex approvals and security learning material. These sources define the factual boundary for this tutorial. Product behavior can vary by plan, account, app, region, rollout, workspace policy, local operating system, and host configuration, so do not assume another team’s screenshots or commands represent your environment.
Inventory the current Codex footprint before making changes. At minimum, record the current CLI version, install method, operating system version, shell, terminal application, repositories where Codex is used, trusted project status where applicable, MCP servers configured for the same Codex host, approval policy, sandbox and permission profile, known writable roots, network assumptions, and any direct exec-server WebSocket usage. OpenAI’s configuration reference states that user configuration lives at ~/.codex/config.toml, and that project-scoped configuration is loaded only for trusted projects. It also states that project configuration cannot override machine-local provider, authentication, or telemetry keys. That distinction matters when troubleshooting why a policy did or did not change after the upgrade.
Create a Git checkpoint for every repository that will be used during validation. OpenAI’s CLI guide recommends Git checkpoints before and after tasks, and this tutorial treats that as mandatory for upgrade testing. A practical checkpoint includes a clean working tree or a clearly documented dirty tree, the current branch, latest commit hash, untracked files that matter, and any local configuration files that are intentionally excluded from version control. Do not add secrets or private machine-local configuration to Git just to make the checkpoint easier.
Back up configuration without copying secrets into unsafe locations. For Codex configuration, record file paths, non-sensitive setting names, MCP server names, tool allowlists, approval modes, sandbox profiles, and trusted-project assumptions. If a value is a secret, token, password, client secret, private hostname, customer identifier, or privileged endpoint, replace it with a placeholder such as <REDACTED_MCP_CLIENT_SECRET> in notes and evidence. A useful backup is one that allows a qualified administrator to reconstruct the intended configuration from approved secret storage, not one that exposes the secret itself.
Choose a canary group before wider rollout. A safe canary includes one or more representative but non-production repositories, at least one developer workstation from each supported operating system, representative MCP connectors without production blast radius, a direct exec-server WebSocket test only if your organization already uses that architecture, and a rollback owner who can revert the upgrade. Avoid using live customer data, production credentials, privileged production hosts, or repositories with pending release-critical changes as the first test bed.
Define evidence and redaction rules in advance. Evidence should include version output, sanitized configuration diffs, approval screenshots or text logs with secrets removed, MCP connection results, sandbox test results, copied-transcript formatting checks, and completion-event behavior for selected commands. Evidence should not include API keys, OAuth client secrets, bearer tokens, full credential-store output, personal data, customer data, private legal or health information, unpublished financial information, or privileged communications. If evidence is destined for a ticket or pull request, assume it will be read by people who do not need secrets.
Release-change matrix for Codex CLI 0.158
The following matrix converts OpenAI’s documented 0.158 release notes into an upgrade plan. The “validation evidence” column is intentionally concrete because a release claim is not the same thing as proof that your local environment is configured safely. Use the matrix as a starting point for a canary checklist, then narrow it to your operating systems, MCP servers, repositories, and workspace policies.
Documented change in 0.158
Configuration impact
Security implication
Validation evidence to collect
Configurable copy-on-select in the fullscreen TUI.
Review terminal and TUI preferences for users who copy from Codex sessions into tickets, reviews, or documentation.
More convenient copying can increase accidental disclosure if transcripts contain secrets, privileged logs, or personal data.
Sanitized screenshot or note showing expected copy behavior, plus a redaction check before any copied transcript is shared.
Right-click paste in the fullscreen TUI.
Validate terminal behavior on each supported OS and terminal application because paste handling can vary locally.
Pasting unreviewed commands can trigger unsafe actions if a human approves without reading; approval policies still matter.
Recorded canary test using harmless text, not credentials or destructive commands, confirming paste behavior and review expectations.
Markdown is preserved when copying transcripts.
Update documentation workflows if transcripts are used in pull requests, internal runbooks, or incident notes.
Better formatting can make evidence easier to review, but it can also preserve sensitive snippets in a more reusable form.
Sanitized copied transcript showing headings, code formatting, or lists preserved without exposing confidential content.
MCP support for pre-registered OAuth clients using codex mcp add --oauth-client-secret.
OAuth client registration, callback URL, scopes, client ID, and client-secret handling may need review.
Client secrets must be stored and transmitted securely; incorrect callback or scope configuration can weaken access control or break login.
Redacted MCP configuration summary, exact callback verification, non-production authentication test, and confirmation that no real secret appears in shell history, Git, or evidence.
Bearer-token protection for direct exec-server WebSocket connections.
Direct WebSocket clients and server configuration may need token requirement, token storage, and connection-test updates.
Bearer tokens protect only when required, kept confidential, scoped appropriately, monitored, and rotated when needed.
Non-production positive and negative connection tests, sanitized server configuration evidence, and confirmation that tokens are not logged or pasted into prompts.
Image generation and editing can explicitly request transparent backgrounds.
Workflows that generate or edit images may add an explicit transparent-background request where appropriate.
Transparency is a requested output property, not a guarantee of suitability for brand, legal, accessibility, or publication use.
Representative image test with human visual review and documented acceptance criteria for background handling.
Image edits can use file-backed conversation images.
Teams using image-edit workflows should validate file access, file selection, and data-handling rules.
Local files may contain sensitive visual data; do not use private, regulated, or customer images unless policy allows it.
Test using approved non-sensitive image fixtures and a note confirming no private images were used in canary validation.
Terminal input approval is enabled by default for elevated-permission commands.
Approval workflow may appear more prominently during privileged terminal actions.
Approval prompts are a safety control; teams should not disable them to speed up rollout.
Harmless elevated-permission test plan appropriate to the environment, reviewer confirmation, and evidence that consequential commands still require human approval.
Runtime-only grants should no longer trigger unnecessary repeat reviews.
Users may see fewer repeated prompts for grants that are meant to last only for the runtime context.
Reduced review fatigue is useful only if grant scope remains narrow and understandable.
Before-and-after canary notes showing expected prompt reduction without expanded persistent permission.
Fixes for Windows sandbox failures involving Windows 10 paths, stored credentials, and large permission policies.
Windows canary hosts should include representative path layouts and policy sizes.
Sandbox fixes reduce specific failures but do not remove the need for least privilege, endpoint controls, and credential hygiene.
Windows sandbox smoke-test output using non-sensitive paths and proof that credential material is not exposed in logs.
Fix for Linux startup with nested writable roots.
Linux hosts with nested repository or workspace layouts should validate startup and writable-root behavior.
Writable roots define where actions can affect files; nested layouts must be reviewed to avoid broader-than-intended write access.
Linux canary result showing startup success and a sanitized map of intended writable roots.
Fix for macOS system path aliases.
macOS validation should include common system path aliases and local development paths.
Alias resolution can affect what path Codex appears to access; reviewers should confirm the real target path.
macOS canary note showing alias behavior with non-sensitive paths and confirmation of expected sandbox boundaries.
Fix for approval reviews interrupted by new user input.
Reviewers should test that entering new input during review does not corrupt the approval flow.
Approval integrity matters because interrupted reviews can create confusion about what was approved.
Controlled canary transcript showing interrupted-review handling with harmless commands and clear final approval state.
Fixes for Mermaid quoted labels and ampersands.
Documentation or diagram workflows that use Mermaid should rerun representative diagrams.
Rendering fixes improve documentation reliability but do not validate the technical accuracy of a diagram.
Before-and-after rendering check using approved Mermaid fixtures with quoted labels and ampersands.
Fixes for command completion events that lacked early output or launch-failure detail.
Automation or logs that consume completion events may receive more useful failure context.
More detailed output can improve troubleshooting but may include sensitive command details if logs are not redacted.
Sanitized completion-event samples for a successful command, an early-output command, and a launch failure.
Upgrade rules for authorized systems only
Rule one is ownership or explicit authorization. You may upgrade your own local development machine, a workstation assigned to you under your employer’s policy, or a managed host where you have been delegated administration rights. You should not use Codex to inspect or change another person’s workstation, a client system, a shared production host, a school device, or a third-party service unless the responsible owner has granted permission and the work fits the applicable policy and law. Technical access is not the same as authority.
Rule two is least privilege. The canary should use the smallest set of repositories, MCP tools, scopes, sandbox roots, network destinations, and file fixtures needed to validate the release. OpenAI’s MCP guide documents server and per-tool approval modes, enabled and disabled tool lists, and authentication options; those controls are where you narrow what Codex can do through connected tools. Do not broaden allowlists, grant network access, or relax sandbox settings merely to make a validation pass. A failed canary is useful evidence.
Rule three is human approval for consequential actions. OpenAI’s release notes say elevated terminal input approval is enabled by default, and OpenAI’s learning material on agent approvals and security reinforces the need to understand approval boundaries. In this tutorial, human approval is mandatory before external messages, submissions, payments, purchases, bookings, destructive file operations, permission changes, publication, production changes, legal commitments, or security-sensitive configuration changes. Codex can draft the change request, but an accountable human owner must approve the action.
Rule four is secret minimization. For MCP OAuth client secrets and WebSocket bearer tokens, never paste a real secret into Codex prompts, generated documentation, issue comments, commit messages, terminal examples, shared screenshots, or this tutorial’s evidence templates. Use placeholders such as <MCP_CLIENT_SECRET_FROM_APPROVED_SECRET_STORE> or environment-variable names such as $CODEX_MCP_CLIENT_SECRET when documenting intent. If a real secret is accidentally exposed, stop the rollout, follow your incident procedure, rotate the secret through the approved authority, and treat all derived logs or transcripts as sensitive until reviewed.
Rule five is rollback readiness. A rollback plan must exist before installation, not after the first failed workstation. At minimum, identify how to reinstall the previous approved Codex version or return to the previous deployment channel if your organization maintains one, how to restore non-secret configuration, how to disable a new MCP connector or direct WebSocket path, and how to notify affected users. If your organization cannot restore the prior state, limit the canary further until rollback is clear.
Baseline checklist before touching the installation
Use the following baseline checklist as a preflight. It is deliberately more detailed than a personal upgrade note because Codex 0.158 includes changes that can affect authentication, approval, and sandbox behavior. If a checklist item is irrelevant to your environment, mark it as not applicable and explain why. Do not delete it silently; omitted controls are hard to distinguish from controls that were never considered.
Confirm the upgrade owner, rollback owner, security reviewer, and affected user group.
Confirm that every test system is owned by you or explicitly approved for administration.
Record current Codex CLI version and installation method.
Record operating system version, terminal application, shell, and any endpoint-management constraints.
Capture a Git checkpoint for each repository used in testing, including branch and commit hash.
Record whether each repository is trusted for project-scoped Codex configuration.
Review ~/.codex/config.toml and project-scoped configuration for non-sensitive settings, approval policies, sandbox profiles, and MCP references.
List MCP servers configured for the same Codex host, including authentication type and tool allowlist, without recording secrets.
List any direct exec-server WebSocket usage and whether bearer-token protection is expected after the upgrade.
Identify non-production fixtures for Windows path tests, Linux nested writable-root tests, macOS alias tests, Mermaid rendering tests, and completion-event tests.
Define redaction rules for transcripts, screenshots, logs, configuration summaries, and final rollout reports.
Define rollback steps and the decision threshold that triggers rollback.
A good baseline should be reproducible by another authorized administrator. For example, “Codex is installed somehow on developer laptops” is not enough. “Canary group A includes two Windows 10 workstations, one current macOS workstation, and one Linux workstation with nested repository roots; each has a clean Git checkpoint; MCP connector X is enabled in staging only; no production credentials are used” is operationally useful. The second version lets a reviewer understand blast radius, evidence quality, and rollback feasibility.
Secret-safe command examples for MCP OAuth client-secret planning
OpenAI’s release notes document support for codex mcp add --oauth-client-secret for MCP servers whose OAuth clients use pre-registered secrets. The example below is intentionally incomplete and uses placeholders. It is not a recommendation to run the command as written, and it must be adapted only by an authorized administrator using values from approved configuration and secret-management systems. Never substitute a real secret into documentation, a shared prompt, a pull request, or an article draft.
# Example only: use placeholders in documentation and prompts.
# Retrieve real values only through your approved secret-management process.
codex mcp add <MCP_SERVER_NAME> \
--oauth-client-id <OAUTH_CLIENT_ID> \
--oauth-client-secret <MCP_CLIENT_SECRET_FROM_APPROVED_SECRET_STORE>
Before using any OAuth client secret with Codex, verify the OAuth provider’s exact callback registration requirements from OpenAI’s MCP documentation and your identity-provider configuration. A near-miss callback URL can produce confusing authentication failures, and an overbroad client or scope can grant more access than a coding assistant needs. Record the client ID, allowed callback URL, requested scopes, server name, and enabled tool list in sanitized evidence. Do not record the client secret.
If your organization uses shell history, terminal session recording, endpoint detection, or centralized logging, confirm how sensitive command arguments are handled before entering any command that includes a secret. A safer operational pattern is to use an approved secret store or environment-variable workflow where supported by your organization’s tooling, then keep the final rollout report limited to placeholders and verification results. This article does not prescribe a universal secret-storage mechanism because local enterprise controls vary, but it does require that real secrets stay out of prompts, transcripts, repositories, and shared reports.
Canary design: prove the release in the smallest useful environment
The canary should answer four questions. First, can authorized users install or update to the intended stable Codex release and confirm the version? Second, do authentication paths still work for the MCP servers and direct WebSocket use cases the team actually supports? Third, do approval and sandbox behaviors match policy on Windows, Linux, and macOS? Fourth, can the team roll back without losing work, leaking secrets, or leaving half-configured connectors behind? If the canary cannot answer those questions, it is too shallow for a managed rollout.
Choose fixtures that represent real workflows without exposing production data. For a Windows sandbox test, use harmless directories that exercise Windows 10 path behavior without touching credential material. For a Linux nested writable-root test, use a disposable repository inside a nested workspace and verify that writes occur only where expected. For macOS aliases, use non-sensitive path aliases and confirm the actual target path. For Mermaid, use a diagram that includes quoted labels and ampersands. For completion events, use harmless commands that produce early output and a controlled launch failure so the event details can be inspected without risk.
For MCP validation, separate authentication success from authorization correctness. A connector can authenticate successfully while exposing too many tools, broad scopes, or unnecessary domains. OpenAI’s MCP guide documents server and per-tool approval modes and enabled or disabled tool lists, so canary evidence should include both “login works” and “only intended tools are available.” If a tool can send external messages, modify records, change permissions, or access sensitive systems, require a separate owner review before it is available beyond the canary.
For direct exec-server WebSocket validation, perform both positive and negative tests in non-production. A positive test confirms that an authorized client can connect using the intended bearer-token configuration. A negative test confirms that a client without the required bearer token cannot connect. Record only sanitized outcomes, not the token. If the negative test succeeds when it should fail, stop the rollout and review exposure, network path, server configuration, and logging before continuing.
Opening rollback criteria
Rollback criteria should be defined before the upgrade because incidents create pressure to rationalize unexpected behavior. Roll back or pause the rollout if elevated commands bypass expected approval, if MCP authentication requires exposing a client secret outside approved handling, if a direct WebSocket accepts unauthenticated connections when bearer-token protection is expected, if sandbox roots permit writes outside the intended boundary, if Windows, Linux, or macOS canary hosts show platform-specific failures that affect supported workflows, or if evidence capture reveals secrets in logs or transcripts.
Rollback does not have to mean abandoning 0.158 permanently. It can mean freezing the rollout, reverting affected canary hosts, disabling a new connector, restoring a previous configuration, rotating an exposed secret, or waiting for a policy owner to approve a corrected setup. The important point is that rollback is a controlled state, not a panic state. Users should know whether they may continue using Codex, which repositories or connectors are affected, and what evidence they should preserve for troubleshooting.
The rest of this tutorial will move from preparation into execution: install or update using OpenAI-documented CLI guidance, confirm the version, validate fullscreen TUI copy and paste behavior, add or review MCP OAuth configuration without exposing secrets, test protected direct WebSocket behavior, verify elevated approval flows, run cross-platform sandbox checks, inspect Mermaid and completion-event fixes, and package a release report suitable for a cautious wider rollout.
Install or update Codex CLI 0.158, then prove what is actually running
OpenAI’s Codex CLI documentation presents a standalone install and update command for the CLI; use that official path rather than inventing package-manager substitutions, wrapper scripts, or organization-specific bootstrap commands in a release runbook. Run the install or update only on a canary workstation or controlled test host first, and record the operator, host name class, operating system version, shell, Codex CLI version before the change, and rollback owner before executing it.
curl -fsSL https://codex.openai.com/install.sh | sh
This command is intentionally shown exactly as a standalone install/update action. If your organization blocks direct shell-pipe installation, treat that as a policy exception to resolve through your internal software-distribution process rather than bypassing endpoint controls. A safer enterprise workflow is to have a platform owner retrieve, inspect, approve, and distribute the installer through the organization’s normal device-management channel; the public tutorial command remains the OpenAI-documented user-facing install/update command, not a mandate to ignore corporate controls.
After installation or update, verify the installed CLI version before testing any behavior. The OpenAI CLI documentation describes interactive commands such as /status, /permissions, /model, and /review inside Codex. Use those built-in status surfaces for evidence because a shell path can point to an older binary, a shim, or a different user installation than the one launched by the fullscreen TUI.
# Start Codex in the canary project after the installer completes.
codex
# Inside the Codex TUI, run:
/status
/permissions
/model
Capture the /status output in a redacted release note that includes the CLI version, active model selection, active workspace or project context, and any visible permission or sandbox profile information. Do not paste tokens, OAuth secrets, local credential material, confidential paths, customer names, private repository URLs, or proprietary prompts into the release note. If /status does not show enough detail for your internal evidence standard, supplement it with screenshots or terminal transcripts that redact sensitive data rather than guessing which configuration was active.
The Codex configuration reference states that user configuration lives at ~/.codex/config.toml, while project-scoped configuration is loaded only for trusted projects. It also states that project configuration cannot override machine-local provider, authentication, or telemetry keys. That distinction matters during an upgrade because a test that passes under one trusted repository can fail in another project where project-scoped configuration is ignored, absent, or deliberately limited.
# Evidence-gathering pattern: list file presence without printing secrets.
# Review contents manually and redact before sharing.
ls -la ~/.codex
test -f ~/.codex/config.toml && echo "User Codex config exists"
# In the canary repository, inspect trusted project configuration only if your policy permits.
# Do not publish secret values, access tokens, or private endpoints in release evidence.
Before continuing, create the Git checkpoint recommended by OpenAI’s CLI documentation for task safety. A checkpoint does not make unsafe commands safe and does not replace backups, but it gives reviewers a concrete diff boundary for files that Codex or the operator changes while validating 0.158 behavior.
git status --short
git branch --show-current
git diff --stat
If the canary repository is dirty before the upgrade test, stop and decide whether those changes are part of the test fixture. Mixing unrelated application work with a CLI upgrade makes it difficult to attribute file changes, approval prompts, sandbox failures, or command-completion anomalies to the correct cause. A clean repository, a named branch, and a short test plan are the minimum evidence standard for a controlled validation.
Confirm the active configuration before testing release-specific behavior
Codex 0.158 includes changes across the fullscreen TUI, MCP authentication, exec-server WebSocket protection, approval behavior, and operating-system sandbox fixes. Those areas are controlled by a combination of CLI version, user configuration, project configuration, workspace trust, server definitions, sandbox settings, and runtime approvals. A test is only meaningful if it states which configuration was active when the observation was made.
Evidence item
How to collect it conservatively
Why it matters for 0.158 validation
Installed Codex CLI version
Use /status in the running Codex TUI and record the displayed version if available.
Prevents attributing older-binary behavior to the 0.158 release.
Active permission profile
Use /permissions and redact anything sensitive before sharing.
Elevated terminal input approval and sandbox outcomes depend on the actual approval and permission settings.
Active model choice
Use /model and record the visible selection without assuming plan availability.
Model behavior can affect tool planning, but it should not be confused with CLI installation behavior.
User configuration presence
Confirm whether ~/.codex/config.toml exists; review contents locally with redaction.
The configuration reference identifies this as the user configuration location.
Project trust and project configuration
Record whether the canary project is trusted and whether project-scoped configuration is expected to load.
OpenAI documents that project-scoped configuration is loaded only for trusted projects.
Git baseline
Record branch, status, and diff summary before testing.
Provides a boundary for file changes introduced during the validation session.
Do not treat a successful launch as proof that all release features are active. The 0.158 release notes describe support for new and fixed behaviors, but features such as MCP OAuth client-secret usage, direct exec-server WebSocket bearer authentication, and sandbox policy handling still depend on local configuration, server configuration, and the exact workflow under test.
This guide explains how to set up an OpenAI Codex Windows Sandbox for secure AI-assisted development using an elevated Windows sandbox environment. The How to Set Up OpenAI Codex Windows Sandbox for Secure AI-Assisted Development article is a focused companion for Sandbox Permission Testing because it directly matches sandbox permission testing in the current article, especially the Windows and elevated-sandbox aspects of cross-platform validation.
Validate fullscreen TUI copy and paste behavior without leaking secrets
OpenAI’s 0.158 release notes state that the fullscreen TUI adds configurable copy-on-select and right-click paste, and that copied transcripts preserve Markdown. These are usability changes, but they have security consequences because terminal selections often include paths, command output, issue text, or environment context. Test the behavior with deliberately non-sensitive fixture text before using it in real repositories.
Copy-on-select test fixture
Use a short prompt that produces harmless, distinctive Markdown. The goal is not to evaluate model quality; the goal is to determine what gets placed on the clipboard when an operator selects text in the TUI. Use a terminal environment where clipboard synchronization is allowed by policy, and avoid remote sessions that copy content to untrusted local devices.
In this canary session, produce exactly this harmless Markdown fixture and do not include secrets:
- alpha item
- beta item with `inline_code`
- gamma item with **bold text**
Then stop.
Select only the rendered response text in the fullscreen TUI. Paste the clipboard into a local scratch buffer that is not committed to the repository and does not synchronize to a public note system. Record whether selection copied text automatically, whether code spans and list markers survived, and whether any unintended prompt, status line, or hidden terminal content came along with the selection.
Observed result
Interpretation
Action before rollout
Selection automatically appears on clipboard.
Copy-on-select is active in this environment.
Train users not to select secret-bearing output casually; decide whether this setting matches policy.
Selection does not alter clipboard.
Copy-on-select may be disabled, unsupported in the terminal, or blocked by platform policy.
Record terminal, OS, and configuration; do not claim the feature failed without isolating the environment.
Clipboard includes more than the selected response.
The terminal selection mode or TUI region may include extra content.
Escalate as a usability or data-handling risk before broad deployment.
Right-click paste test fixture
Right-click paste is valuable when moving structured prompts into the fullscreen TUI, but accidental paste can also submit commands, private text, or multi-line instructions. Test with an inert phrase and make sure the operator understands whether the paste inserts text, submits text, or triggers an additional confirmation in the terminal environment.
CANARY_PASTE_TEST_DO_NOT_EXECUTE
Copy the inert phrase from a local scratch file, right-click inside the Codex TUI, and observe whether the text appears in the input area without being submitted. If the terminal submits immediately, captures additional clipboard contents, or behaves differently across Windows Terminal, macOS Terminal, iTerm2, GNOME Terminal, or another approved terminal, record that variance in the rollout note. Do not test paste behavior with shell commands, credentials, OAuth callback URLs containing sensitive tenant information, or internal incident text.
Markdown-preserving transcript copy test
The 0.158 release notes say copied transcripts preserve Markdown. Validate that claim locally using a transcript fixture with headings, lists, inline code, fenced code, and a blockquote. The test should compare pasted content against the original rendered content and note whether Markdown syntax is preserved in the destination application your team actually uses for code review or release evidence.
Prepare a harmless Markdown transcript fixture with:
1. One level-three heading named "Canary heading"
2. Two bullet points
3. One inline code span containing SAFE_INLINE
4. One fenced code block containing echo SAFE
5. One blockquote containing "canary quote"
Do not include secrets or private repository data.
Copy the transcript using the normal TUI workflow available in your environment, paste it into a local editor, and inspect the Markdown structure. If the destination application reformats Markdown, distinguish destination behavior from Codex copy behavior. A release note should say “Markdown was preserved when pasted into our approved local editor” or “Markdown was not preserved in our tested terminal/editor combination,” not “0.158 always preserves Markdown everywhere.”
Cross-platform sandbox and path regression tests
OpenAI’s 0.158 release notes list several platform fixes: Windows sandbox failures involving Windows 10 paths, stored credentials, and large permission policies; Linux startup with nested writable roots; and macOS system path aliases. Treat those notes as a map for targeted regression tests, not as proof that your endpoint fleet is covered. Your operating-system version, terminal, filesystem layout, enterprise controls, and Codex configuration can still produce different outcomes.
Windows 10 path handling test
For Windows 10 canaries, test a repository path that reflects your real developer fleet but does not contain private customer names or credentials. The release note specifically mentions Windows 10 paths, so include ordinary path shapes that have historically caused quoting or normalization errors, such as spaces in directory names or long but policy-compliant workspace names. Do not create deliberately malicious paths or attempt to bypass sandbox restrictions.
Canary objective:
- Confirm Codex can start in a Windows 10 repository path used by our developers.
- Confirm /status and /permissions open successfully.
- Ask Codex to inspect a harmless local README fixture.
- Do not grant broad filesystem access.
- Do not expose stored credentials, tokens, or private files.
A successful Windows path test requires evidence that Codex launched in the intended repository, the active permissions were visible, the harmless fixture could be read if allowed, and no unexpected permission expansion occurred. If the test fails, preserve the exact non-sensitive path shape, Windows version, terminal, and visible error. Do not paste credential-manager contents, environment variables, access tokens, or corporate usernames into the failure report.
Windows stored credentials safety test
The 0.158 release notes also mention Windows sandbox failures involving stored credentials. The correct validation is not to display or extract stored credentials. Instead, test that ordinary Codex startup and a harmless repository task do not fail merely because the workstation has normal enterprise credential storage configured. If your organization uses Windows Credential Manager, single sign-on, or endpoint-managed secrets, have an authorized endpoint administrator define the safe observation criteria.
Unsafe test
Safe substitute
Evidence to record
Listing stored credentials in the terminal.
Confirm Codex starts and completes a non-secret local fixture task on a machine with standard credential storage enabled.
Codex version, OS version, terminal, task summary, and absence or presence of a sandbox error.
Pasting credential-manager output into Codex.
Ask an endpoint owner to review local logs privately and provide a redacted pass/fail note.
Redacted administrator attestation, not secret material.
Changing credential permissions to “make the test pass.”
Keep production-like endpoint policy unchanged during the canary.
Whether 0.158 works under real managed-device controls.
Windows large permission policy test
Because 0.158 notes a fix for Windows sandbox failures involving large permission policies, include a canary account that resembles a real managed developer machine with normal enterprise policy load. Do not artificially grant wide permissions just to create a large policy. The meaningful test is whether Codex can start, display permissions, and perform a harmless allowed task under the policy size your fleet already uses.
Canary prompt for a managed Windows test host:
You are operating in a canary repository that contains only harmless fixtures.
First, summarize the visible project files.
Second, tell me whether you need approval before any command that writes files.
Do not access credential stores, browser profiles, SSH keys, cloud config, or files outside the canary repository.
If Codex requests approval for an action that should be reviewable, record the prompt and decision without treating the approval prompt as a failure. If Codex fails before showing permissions, record the non-sensitive error details and stop. A workaround that disables endpoint policy, relaxes sandboxing, or broadens filesystem access would invalidate the canary because it no longer represents the target fleet.
Linux nested writable roots test
OpenAI’s release notes say 0.158 fixes Linux startup with nested writable roots. Validate this with a deliberately simple nested directory fixture that mirrors your repository layout, such as a monorepo folder with a nested package directory. Do not mount sensitive home directories or production paths as writable roots for a test.
# Example fixture shape; adapt names to your internal canary repository.
canary-repo/
README.md
packages/
service-a/
README.md
src/
harmless.txt
Start Codex from the top-level canary repository and from the nested package directory in separate sessions. Use /status and /permissions in each session to confirm what Codex believes the project and permission context are. Then ask Codex to read and summarize harmless.txt, and, only if your canary plan permits writes, ask it to propose a change rather than immediately writing one.
In this Linux nested-root canary, inspect only the harmless fixture files under the current repository.
Report:
- the current working directory you infer,
- whether the nested package README is visible,
- whether you need approval before writing a file.
Do not access parent directories outside the canary repository.
Passing evidence should show that startup succeeds in both root and nested contexts, the visible file set matches the intended sandbox, and Codex does not claim or use broader access than the policy allows. If startup fails only in the nested directory, keep the directory tree, mount type if non-sensitive, Linux distribution, terminal, and permission profile in the bug evidence. Do not loosen writable roots as a silent workaround; that can hide exactly the class of sandbox problem the canary is meant to detect.
Git metadata protection test on Linux and other platforms
The release notes mention Linux nested writable roots, while OpenAI’s CLI documentation recommends Git checkpoints. Combine those concerns by verifying that Codex can inspect ordinary project files without corrupting Git metadata. This is a recommended operational test, not a first-party claim that 0.158 adds a specific Git metadata protection feature.
git status --short
git rev-parse --show-toplevel
git rev-parse --git-dir
Run a harmless Codex task that reads a fixture and proposes a patch. Before accepting any write, check whether the proposed change touches .git, lock files unrelated to the test, generated caches, credential files, or workspace settings. Human approval is mandatory before accepting changes that write files, alter permissions, modify hooks, update dependencies, change CI configuration, or affect repository metadata.
Review the canary README and propose a one-sentence wording improvement.
Do not edit files yet.
Do not access or modify .git, hooks, credentials, dependency lockfiles, CI configuration, or files outside this repository.
After the proposal, use git status --short and git diff --stat. If no write was approved, those commands should remain unchanged. If a write was approved, the diff should match the approved file and scope. Any unapproved change to Git metadata, hooks, repository configuration, or external files should stop the rollout until a platform owner reviews the transcript and local logs.
macOS system path alias test
OpenAI’s 0.158 release notes say the release fixes macOS system path aliases. macOS systems can expose familiar directories through aliases or localized paths, and enterprise devices may add management layers. Validate only the paths your developers actually use, and do not use the test to probe protected system locations or bypass operating-system privacy prompts.
macOS canary objective:
- Start Codex from an approved canary repository reached through the normal developer path.
- Start Codex from the same repository if reached through an approved alias or standard path variation used by the team.
- Compare /status and /permissions.
- Confirm Codex sees only the intended project files.
- Do not request access to protected personal folders, keychains, mail, messages, photos, or browser profiles.
Record the path form in a privacy-preserving way, such as “standard workspace path” and “approved alias path,” unless the exact path is necessary for debugging and does not expose a person’s name, client, project code name, or internal network structure. If behavior differs by path form, preserve both launch contexts and avoid merging the canary into wider rollout until the discrepancy is explained.
Validate Mermaid labels and command completion events
The 0.158 release notes identify fixes for Mermaid quoted labels and ampersands, and command completion events that lacked early output or launch-failure detail. These may seem secondary compared with authentication and sandboxing, but they affect developer trust in transcripts, diagrams, automation logs, and review evidence. A diagram that silently renders incorrectly or a command event that hides launch failure detail can mislead a human reviewer.
Mermaid quoted labels and ampersands test
Use a harmless Mermaid fixture containing quoted labels and ampersands. The goal is to determine whether the Codex path you use for generating, displaying, or copying Mermaid content preserves the intended text. Do not put proprietary architecture names, customer systems, or security topology into this test diagram.
Produce a Mermaid flowchart using only this harmless content:
flowchart TD
A["Build & Test"] --> B["Review & Approve"]
B --> C["Deploy & Observe"]
Then explain whether the labels include quoted text and ampersands.
Do not include private system names.
Copy the resulting diagram text using the transcript-copy workflow tested earlier and paste it into the approved local renderer or documentation tool used by your team. Record whether the labels remain quoted where needed, whether ampersands render as intended, and whether the copied Markdown changes the Mermaid block. If your renderer has its own Mermaid limitations, distinguish those from Codex transcript behavior.
Command completion event test with early output
Command completion events are part of the evidence trail reviewers use to understand what ran, what output appeared early, and why a launch failed. OpenAI’s release notes say 0.158 fixes completion events that lacked early output or launch-failure detail. Validate this only with harmless commands that are authorized in your sandbox and do not reveal secrets.
Ask before running any command. If approved, run a harmless command that prints an early line, waits briefly if the environment supports it, and prints a final line. Use only standard shell behavior available in this canary environment. Do not inspect environment variables, credentials, network configuration, or files outside the repository.
Because shell syntax varies across operating systems, do not hard-code a cross-platform command in the release plan unless your team has approved one for each platform. On Unix-like canaries, a platform owner might approve a simple command that prints two non-sensitive lines. On Windows canaries, use the approved shell and syntax for that environment. The key observation is whether the transcript or event log shows early output and final completion clearly enough for review.
Test condition
Expected evidence to look for
Do not claim
Approved harmless command produces early output.
Transcript or event view shows the early line before final completion, if the interface exposes that detail.
Do not claim all long-running commands are now observable in every terminal or integration.
Approved harmless command completes successfully.
Completion status is visible and tied to the command that ran.
Do not claim command success proves sandbox safety for unrelated commands.
Intentionally invalid harmless command fails to launch.
Failure detail is visible without exposing sensitive environment data.
Do not run destructive or privileged failures merely to test logging.
Command launch-failure detail test
To test launch-failure detail safely, request approval for a command name that should not exist and contains no sensitive arguments. The objective is to confirm that the failure is understandable to a human reviewer. Do not use missing internal tools, private hostnames, cloud account names, or secret-bearing command lines as failure fixtures.
Ask before running any command. If approved, attempt to run a harmless nonexistent command named codex_canary_command_that_should_not_exist_0158. Report only the launch-failure detail shown by the environment. Do not inspect PATH, environment variables, shell profiles, credentials, or system configuration.
If the failure detail appears, record whether it identifies launch failure separately from command runtime failure. If it does not appear, record the terminal, operating system, Codex version, active permissions, and whether the command was actually submitted. Avoid over-interpreting the result: a missing failure detail in one terminal may be a display or integration issue rather than a universal Codex CLI defect.
Validate elevated terminal approvals without weakening review
OpenAI’s 0.158 release notes say terminal input approval is enabled by default for elevated-permission commands, and that runtime-only grants should no longer trigger unnecessary repeat reviews. The Codex approvals and security training material should be treated as the governing model: approvals are a safety checkpoint, not a nuisance to remove. Your validation should prove that review still appears when it should and does not become repetitive in the specific runtime-grant cases you authorize for testing.
Use a harmless elevated-approval simulation first. The safest pattern is to ask Codex to explain what it would need before performing a write, permission change, package operation, network action, or other consequential command, without authorizing the command itself. Then, if your policy allows, approve a narrowly scoped non-destructive command and document whether the approval flow is understandable.
In this canary repository, do not run commands yet.
Explain whether you would need human approval before:
1. writing a file,
2. changing file permissions,
3. installing software,
4. accessing the network,
5. deleting files.
Use the active permission profile. Do not request broader access.
For an actual approval-flow test, choose a command that is allowed by your canary policy and has no destructive effect, such as reading a known harmless fixture file. If the command requires approval under your active policy, the reviewer should see enough information to decide. If no approval appears, verify that the command is truly within the allowed sandbox before marking the test as pass.
Ask for approval before running any command.
If approved, read only the file named README.md in this canary repository and summarize it in one sentence.
Do not write files, access the network, inspect credentials, or read outside the repository.
Never validate elevated approvals by running commands that change ownership, weaken permissions, disable security tools, clear logs, alter firewall rules, install unreviewed packages, remove files, publish data, rotate credentials, or modify production infrastructure. A release canary should create evidence about the approval user experience, not pressure reviewers into approving dangerous operations for the sake of a test.
Runtime-only grant repeat-review check
The 0.158 release notes say runtime-only grants should no longer trigger unnecessary repeat reviews. A conservative test is to use one narrow, temporary permission decision inside a canary session and observe whether Codex asks again for the same runtime-only grant without a new reason. This does not mean approvals should disappear for different commands, broader access, new directories, network operations, or later sessions.
Canary instruction:
Ask before any command. If a temporary runtime permission is granted for a harmless read-only action, do not treat that grant as permission for writes, network access, deletion, permission changes, package installation, or access outside the canary repository. If you need a different permission, ask again and explain why.
Observed approval behavior
Conservative interpretation
Rollout decision
Same narrow runtime-only grant is not repeatedly requested without a new reason.
Behavior aligns with the release-note fix in this tested scenario.
Record as pass for that scenario only.
Codex asks again for a materially different action.
This may be correct; different actions should receive separate review.
Do not mark as failure unless the request is truly redundant.
Codex proceeds to a broader action without approval.
This is a safety concern or policy mismatch.
Stop rollout and review permissions, transcript, and configuration.
Codex repeatedly asks for the identical narrow grant.
The fix may not apply to this environment or scenario.
Record evidence and keep rollout limited.
Approval validation is complete only when a human reviewer can explain what was requested, why it was allowed or denied, which files or commands were in scope, and what evidence proves the agent stayed within that scope. If your evidence consists only of “the task worked,” you have validated productivity, not approval safety.
Record pass, fail, blocked,
Configure MCP OAuth clients with registered callbacks, scoped access, and secret-safe evidence
Codex CLI 0.158 adds support for MCP servers whose OAuth clients use pre-registered secrets through the release-noted codex mcp add --oauth-client-secret option. Treat that addition as a configuration capability, not as a guarantee that an MCP server, identity provider, or downstream tool is safe to connect. The OpenAI MCP documentation states that Codex supports Streamable HTTP authentication with bearer tokens and OAuth, and the configuration reference keeps approval policies, sandboxing, and project trust as explicit controls. Your upgrade work should therefore prove three separate things: the OAuth client is registered correctly, the granted scopes are the minimum needed for the specific MCP tools, and no secret value appears in commands, prompts, logs, repositories, screenshots, tickets, transcripts, or release evidence.
The safest pattern is to pre-register an OAuth client with your identity provider or MCP authorization server before you add it to Codex. Use a non-production canary client first, assign it only the scopes required by the test server, and document who owns the client, who may rotate its secret, which redirect URI is allowed, and which MCP server the client is intended to reach. If the same organization uses the ChatGPT desktop app, Codex CLI, and IDE extension against the same Codex host, remember that OpenAI’s MCP guide states that those surfaces share MCP configuration for that host; do not assume that a local CLI-only test is isolated from every other user experience in your environment.
This release article covers Codex CLI 0.144.0 features including app-approval writes mode, interactive MCP authentication, and multi-agent concurrency controls. The Codex CLI 0.144 Arrives — New Writes Approval Mode, MCP Auth, and Multi-Agent Concurrency Controls article is a focused companion for MCP Authentication because it is the most specific candidate for MCP authentication because the title and excerpt explicitly mention MCP auth in a Codex CLI release context.
Pre-register the OAuth client before running Codex commands
Use your organization’s identity-provider process to create a dedicated OAuth client for the MCP server instead of reusing a broad application client. A dedicated client gives administrators a practical revocation handle, makes audit trails easier to interpret, and prevents a future MCP configuration change from inheriting unrelated scopes. Record only non-secret metadata in the rollout worksheet: client name, client ID placeholder, owner group, callback URI, allowed scopes, issuer, environment, and rotation contact. The actual client secret belongs in an approved secret manager or equivalent secure storage, not in a planning document.
OAuth registration field
Operational rule
Evidence to keep without secrets
Client name
Use an environment-specific name that identifies Codex and the MCP server purpose.
Example label such as codex-canary-mcp-docs-readonly; do not include secret material.
Client ID
Use the ID assigned by the authorization server; it is not a password, but still avoid posting it unnecessarily.
Use <OAUTH_CLIENT_ID> in runbooks and redact real IDs from public artifacts.
Client secret
Store only in approved secret storage and pass to authorized setup flows without exposing it in shell history.
Evidence should say “secret stored in approved vault entry” or “secret rotated on date,” never the value.
Redirect or callback URI
Register the exact callback URI documented by OpenAI for the Codex MCP OAuth flow.
Screenshot or export showing the exact callback field is acceptable only after checking that no secret appears nearby.
Scopes
Grant only the scopes needed by the specific MCP server and enabled tools.
List scope names and the business reason for each scope; reject unexplained broad scopes.
Issuer
Verify that the authorization server issuer matches the expected trusted issuer for the MCP server.
Record expected issuer as a non-secret value and compare it during canary authentication.
OpenAI’s MCP documentation calls out exact callback registration requirements for the OAuth flow. In practical rollout terms, “exact” means character-for-character agreement with the documented callback URI, including scheme, host, path, port if applicable, trailing slash behavior, and any registered loopback convention in the official documentation. Do not “fix” a failed OAuth redirect by adding multiple broad redirect patterns unless the identity provider and OpenAI documentation both allow that pattern and your security team approves it. A callback mismatch should be treated as a configuration defect, not as a reason to loosen redirect validation.
Secret-handling rule: every command, prompt, transcript, terminal recording, issue comment, support bundle, screenshot, and training note in this tutorial uses placeholders only. Never paste a real OAuth client secret, bearer token, access token, refresh token, API key, session cookie, private key, password, or stored credential into Codex, a shell command shown in a ticket, a repository, a screenshot, or an article draft.
Use the documented OAuth client flow with placeholders only
The OpenAI MCP guide documents adding an MCP server with a pre-registered OAuth client by using codex mcp add with --oauth-client-id. OpenAI’s Codex CLI 0.158 release notes add support for --oauth-client-secret for OAuth clients that require pre-registered secrets. The example below is a safe template because it uses placeholders rather than real values. Adapt only the non-secret structure after checking the current OpenAI documentation and your organization’s approved command-entry procedure.
# Example only: placeholders must be replaced through an approved secret-safe procedure.
# Do not paste a real client secret into a prompt, ticket, repository, screenshot, or shared terminal log.
codex mcp add <MCP_SERVER_NAME> \
--url <MCP_STREAMABLE_HTTP_URL> \
--oauth-client-id <OAUTH_CLIENT_ID> \
--oauth-client-secret <OAUTH_CLIENT_SECRET_PLACEHOLDER>
That template intentionally does not show a real host, tenant, path, client ID, or secret. In a hardened environment, even placing a secret directly on a command line may be prohibited because shells, process listings, terminal recorders, endpoint tools, or support logs can capture arguments. If your organization has a secret-injection mechanism or an approved interactive setup method, use that method instead of putting the secret into visible command text. If your policy does not permit command-line secrets, do not weaken the policy for convenience; open a platform-security ticket that asks for a compliant way to supply the OAuth secret to the Codex MCP setup flow.
Before the OAuth browser or device step completes, verify the authorization screen against a short allowlist. The issuer should be the expected identity provider or authorization server, not a lookalike tenant. The application name should match the registered MCP client, not a generic or unrelated app. The scopes should match the approved list, not a superset introduced by a default template. If the authorization screen displays a scope you cannot explain, stop and correct the client or server configuration before consenting.
OAuth check
Pass condition
Stop condition
Callback registration
The registered callback exactly matches the callback required by the OpenAI MCP documentation for Codex.
The provider accepts a wildcard, alternate domain, or broad redirect that was not approved for this client.
Issuer identity
The authorization prompt and token metadata point to the expected trusted issuer.
The issuer is unknown, misspelled, from a different tenant, or inconsistent with the MCP server design.
Client identity
The client name and ID correspond to the canary Codex MCP client.
The prompt references a legacy app, a production app during a canary, or an app with unclear ownership.
Scopes
Every requested scope has a documented MCP tool purpose and an accountable owner.
Broad, administrative, write, destructive, or unrelated scopes appear without explicit approval.
Tool approval
Server-level and per-tool approval modes remain aligned with OpenAI’s MCP controls and local policy.
Setup instructions attempt to bypass approval prompts, grant all tools, or remove review for consequential actions.
Map scopes to MCP tools before you enable users
OpenAI’s MCP guide documents server and per-tool approval modes, enabled and disabled tool lists, and authentication support. Your upgrade should connect those controls instead of treating them as independent checkboxes. A read-only documentation MCP server should not receive write scopes merely because a future workflow might need them. A deployment-related MCP server should not expose production mutation tools to general Codex users without separate approval gates, sandbox boundaries, and human change control. If a tool can send messages, create tickets, modify repositories, deploy code, change permissions, access sensitive records, or trigger external operations, require explicit human approval before the action occurs.
A practical scope review starts with the tool inventory. For each MCP tool, write down the intended business task, the data classes it can access, the maximum action it can perform, the OAuth scopes required, the approval mode, and the test fixture that proves least privilege. If you cannot prove that a scope is required by a tool you intend to enable, remove the scope from the canary client. If a tool requires a broad scope because the downstream system lacks granular permissions, document the compensating controls and obtain security approval before broader rollout.
# Example scope worksheet fragment; keep this in a private internal runbook without secrets.
MCP server: <MCP_SERVER_NAME>
Environment: <CANARY_OR_STAGING>
OAuth client: <OAUTH_CLIENT_ID_PLACEHOLDER>
Expected issuer: <EXPECTED_ISSUER>
Registered callback: <DOCUMENTED_CODEX_MCP_CALLBACK>
Tool: <READ_ONLY_TOOL_NAME>
Purpose: Retrieve approved project metadata for Codex context.
Requested scopes: <READ_SCOPE>
Approval mode: <SERVER_OR_TOOL_APPROVAL_MODE>
Allowed data: <NON_SECRET_TEST_FIXTURE>
Disallowed data: credentials, private customer records, restricted legal/health/financial data
Pass test: tool can read fixture metadata and cannot perform write action.
Tool: <WRITE_TOOL_NAME_IF_AUTHORIZED>
Purpose: <AUTHORIZED_PURPOSE>
Requested scopes: <WRITE_SCOPE>
Approval mode: human approval required before any external change
Pass test: dry-run or staging-only mutation requires approval and records non-secret evidence.
Do not ask Codex to infer whether a scope is safe from a pasted access token, authorization response, or decoded credential. If you need token claims reviewed, use your organization’s approved security tooling and redact the token value before creating any work item. Codex can help draft a checklist or compare a manually entered list of non-secret scope names against a policy, but it should not receive bearer tokens, refresh tokens, signed JWTs, cookies, or client secrets.
Validate issuer checks and consent evidence without leaking tokens
Issuer validation matters because OAuth security depends on knowing which authorization server issued the credential and which audience the token is meant for. During canary setup, capture evidence that the issuer, client, callback, and scopes match the approved plan. The evidence can be a redacted configuration export, an administrator attestation, or a screenshot of non-secret fields after careful review. Do not capture browser address bars containing authorization codes, terminal lines containing tokens, local callback payloads, or logs that include access-token material.
Use a two-person review for the first successful OAuth connection. The operator performs the setup on an authorized canary workstation. The reviewer checks the registration metadata, confirms the callback exactly matches the OpenAI-documented callback requirement, and verifies that the scopes and tool approvals match the rollout worksheet. This review is not a legal compliance certification; it is an operational safeguard that catches the common errors that make MCP integrations over-permissive.
Confirm the canary workstation is authorized, patched, and using the intended Codex CLI version.
Confirm the MCP server URL is the approved canary or staging endpoint, not production unless production testing has been explicitly approved.
Confirm the OAuth client belongs to the same environment and owner group as the MCP server.
Confirm the callback registered with the authorization server exactly matches the OpenAI-documented callback value for Codex MCP OAuth.
Confirm the issuer value matches the expected trusted issuer and not a similar-looking tenant.
Confirm the requested scopes are listed in the scope worksheet and tied to enabled MCP tools.
Confirm approval modes remain active for tools that can perform external, destructive, privileged, or consequential actions.
Confirm no secret, token, authorization code, or private record appears in saved evidence.
Protect direct exec-server WebSocket connections with bearer-token controls
Codex CLI 0.158 also adds bearer-token protection for direct exec-server WebSocket connections, according to OpenAI’s stable release notes. Interpret that narrowly: bearer tokens protect direct exec-server WebSocket connections when the server and client are configured correctly and when the surrounding environment treats the token as a credential. The release note does not mean every WebSocket in every deployment is automatically protected, nor does it remove the need for network restrictions, token rotation, log redaction, endpoint hardening, and human approval for privileged operations initiated through the connection.
This article outlines enterprise security best practices for running AI coding agents such as Codex, focusing on safe operation in development environments. The Running AI Coding Agents Safely: Enterprise Security Best Practices for Codex article is a focused companion for WebSocket Security because although not WebSocket-specific, it is the most relevant allowed target for security guidance around Codex operational surfaces and complements bearer-token transport hardening.
Use environment-variable placeholders for bearer tokens
Bearer tokens should be handled as secrets. In examples, use environment-variable names and placeholder values only. Do not paste a real bearer token into Codex prompts, command examples, shell history, process managers, issue trackers, chat messages, screenshots, CI logs, repository files, or terminal transcripts. If your organization uses a secret manager, inject the token through the approved runtime mechanism and record only the secret reference name in deployment evidence.
# Example only: do not use real token values in shared commands or logs.
# Use an approved secret manager or runtime injection mechanism in real environments.
export CODEX_EXEC_SERVER_BEARER_TOKEN="<BEARER_TOKEN_PLACEHOLDER>"
export CODEX_EXEC_SERVER_WS_URL="wss://<AUTHORIZED_EXEC_SERVER_HOST>/<WEBSOCKET_PATH>"
The variable names above are illustrative placeholders for your local wrapper or deployment procedure unless OpenAI’s current documentation for your deployment specifies exact names. The key operational point is not the spelling of a sample variable; it is that bearer-token material must remain outside prompts, repositories, screenshots, and ordinary logs. If a developer needs to prove that a token was present, the acceptable evidence is a redacted health check, a server-side authentication success event with token value suppressed, or an attestation from the approved secret-injection system.
Bearer-token risk
Unsafe practice
Recommended control
Shell history exposure
Typing a real token directly into a command that is stored by the shell.
Use approved secret injection, disable recording only if policy allows, and avoid showing token values entirely.
Process-list exposure
Passing a token as a visible command-line argument.
Prefer environment or secret-manager injection where permitted by local security standards.
Log leakage
Printing request headers, connection URLs with credentials, or authorization failures containing token text.
Redact authorization headers and token-like values at client, proxy, and server logging layers.
Repository leakage
Committing token values to scripts, dotenv files, notebooks, fixtures, or screenshots.
Store only placeholder files, use secret scanning, and rotate immediately if a real token is committed.
Overbroad access
Using the same token for unrelated users, environments, or servers.
Issue environment-specific tokens with narrow audience, ownership, and rotation procedures where supported.
Validate direct exec-server WebSocket authentication
A direct exec-server WebSocket can be a powerful path into an execution environment, so the test must prove both acceptance and rejection. A passing test is not just “the authorized client connects.” It is also “an unauthenticated client fails,” “a placeholder or wrong token fails,” “the server does not reveal sensitive detail on failure,” and “logs do not record token values.” If your server cannot demonstrate clean denial behavior in a canary, do not move the configuration to a wider developer population.
# Pseudocode test plan only. Do not paste real tokens into this script or its output.
Test case: authorized connection
URL: wss://<AUTHORIZED_EXEC_SERVER_HOST>/<WEBSOCKET_PATH>
Authorization: Bearer <INJECTED_FROM_SECRET_MANAGER>
Expected: connection succeeds; server logs authentication success without token value.
Test case: missing token
URL: wss://<AUTHORIZED_EXEC_SERVER_HOST>/<WEBSOCKET_PATH>
Authorization: <ABSENT>
Expected: connection rejected; no execution session created.
Test case: invalid token
URL: wss://<AUTHORIZED_EXEC_SERVER_HOST>/<WEBSOCKET_PATH>
Authorization: Bearer <INTENTIONALLY_INVALID_PLACEHOLDER>
Expected: connection rejected; logs do not include the invalid token text.
Test case: wrong environment
URL: wss://<PRODUCTION_EXEC_SERVER_HOST_IF_AUTHORIZED_FOR_NEGATIVE_TEST>/<WEBSOCKET_PATH>
Authorization: Bearer <CANARY_TOKEN_PLACEHOLDER>
Expected: connection rejected unless explicitly designed and approved otherwise.
Do not run negative tests against production unless the environment owner has explicitly approved the timing, source address, rate, and expected alert behavior. Authentication-failure testing can trigger security monitoring, account lockouts, or incident workflows. In a mature rollout, the security team knows which test window is authorized, the operations team knows which alerts are expected, and the evidence packet shows only redacted headers, timestamps, status outcomes, and non-secret request IDs.
Confirm network boundaries around WebSocket access
Bearer tokens are one control, not the only control. Direct exec-server WebSocket access should be limited by network location, host authorization, endpoint policy, and server-side identity checks where those controls are available in your environment. If a token leaks, network restrictions and narrow audience design can reduce blast radius. If the network boundary is broad, a token mistake becomes more consequential. The Codex 0.158 release note is a reason to test your WebSocket authentication path, not a reason to publish a previously internal exec server to untrusted networks.
For canary rollout, document the expected connection path: client workstation, proxy if any, destination host, WebSocket path, authentication header handling, logging layer, and execution environment. Then prove that an unauthorized network cannot connect and that an authorized network still requires a valid bearer token. If proxies or gateways terminate or forward WebSocket traffic, verify that they do not strip the authorization header needed by the exec server and that they do not log bearer-token values while debugging connection failures.
Control layer
Question to answer
Acceptable canary evidence
Client host
Is the workstation or runner authorized to initiate direct exec-server connections?
Asset ID, owner, environment, and patch status; no local secrets in the artifact.
Network route
Can only approved source networks reach the WebSocket endpoint?
Firewall or gateway rule summary with sensitive ranges redacted as required.
Authentication
Does the server require a valid bearer token for direct exec-server WebSocket connections?
Redacted success and failure logs showing token values suppressed.
Logging
Are authorization headers, query strings, and token-like values redacted?
Sample log lines using placeholders or confirmed redaction markers.
Execution scope
What can a successfully authenticated session reach or change?
Sandbox profile, writable roots, network policy, and approval policy summary.
Verify elevated terminal approval behavior and runtime-only grants
OpenAI’s 0.158 release notes state that terminal input approval is enabled by default for elevated-permission commands, and that runtime-only grants should no longer trigger unnecessary repeat reviews. The approvals training material emphasizes that agent approvals are part of safe operation rather than an inconvenience to remove. Your validation should therefore prove that approval prompts appear when elevated authority is needed, that reviewers receive enough context to make a decision, and that a grant intended only for the current runtime does not become a durable permission change.
Do not test elevated approvals by running destructive commands against a real repository, production server, user directory, or shared credential store. Use a throwaway canary repository, a disposable directory, or a staging environment with backups and Git checkpoints. The goal is to verify the approval mechanism, not to prove that a risky command is harmless. Human approval remains mandatory for external messages, submissions, payments, purchases, bookings, destructive operations, permission changes, publication, legal commitments, campaign launches, and other consequential actions.
Design a safe elevated-command approval test
A safe elevated-command test uses a command that requires the relevant approval path but affects only a disposable target. For example, a platform team may create a temporary canary directory owned by the test account, ask Codex to perform a controlled operation that would require elevated permission under the local policy, and confirm that the approval review appears before the command proceeds. If local policy defines specific elevated operations, use those policy definitions rather than inventing a more dangerous test.
# Example test fixture only. Adapt to your platform policy and avoid production paths.
Repository: <CANARY_REPOSITORY_PATH>
Disposable directory: <TEMP_CANARY_DIRECTORY>
Protected target for test: <SANDBOXED_PATH_REQUIRING_APPROVAL>
Expected behavior: Codex requests approval before elevated-permission terminal input.
Forbidden targets: production repositories, user home secrets, credential stores, customer data, system configuration.
The reviewer should inspect the command, working directory, sandbox profile, intended file targets, network behavior, and expected output before approving. If the approval prompt lacks enough detail to evaluate the risk, deny the request and refine the task. Approval is not a rubber stamp; it is the control that prevents an agent from converting an ambiguous instruction into a privileged operation without accountable human review.
Approval review item
Approve only if
Deny if
Command purpose
The operation directly supports the canary test and has a documented expected outcome.
The command performs extra cleanup, broad discovery, network access, or unrelated changes.
Target path
The path is disposable, backed up, or inside an approved test sandbox.
The path includes production code, credentials, personal files, system directories, or unknown symlinks.
Permission level
The elevated permission is necessary for the specific test and limited to the runtime request.
The request asks for durable permission expansion or broad future access.
Network behavior
No network access is needed, or the exact approved endpoint is listed.
The command contacts unapproved hosts, downloads scripts, or uploads data.
Rollback
The operator can restore the canary fixture or discard the test repository.
The operation cannot be undone or its effects cannot be bounded.
Validate that runtime-only grants do not become durable access
Runtime-only grants are useful only if they remain runtime-only. After approving a controlled elevated operation, close the relevant Codex session or runtime according to your normal procedure, start a fresh session, and attempt the same category of operation against the same disposable fixture. The expected result, based on the 0.158 release note, is not that approvals disappear forever; it is that unnecessary repeat reviews should be reduced while approval boundaries remain meaningful. If a grant persists beyond the intended runtime or silently expands the project’s default permissions, treat that as a rollout blocker until you understand the configuration.
Create a disposable canary fixture and record its path using placeholders in shared evidence.
Ask Codex to perform the controlled operation that requires elevated terminal input approval under local policy.
Confirm that terminal input approval is requested before the elevated command runs.
Approve only after checking command text, target path, sandbox context, and rollback plan.
Verify the operation completed only against the disposable fixture.
End the runtime or session using your standard procedure.
Start a fresh session and repeat the request to determine whether the permission boundary behaves as intended.
Inspect user and project configuration for unintended durable permission changes, remembering that project-scoped configuration is loaded only for trusted projects and cannot override machine-local provider, auth, or telemetry keys under OpenAI’s configuration reference.
When documenting the result, separate observed behavior from policy judgment. “The second request did not trigger an unnecessary repeat review within the same runtime” is different from “this command is now safe.” The former is a product-behavior observation; the latter would be an unsupported security conclusion. For any command that can change permissions, delete data, affect customers, publish content, send external communications, or trigger financial or legal commitments, keep human approval in the workflow regardless of runtime-grant improvements.
Use approval failures as evidence, not as obstacles to bypass
If an elevated approval request is denied, capture the non-secret reason and improve the workflow. A denial may reveal that Codex selected a broad path, combined multiple operations, failed to explain the network endpoint, or attempted a durable permission change. Those are useful findings during a canary. Do not respond by disabling approvals, broadening sandbox roots, adding blanket allowlists, or instructing users to approve prompts faster. The controlled upgrade succeeds when risky operations are stopped early and explained clearly.
# Example denial note; do not include secrets, private paths, or token values.
Date: <DATE>
Codex CLI version: <VERSION_OUTPUT_REDACTED_IF_NEEDED>
Environment: <CANARY_WORKSTATION>
Requested operation: <SUMMARY_OF_ELEVATED_COMMAND>
Decision: denied
Reason: command targeted <UNAPPROVED_PATH_CATEGORY> and did not provide a bounded rollback plan.
Follow-up: revise task prompt to use <DISPOSABLE_FIXTURE>; keep approval requirement enabled.
Approval telemetry and release evidence should be handled like security evidence. Store it where only authorized administrators and auditors can access it, redact sensitive paths and identifiers when possible, and avoid copying terminal transcripts that include unrelated repository contents or private records. If an approval review is interrupted by new user input, note that OpenAI’s 0.158 release notes include a fix for approval reviews interrupted by new user input; then retest the interrupted-review case in the can
Build the final canary matrix before broad deployment
A Codex CLI 0.158 rollout should finish with a cross-platform canary matrix that proves the release on the combinations your organization actually operates. OpenAI’s release notes identify fixes and changes across Windows, Linux, macOS, MCP authentication, WebSocket protection, elevated terminal approvals, transcript copying, image workflows, Mermaid rendering, and command completion events. That scope is too broad for a single “it launches” check; the canary should map each release-sensitive behavior to an operating system, configuration boundary, expected result, failure evidence, owner, and rollback rule.
The canary should remain smaller than production but representative enough to catch regressions. For example, a platform team might select one Windows 10 workstation with typical enterprise path conventions, one Windows machine with stored credential workflows enabled by policy, one Linux developer container that uses nested writable roots, one macOS device that exercises system path aliases, and one controlled MCP host using a pre-registered OAuth client. The exact fleet design depends on your environment, but every selected node should be authorized, non-production or low-blast-radius, monitored, and capable of rollback without waiting for a release meeting.
Canary lane
Primary release behavior to validate
Required evidence
Rollback trigger
Windows 10 developer workstation
Sandbox behavior with Windows 10 paths, stored credentials, and large permission policies described in OpenAI’s 0.158 release notes
Version output, sandbox policy summary, denied/allowed operation log, redacted command transcript, and human reviewer notes
Connection succeeds without token, token appears in logs, access is reachable from unintended networks, or auth behavior is ambiguous
Elevated terminal approval lane
Terminal input approval enabled by default for elevated-permission commands and reduced unnecessary repeat reviews for runtime-only grants
Approval prompt capture with secrets redacted, reviewer identity or role, command classification, decision, and post-action verification
Elevated command runs without approval, approval is skipped unexpectedly, runtime grant persists beyond intended session, or reviewer cannot reconstruct the decision
Transcript and TUI usability lane
Configurable copy-on-select, right-click paste, and Markdown-preserving transcript copy in the fullscreen TUI
Missing early output, no launch-failure detail where expected, diagram corruption that affects documentation workflows, or event telemetry gap
The matrix should record negative tests as first-class canary items, not as afterthoughts. A successful release is not merely one where an authorized path succeeds; it is one where unauthorized paths fail predictably, leave evidence, and do not expose secrets. For 0.158, negative tests are especially important because the release introduces authentication-related surface area for MCP OAuth client secrets and bearer-token-protected direct WebSocket connections while also changing approval behavior for elevated terminal input.
Run negative tests that prove boundaries still fail closed
Negative tests should be safe, reversible, and designed to verify control behavior rather than defeat it. The objective is to confirm that Codex, the operating system, the sandbox, MCP configuration, network controls, and reviewer workflow reject operations that should not be permitted. Do not use production secrets, live customer data, destructive commands, or attempts to bypass endpoint security. A negative test that requires a real credential or a privileged production target is too dangerous for a rollout canary.
Control boundary
Safe negative test
Expected result
Evidence to retain
Sandbox writable roots
Ask Codex to write a harmless marker file outside the approved test writable root, using a non-sensitive path selected by the platform team
The operation is denied or requires approval that should not be granted for the test
Command transcript, denial message, path, sandbox profile, and reviewer note
Project trust boundary
Place a project-scoped configuration file in an untrusted project and verify it is not treated as an override for machine-local provider, authentication, or telemetry keys
Project configuration is not allowed to override machine-local provider/auth/telemetry controls, consistent with OpenAI’s configuration reference
Config file hash or redacted diff, trust status, effective configuration summary, and reviewer confirmation
MCP tool authorization
Attempt to invoke a disabled or unapproved MCP tool in a controlled test server
The tool is unavailable, denied, or requires approval according to the configured server and per-tool approval modes
Tool list, approval mode, denial record, and server log with tokens redacted
OAuth callback registration
Use an intentionally incorrect callback URL in a staging registration record or staging-only configuration
OAuth flow fails because callback registration does not match the server requirements documented by OpenAI
Callback inventory, failure message, timestamp, and confirmation that no token was issued to the wrong callback
WebSocket bearer token
Attempt a direct exec-server WebSocket connection without the required bearer token from an approved network test host
The connection is rejected and no privileged operation runs
Network source, connection result, server log with redaction, and confirmation that no token was printed
Elevated command approval
Request a harmless elevated operation that should trigger review under the organization’s policy
Terminal input approval appears before execution, and the reviewer can deny or approve based on context
Approval prompt, command classification, reviewer decision, and post-test state verification
Clipboard safety
Copy a fixture transcript that contains fake placeholders such as <TOKEN_PLACEHOLDER>, then inspect the copied result under local policy
Markdown structure is preserved for allowed content, and no real secret enters the clipboard
Fixture text, copied output, clipboard-handling note, and endpoint policy status
Do not convert a failed negative test into a workaround. If an unauthorized WebSocket connection succeeds, if an MCP tool appears despite being disabled, or if an elevated command runs without the expected review, pause the rollout and treat the outcome as a security finding. The correct next step is to preserve evidence, revoke or rotate any exposed test credentials, restore the previous known-good configuration if needed, and have the platform owner determine whether the issue is a local misconfiguration, an unsupported assumption, or a release-blocking defect.
Test OAuth failures without exposing secrets
OpenAI’s 0.158 release notes state that Codex now supports MCP servers whose OAuth clients use pre-registered secrets through codex mcp add --oauth-client-secret. That feature helps organizations integrate with OAuth deployments that require confidential clients, but it also creates a new place where secret-handling mistakes can become durable. A canary should therefore test both the happy path and controlled failure modes while keeping real secrets out of prompts, screenshots, shell history, ticket comments, chat messages, and repository files.
A safe OAuth failure test begins with a staging MCP server or a dedicated test registration, not a production authorization path. The test operator should use placeholders in written evidence and pass any real secret through an approved secret manager or secure local injection mechanism chosen by the organization. The report should never include the secret value. It should show only that a configured secret existed, that the callback matched the registered value, that scopes were intentionally narrow, and that failure modes did not leak tokens or grant access to unapproved tools.
Callback mismatch test: configure a staging record with a deliberately incorrect callback and verify that authorization fails. The retained evidence should list the expected callback, the test callback, the failure category, and confirmation that no usable token was issued to the wrong callback.
Missing client-secret test: run the staging flow without providing the confidential-client secret through the approved secure mechanism. The expected result is authentication failure, not a fallback to unauthenticated access.
Invalid client-secret test: use a rotated or intentionally invalid staging secret and verify that the server rejects it without printing the value in local logs, terminal output, or diagnostic bundles.
Overbroad scope test: request a scope that should not be allowed for the canary toolset and verify that the OAuth server, MCP server, Codex approval mode, or local policy blocks use of the corresponding tool.
Disabled-tool test after successful OAuth: complete OAuth successfully with narrow staging scopes, then attempt to invoke a disabled MCP tool and confirm the tool remains unavailable or requires explicit approval.
The strongest OAuth report separates identity, authentication, authorization, and approval. A successful OAuth login only proves that the client can authenticate under the registered flow. It does not prove that every enabled tool is appropriate, that scopes are least-privilege, that callbacks are correct for every environment, that tokens are protected for their full lifetime, or that human review is unnecessary. Treat OAuth as one layer in the control stack, not a substitute for tool allowlists, sandboxing, endpoint protection, credential management, or approval workflow.
# Example evidence template only. Do not paste real secrets or tokens.
mcp_oauth_canary:
environment: "staging"
codex_version: "0.158.x as verified locally"
server_name: "approved-mcp-staging-name"
oauth_client_id: "<CLIENT_ID_PLACEHOLDER>"
client_secret_handling: "provided through approved secret mechanism; value not recorded"
registered_callbacks:
- "<REGISTERED_CALLBACK_PLACEHOLDER>"
requested_scopes:
- "<NARROW_SCOPE_PLACEHOLDER>"
enabled_tools:
- "<TOOL_NAME_PLACEHOLDER>"
disabled_tools:
- "<DISABLED_TOOL_PLACEHOLDER>"
approval_mode: "<SERVER_OR_TOOL_APPROVAL_MODE>"
negative_tests:
callback_mismatch: "failed as expected"
missing_secret: "failed as expected"
invalid_secret: "failed as expected"
disabled_tool_invocation: "denied as expected"
redaction_verified_by: "<HUMAN_REVIEWER_ROLE>"
Define MCP tool allowlists before users discover capabilities by trial and error
OpenAI’s MCP documentation describes server and per-tool approval modes, enabled and disabled tool lists, and supported authentication patterns such as bearer tokens and OAuth for Streamable HTTP. The practical governance rule is simple: decide which tools are allowed before a user asks Codex to perform work through the server. Trial-and-error discovery encourages accidental overreach, weakens audit evidence, and makes it harder to distinguish an intended capability from a configuration mistake.
A tool allowlist should start with business purpose, not technical convenience. For example, a documentation MCP server might allow read-only issue lookup and draft-generation support while disabling write operations, label changes, publication, or external notifications until a human reviewer explicitly approves them outside the canary. A repository MCP server might allow status inspection and branch metadata but require approval for changes, merges, releases, or permission updates. The key is to pair each tool with a permitted data class, environment, approval requirement, and owner.
Tool category
Default canary stance
Approval requirement
Operational warning
Read-only metadata lookup
Allow only for authorized systems and non-sensitive records needed for the canary
Pre-approved if documented in the canary plan
Metadata can still expose confidential project names, usernames, internal paths, or incident context; redact reports accordingly
Content retrieval
Allow only where the data class is approved for model-assisted analysis
Human approval if content may contain private, regulated, privileged, or customer-confidential information
Do not use canaries as a shortcut for privacy review or legal review
File write or repository modification
Disable by default in the initial canary or confine to throwaway branches and fixtures
Explicit approval before execution and Git checkpoint before and after the task
External message, ticket, publication, or notification
Disable for technical canary unless the rollout specifically tests an approved communication workflow
Mandatory human approval before any external or consequential message
Drafting can be tested with fixtures; sending should not be delegated without accountable review
Permission, identity, billing, deployment, or production-change tool
Disable in the first canary unless a senior platform owner approves a dedicated control test
Mandatory human approval, change ticket, rollback plan, and post-action verification
Codex 0.158 does not make consequential operations safe simply because an approval prompt exists
The allowlist should also specify what is intentionally disabled. A “not configured” tool is not the same as a prohibited tool in an audit discussion. Write down disabled tools, the reason each is disabled, the approval path for future enablement, and the environment where the decision applies. If the ChatGPT desktop app, Codex CLI, and IDE extension share MCP configuration for the same Codex host, as OpenAI’s MCP guide states, administrators should verify that a change intended for one surface does not unintentionally broaden another surface used by the same developers.
Record approvals as evidence, not as a rubber stamp
OpenAI’s Codex learning material on agent approvals and security emphasizes the importance of approval review, and OpenAI’s 0.158 release notes say terminal input approval is enabled by default for elevated-permission commands while runtime-only grants should no longer trigger unnecessary repeat reviews. The operational lesson is not to click through prompts faster. The lesson is to make approvals more meaningful by recording enough context for a later reviewer to understand what was requested, why it was safe, what boundary applied, and what happened after execution.
This article explains how to harden local Codex projects with trust boundaries, layered configuration, sandboxes, approvals, web search controls, and secret filtering. The Harden Codex Local Projects: Trust Boundaries, Layered Config, Sandboxes, Approvals, Web Search, and Secret Filtering article is a focused companion for Elevated Command Approvals because it closely supports a discussion of elevated command approvals because it specifically covers Codex local hardening, approval controls, sandboxes, and secret filtering.
An approval record should be concise but complete. It should identify the command class, target system, sandbox context, data class, whether the operation is reversible, whether a Git checkpoint exists, whether the request touches credentials or permissions, who approved it, and how the result was verified. For canary purposes, this record can live in a change ticket, release checklist, internal audit system, or other approved evidence repository. Avoid screenshots that capture secrets, tokens, private user data, or sensitive paths unless your security team has explicitly approved the redaction method.
Approval records should explicitly distinguish runtime-only grants from durable configuration changes. A runtime-only grant that allows a command in a session should not be treated as permission to edit project configuration, expand tool access, change workspace defaults, or bypass future review. If a user asks for “just one more permission” during a canary, the reviewer should classify the request, determine whether it belongs in the canary plan, and deny or defer anything outside the approved scope.
Add observability that catches authentication, sandbox, and approval drift
Observability for a Codex CLI 0.158 rollout should answer four questions: what version ran, under which configuration, with which tools and approvals, and what happened when boundaries were tested. It should not collect unnecessary secrets, tokens, private code, personal data, privileged legal content, regulated health information, or customer records. The useful signal is control behavior, not a complete dump of developer activity.
The first observability layer is local release evidence. Each canary host should record the installed Codex version, operating system, project trust status, effective non-secret configuration summary, sandbox profile, enabled MCP servers, enabled/disabled MCP tool list, and whether the canary used direct exec-server WebSocket connections. This evidence helps separate a release defect from a misconfigured host. For example, a WebSocket negative test that succeeds without a token may be a server configuration failure rather than a CLI failure; without configuration evidence, the team will waste time debating the wrong layer.
The second observability layer is event evidence. For command completion events, retain whether early output appeared, whether launch failures carried useful detail, whether an approval prompt was interrupted by new user input, and whether the final state matched expectations. OpenAI’s 0.158 release notes mention fixes in these areas, so a canary should verify them with harmless commands and failing fixtures rather than waiting for a production debugging session.
The third observability layer is security evidence. Record denied sandbox writes, failed OAuth attempts, rejected WebSocket connections without bearer tokens, disabled-tool invocations, approval denials, and redaction checks. These records show that controls are not merely configured but exercised. They also give security teams a baseline for anomaly detection after rollout: if a previously disabled MCP tool begins appearing in logs, or if WebSocket attempts increase from unexpected networks, the deployment may have drifted.
Signal
Why it matters
Collection rule
Codex version and installation source
Confirms that the host is actually testing 0.158 behavior
Record version output and installation/update method documented by OpenAI; do not infer version from package names alone
Effective non-secret configuration
Explains sandbox, approval, MCP, provider, and telemetry behavior
Capture redacted summaries; never publish secrets, tokens, private keys, or credential file contents
Approval decisions
Proves that elevated and consequential actions had human review
Use harmless marker paths and fixture files; do not probe unauthorized third-party systems
Tool allowlist decisions
Prevents accidental capability expansion across MCP surfaces
Record allowed, disabled, and approval-required tools with owner and environment
Set rollback triggers that humans can execute under pressure
A rollback plan is useful only if the team can apply it while a release is noisy. Define triggers before the first canary starts, assign an owner, and decide what evidence must be preserved before reversing the change. OpenAI’s sources document how to install and configure Codex, MCP, approvals, and project configuration, but your organization is responsible for its local rollback mechanics, package management, endpoint controls, and change-management process.
Rollback should not wait for a perfect root-cause analysis when a control boundary fails. If bearer-token protection is ambiguous, if OAuth secrets appear in logs, if an elevated command runs without the expected approval, if sandbox writes escape the intended root, if MCP tool exposure is broader than the allowlist, or if a canary host becomes unstable enough to block normal development, halt expansion and return that lane to the previous known-good state. The team can investigate from preserved evidence after the blast radius is contained.
Trigger class
Examples
Immediate action
Before resuming rollout
Credential exposure
OAuth client secret, bearer token, API key, or session token appears in terminal output, logs, screenshots, or tickets
Stop the lane, restrict evidence access, rotate or revoke the exposed credential through approved procedures, and notify the security owner
Prove redaction, update secret-handling workflow, rerun negative tests, and obtain human sign-off
Authentication bypass or ambiguity
Direct WebSocket connection succeeds without bearer token, OAuth callback mismatch succeeds, or disabled tool executes
Disable the affected path or restore previous configuration; preserve minimal redacted evidence
Identify configuration or product behavior, validate failure tests, and document the corrected boundary
Sandbox failure
Unexpected write outside approved root, Windows path crash, Linux nested-root startup failure, or macOS alias resolving unsafely
Remove host from canary and restore previous sandbox profile or CLI version according to local procedure
Repeat path-specific tests on a clean fixture and review project trust configuration
Approval failure
Elevated command runs without review, reviewer cannot reconstruct a decision, or runtime grant becomes durable unexpectedly
Pause elevated-command rollout and deny further elevated tests until approval records are corrected
Frequent crashes, missing launch-failure detail, broken command completion events, or regression that blocks normal developer work
Stop expansion, collect version and fixture evidence, and restore the affected users to the previous known-good state
Confirm fix or workaround in a smaller canary before reintroducing the lane
Rollback should also include communication. Developers need to know whether they should stop testing a lane, avoid an MCP server, refrain from copying transcripts, or return to a prior approved configuration. Security teams need to know whether a credential exposure occurred. Administrators need to know whether a workspace policy or project configuration should be frozen. The announcement should be specific and bounded; do not create unnecessary alarm, but do not hide a control failure behind vague release language.
Stage the rollout from one team to general availability
A staged rollout should expand only when evidence supports the next group. Begin with a harmless laboratory fixture, then one platform engineer, a small cross-platform canary, a volunteer product team, and finally a wider deployment. Each stage needs named entry criteria, exit criteria, rollback authority, and accountable approval.
Release intake: translate the 0.158 release notes into environment-specific claims and confirm the supported installation path.
Platform canary: exercise Windows, Linux, macOS, MCP, WebSocket, and elevated-approval lanes with redacted evidence.
Developer pilot: admit a small authorized group, keep tools on the approved allowlist, preserve Git checkpoints, and sample failures.
Department rollout: expand only after negative tests pass, observability works, and security owners accept the documented residual risks.
General availability: publish the supported configuration, known limitations, escalation path, and rollback procedure; continue monitoring for drift.
Release decision and rollback checklist
Gate
Required evidence
Stop condition
Identity and version
Approved installer provenance and verified 0.158 version
Unexpected binary, version, or configuration source
MCP and OAuth
Exact callback, approved scopes, placeholder-only documentation, and negative authentication tests
Secret exposure, scope ambiguity, or callback mismatch
WebSocket authentication
Valid bearer acceptance and missing, malformed, expired, or wrong-token rejection
Unauthenticated connection or leaked token
Approvals and sandbox
Elevated actions prompt correctly and unapproved paths remain blocked
Action proceeds without expected review or boundary evidence is unclear
Rollback
Previous known-good version and configuration can be restored by a named owner
Rollback is untested, too slow, or depends on an unavailable secret
Codex 0.158 does not make unsafe commands safe, validate every MCP server, or replace least privilege, endpoint security, credential management, sandbox review, or human approval. Treat every generated recommendation as a draft until the accountable owner verifies it against the real environment.
Conclusion
The safest upgrade is evidence-led: preserve a checkpoint, update through the documented path, validate each changed behavior with harmless fixtures, keep credentials out of prompts and artifacts, and widen access only after platform and security owners sign off. If any authentication, approval, sandbox, or rollback test is inconclusive, pause the rollout rather than rationalize the gap.
Access 40,000+ AI Prompts for ChatGPT, Claude & Codex — Free!
Subscribe to get instant access to our complete Notion Prompt Library — the largest curated collection of prompts for ChatGPT, Claude, OpenAI Codex, and other leading AI models. Optimized for real-world workflows across coding, research, content creation, and business.
What OpenAI’s GPT-5.5 notice changes—and what it does not OpenAI’s official ChatGPT notice says that GPT-5.5 retires from ChatGPT, ChatGPT Work, and Codex across all plans on October 14. The same notice directs Codex users to use GPT-5.6 Sol or…
Why the Perplexity Astra story matters—and where its evidence stops OpenAI’s September 14, 2026 customer story about Perplexity presents GPT-6 Astra in a notably operational setting: not as a general productivity anecdote, but as a model used around communications, software…
A safe prompt library for authorized Codex 0.158 platform work This masterclass is a practical prompt library for platform teams that are planning, testing, or documenting a controlled rollout of Codex CLI 0.158 across developer workstations, trusted repositories, and approved…
Why API key governance is now an administrator-level control, not just a developer habit OpenAI’s production best-practices guidance now gives administrators a clearer policy surface for governing how new API keys are created and how long newly created keys may…
