codex-manual.md 2026-08-07 18:59 UTC to 2026-08-08 03:02 UTC

title: "Codex Manual" hidden: true

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Find By Topic

• pricing, plans, ChatGPT, API key, Plus, Pro, Business, Enterprise, Edu, feature maturity, what's new: Surfaces and experiences
• prompting, threads, context window, multi_agent, subagents, projects, long-running work, /plan, workflow: Execution Model and Workflows
• approval_policy, sandbox_mode, permissions, permission profiles, network access, read-only, workspace-write, danger-full-access, security, cyber: Approvals, Sandboxing, and Security
• config.toml, .codex/config.toml, auth.json, ChatGPT sign-in, API key login, models, providers, model_reasoning_effort: Configuration, Authentication, and Models
• codex exec, codex cloud, codex mcp, worktrees, cloud environments, internet access, Voice, remote connections, web search, image generation: CLI, IDE, App, and Cloud Behavior
• AGENTS.md, skills, plugins, plugin packaging, plugin marketplace, hooks, Docs MCP, rules, Code Review rules, custom prompts, MCP, GitHub integration, Slack integration: Customization, Skills, Rules, MCP, and Integrations
• sdk, noninteractive, app-server, scheduled tasks, github-action, CI, auth in CI: Noninteractive and Programmatic Interfaces
• Windows, WSL, enterprise, managed configuration, Amazon Bedrock, RBAC, data residency, OSS: Platform, Enterprise, and Caveats

Surfaces and experiences

Entry points, plans, supported surfaces, maturity, and high-level product framing.

ChatGPT on the web

Source: ChatGPT on the web

Use ChatGPT on the web to research, analyze, and create files.

Features

Source: Features

Explore workflows, capabilities, commands, and settings for working in ChatGPT.

ChatGPT brings projects and long-running chats together with web browsing, files, images, and plugins. Commands, settings, and troubleshooting references round out these workflows, from choosing the right workflow to giving each chat the context and tools it needs.

Explore projects and chats

Workflows

Ways to organize, delegate, and review work.

• Projects and chats: Keep related chats, context, and work together.

• Codex Remote: Start tasks, approve actions, and review work from your phone.

• Sites: Create, save, and publish interactive websites and apps in ChatGPT.

• Visualizations: Turn ideas and information into interactive visual explanations.

• Scheduled tasks: Schedule recurring work and review completed results.

• Long-running work: Let ChatGPT continue working while you step away.

• Notifications: Choose how ChatGPT tells you when work needs attention.

• Pets: Choose an animated companion and follow chat activity.

• Codex Micro: Monitor and control ChatGPT chats from a Work Louder keyboard.

Capabilities

Tools ChatGPT can use to understand, create, and take action.

• Browser: Let ChatGPT browse websites and take action while you stay in control.

• Computer use: Let ChatGPT interact with apps through the visual interface.

• ChatGPT Voice: Try voice in Chat, Work, and Codex in the ChatGPT desktop app.

• Plugins: Install reusable workflows, connected tools, and shared context.

• Web search: Find current information and bring sources into a task.

• Image generation: Create and edit images as part of your work.

• Image inputs: Use screenshots and images as context for ChatGPT.

• Appshots: Capture app state for visual inspection and debugging.

• Chrome extension: Share browser context with ChatGPT from Chrome.

• Work with files: Create, preview, and refine documents and other generated files.

Reference

Find commands and settings for the ChatGPT desktop app.

• Commands: Use app commands, keyboard shortcuts, and deep links.

• Slash commands: Use shortcuts for common interactive actions.

• Settings: Configure ChatGPT desktop app preferences.

• Troubleshooting: Resolve common issues in the ChatGPT desktop app.

Glossary

Source: Glossary

Use this glossary as a quick reference for Codex terms across the app, CLI, IDE extension, cloud, SDK, and related integrations.

Resources

Source: Resources

Find Codex videos, community programs, and OpenAI resources

Use ChatGPT

Source: Use ChatGPT

{/_ vale alex.Condescending = NO _/}

Go from idea to useful result

ChatGPT is an AI agent that you communicate with in natural language:

1. Start with a question, an idea, rough notes, a file, or a task you need to complete.

2. Ask ChatGPT to explain information, develop ideas, draft content, research a topic, analyze materials, or create something new.

3. Add the context and tools it needs, such as files, web search, projects, or plugins.

4. Review the result, correct the direction, and ask for changes. You don't need a perfect first prompt or special commands.

Choose how you want to work

Use Chat for a question or back-and-forth. Turn on Work in the switcher when you want ChatGPT to carry a larger task through to a reviewable result. Select Codex when you want developer views or more technical detail, especially for software development.

Use Chat to ask questions, brainstorm, draft or revise text, summarize files, compare options, or clarify a larger task. In Codex, point to New chat, then select Quick chat when that option is available.

When you need a finished, reviewable result, switch to Work and describe what it should include. See Get started with ChatGPT Work for example tasks, prompts, and best practices.

What ChatGPT Work can do

ChatGPT Work can plan a task, gather context, use tools, and carry the work through to a result you can review.

Ask it to:

• Research and analyze information. Search the web, browse websites, compare sources, read files, analyze data, and summarize findings.
• Use your files and tools. Bring in uploaded files, projects, memories, ChatGPT Library, and installed plugins. Plugins can provide connected information, reusable workflows, and supported actions.
• Create finished files. Draft and refine documents, presentations, spreadsheets, and PDF files. Review the result, ask for specific changes, and download the completed file.
• Create visual and interactive work. Generate or edit images, make interactive visualizations, and build or share websites and apps with Sites.
• Work across websites and apps. Use the browser to research and interact with websites. In the desktop app, use the Chrome extension, Computer Use, and appshots when those features are available.
• Run code and review technical work. Run code and shell commands, analyze data, inspect files, review code, and work with repositories your selected environment can access.
• Delegate and continue longer tasks. Split independent work across subagents, follow their progress, and keep long-running work active.
• Repeat useful workflows. Set up scheduled tasks for recurring work and use skills to reuse a workflow.
• Talk through a task. On supported plans in the desktop app, use ChatGPT Voice to start work, check progress, or change direction.

Features depend on your plan, platform, region, rollout, and workspace settings. Your workspace administrator can control access to ChatGPT Work, plugins, browser use, and network access. ChatGPT Work and Codex share usage limits.

Choose cloud or local work

On the web, ChatGPT Work runs in a managed cloud environment. In the desktop app, you may also be able to choose where a task runs:

• Cloud: Run work in an isolated hosted environment. A task can keep going after you close the desktop app and continue from the web or mobile app. Cloud work can use uploaded files, connected tools, and approved websites.
• Work locally: Use files, apps, or the browser on your computer. Local work is available in the desktop app when enabled for your account or workspace.

ChatGPT shows its progress and pauses when it needs information or approval. Review consequential actions before approving them, and check the final result before you use or share it.

Compare ChatGPT Work and Codex on desktop

ChatGPT Work and Codex have overlapping capabilities. If you prefer Codex, you can keep using it for research, documents, presentations, and other knowledge work. When both are available to you, the desktop app changes the interface and how the agent presents its work.

Detailed comparison

Talk to ChatGPT naturally

Write as if you were explaining the request to a helpful colleague. State what you want to accomplish, add the details that change the answer, and describe the format you need. Your first prompt is only a starting point—you can add context or refine the result with follow-up messages.

You can continue with simple directions such as:

• “Make this shorter.”
• “Give me three different approaches.”
• “What assumptions are you making?”
• “Ask me questions before you continue.”

Learn more about prompting, or take the AI Foundations course for guided practice.

Bring the right context into ChatGPT

Give ChatGPT the information, tools, and instructions that matter to the task. You don't need to provide everything—include the context that changes what a good result looks like.

Keep related work in a project

Projects help you organize ChatGPT around a topic, goal, or ongoing body of work. Keep related chats, files, and instructions in one project when the work will continue over time or depend on the same context. Learn more about projects.

Attach files

You can upload or attach documents, presentations, spreadsheets, PDF files, images, and data exports. Use them when you want ChatGPT to:

• Summarize or compare them.
• Find patterns or inconsistencies.
• Extract, clean, or reorganize information.
• Use them as source material for a new file.

When ChatGPT creates a file, open the preview and check its contents. You can then ask for changes without starting over. Learn more about working with files.

Connect tools with plugins

Plugins can connect ChatGPT to the tools and information you use for work, such as Google Drive, SharePoint, Salesforce, or Gong. Use them when a task depends on information outside the chat, actions in another system, or a repeatable workflow.

Plugin availability depends on your plan, workspace settings, and the plugin itself. Learn more about skills and plugins.

Make the result ready to use

Treat the first result as a draft you can inspect, challenge, and improve. A polished response can still be incomplete or wrong, so review the details that matter before you use or share it.

Check the work:

• Verify important numbers, names, dates, quotes, and claims.
• Open generated files and inspect every section, tab, slide, or page.
• Confirm that ChatGPT used the correct and most current source material.
• Look for missing information and unsupported assumptions.
• Ask for focused revisions when the result misses the goal.

Then ask ChatGPT to pressure-test the result:

• “What sources did you use for this?”
• “Cite the source for each major claim.”
• “What assumptions did you make?”
• “What information were you unable to access?”
• “What would change your recommendation?”
• “Check this result against the original files.”

If ChatGPT couldn't access a source or complete part of the task, ask it to say so plainly. An explicit gap is easier to address than a confident guess.

Legal, financial, medical, security, and other high-stakes decisions require appropriate expert review. Use ChatGPT to support informed judgment, not replace it.

Next steps

a]:min-w-0 [&>a]:no-underline"> [

  Start using ChatGPT with a guided first task.

](https://learn.chatgpt.com/docs/quickstart)

[

Write useful prompts for questions, finished work, and coding tasks.

](https://learn.chatgpt.com/docs/prompting)

[

  Set preferences and carry useful context across chats.

](https://learn.chatgpt.com/docs/personalize)

What's new

Source: What's new

This weekly digest highlights ChatGPT and Codex features that can change how you work, with examples and links to learn more. For every versioned update, bug fix, and minor improvement, see the Codex changelog.

July 27–31, 2026

Use GPT-5.6 Terra and Luna at lower rates

GPT-5.6 Terra now costs 20% less, and GPT-5.6 Luna costs 80% less. Input, cached input, and output rates decreased by the same proportions. The updated usage limits and rates make Terra a stronger fit for everyday work and Luna especially useful for focused coding and high-volume tasks.

Find useful context across your browser and open tabs

In the ChatGPT desktop app, the built-in browser can find pages from your browsing history or search Google directly from its address bar. ChatGPT can also search your browsing history when a task needs earlier context.

The Chrome extension lets you mention open tabs, bring selected page text into a side chat, ask questions about YouTube videos, or select Ask ChatGPT from a page's context menu. Review and approve requests to use browser history before ChatGPT includes that information in a task.

Review changes across repositories

When a local project contains more than one folder, the desktop app shows every repository and the lines changed in each one. Select Review to inspect their diffs together without switching between separate review views.

Refine generated images in your conversation

Open a generated image in the expanded viewer, then switch between Focused view and Canvas view. Add comments across images, select the versions you want to keep, and ask for targeted edits without leaving the chat. Learn more about image generation.

Find chats that need your attention

The desktop app's new Activity view brings together chats you recently engaged with and work that needs your attention. Select the bell in the sidebar to open the view.

Read the July 30 desktop release notes.

Connect partner tools with Sign in with ChatGPT

Sign in with ChatGPT is rolling out in beta to supported plugins and partner sites, beginning with Airtable, GitLab, HubSpot, Notion, Supabase, and Vercel. Use it to create or link a partner account with fewer steps, then start working with that service in ChatGPT or Codex.

Partners receive only your name, email address, and profile picture when available. Each plugin's requested access still requires a separate review and approval. Read the July 29 sign-in announcement.

Collaborate in a dedicated academic research workspace

ChatGPT for Academic Researchers offers eligible faculty and postdoctoral researchers 12 months of complimentary access to a dedicated ChatGPT workspace. Approved teams can include up to five verified researchers from the same institution and receive business data protections and ChatGPT Pro-level usage limits. Participants can use GPT-5.6 across ChatGPT, ChatGPT Work, and Codex for research and coding workflows.

The program covers ChatGPT access, not OpenAI API credits. Eligibility requires institutional verification and a qualifying research paper.

Continue Codex tasks more reliably on iOS

ChatGPT for iOS 1.2026.202 reconnects to tasks more reliably when you return to the app or unlock your device with Face ID. Voice conversations use your chosen ChatGPT voice and show usage-limit warnings, while the composer now suggests installed plugins and their skills consistently with the desktop app.

The release also improves pause and resume controls for goals, inline tables and visual themes, large workspace diffs, selected-text references, and model restoration. Read the July 27 iOS release notes.

Compare security scans and manage findings

Hosted Codex Security plugin releases 0.1.14 and 0.1.15 add scan comparisons, false-positive feedback, scoped SECURITY.md policies, and clearer repository and finding histories. You can select findings for tracking in Linear or GitHub Issues, with Codex reviewing the proposed action before you approve it.

Use the existing Codex Security workbench to review saved scans, findings, repository history, and remediation in the desktop app. The hosted plugin catalog offers version 0.1.15, while the public CLI plugin marketplace offers version 0.1.11. Check the Codex Security plugin changelog before relying on a new feature.

Run security scans from the terminal, CI, or TypeScript

The public @openai/codex-security CLI and TypeScript SDK reached version 0.1.5, with release numbers separate from the Codex Security plugin. Use the package to run scans from the CLI, review pull-request changes and upload SARIF results in CI, or run resumable bulk scans across GitHub repositories or a pinned CSV inventory.

The Codex Security TypeScript SDK also lets you build scanning, progress reporting, cost controls, and cancellation into your own tools. The package is public, but running scans still requires Codex Security access. Some full-repository scans also require Trusted Access for Cyber.

Organize sessions and extend Codex CLI 0.146.0

Codex CLI 0.146.0 lets you name a new chat with /new release prep or /clear bug bash, pin important threads, and switch between side conversations without closing them. It also adds temporary conversation forks, standalone web search for compatible custom model providers, executor-provided skills, and support for Agent Plugins manifests, workspace plugin publishing, and other plugin marketplaces.

For custom clients, the app server can filter pinned threads, create in-memory forks, inspect installed connector state, and read connector metadata. Experimental WebSocket support also connects app-server to remote Code Mode hosts. Review the app-server security requirements before exposing a remote connection. The release also improves proxy support, MCP reconnection, terminal responsiveness, and Windows sandbox reliability.

Use GPT-5.6 Sol for hosted Codex work

GPT-5.6 Sol now powers Codex cloud code review and quality assurance for eligible customers. Sol is the flagship GPT-5.6 model for complex coding, research, computer use, and security work. Codex cloud selects its model automatically; Terra and Luna remain available on supported local and web surfaces.

Prepare for the GPT-5.4 model retirement

On August 31, GPT-5.4 and GPT-5.4 mini will retire from Codex for users signed in with ChatGPT. Replace gpt-5.4 with gpt-5.6-terra and gpt-5.4-mini with gpt-5.6-luna in workspace defaults, saved model settings, managed configurations, custom agents, and scheduled tasks.

The OpenAI API and Codex sessions authenticated with an API key are not affected. Review the deprecated Codex models and workspace model availability before the cutoff.

July 20–24, 2026

Talk through work with ChatGPT Voice

ChatGPT Voice, powered by GPT-Live, lets you talk through work and coordinate tasks in Chat, Work, and Codex in the ChatGPT desktop app. Start a new chat or task in voice mode, then ask ChatGPT to start, check, or steer work in other threads.

On macOS, say, “Take a look at this” to share an appshot of your frontmost window when Screen context is on.

Voice is available with Plus, Pro, Business, Edu, and Enterprise plans in the desktop app and through Remote on iOS.

Work across multiple folders in one local project

Local projects in the ChatGPT desktop app can now include multiple related folders. Choose a primary folder for new chats, Git operations, and automatic discovery of AGENTS.md, skills, and config.toml. Secondary folders remain available for file search, reading, and editing.

Open Edit project to add folders and choose the primary folder.

Read the July 23 release notes.

July 13–17, 2026

Keep Work conversations and Projects together on desktop

The ChatGPT desktop app now keeps Chat and Work conversations together in the ChatGPT view. Cloud Work conversations sync across web, mobile, and desktop; local Work conversations stay on your computer. ChatGPT Projects are available in the desktop app. Codex keeps its dedicated view and separate history for developer workflows.

Compare ChatGPT Work and Codex on desktop to choose the view that fits your task.

Control parallel Codex work with Codex Micro

On July 15, OpenAI and Work Louder launched Codex Micro, a limited-run physical control surface for Codex in the ChatGPT desktop app. Its Agent Keys show the status of up to six chats and switch between them. Customizable Command Keys, an analog stick, and a dial can trigger common actions or skills, start push-to-talk, and adjust reasoning effort without leaving the keyboard.

Use GPT-5.6 through Amazon Bedrock

GPT-5.6 Sol, Terra, and Luna reached general availability through Amazon Bedrock. Local ChatGPT Work and Codex surfaces can use the built-in amazon-bedrock provider with a Bedrock API key or the AWS SDK credential chain. This includes Work and Codex in the ChatGPT desktop app, Codex CLI, the IDE extension, and the Codex SDK.

Inspect Codex task visualizations on iOS

ChatGPT for iOS 1.2026.188 added inline visualizations to Codex tasks and improved creating and managing tasks from conversations, including reliable links to newly created tasks. Read the July 13 iOS release notes.

July 6–10, 2026

Take on ambitious work in ChatGPT

ChatGPT Work in ChatGPT can gather context from your files and plugins, take action across workflows, and create reviewable documents, presentations, spreadsheets, Sites, and other finished work. Powered by GPT-5.6, it can break a goal into steps and work for hours while you follow its progress, answer questions, change direction, and approve important actions.

Scheduled tasks can keep that work moving when you're away by running once, on a schedule, when an event occurs, or while monitoring for changes.

Choose the right GPT-5.6 model

The GPT-5.6 family offers three recommended models across ChatGPT Work, the ChatGPT desktop app, Codex CLI, and the Codex IDE extension. Sol is the flagship for complex coding, computer use, research, and security work. Terra balances capability and cost for everyday work, while Luna is the fastest, lowest-cost option. The default Power setting uses Sol with medium reasoning.

Use Codex in the ChatGPT desktop app

On July 9, the Codex app merged into the ChatGPT desktop app for macOS and Windows. Codex keeps its dedicated coding experience alongside ChatGPT's Chat and Work. The Codex experience includes inline editing in diffs, pull request review in the side panel, faster Computer Use powered by GPT-5.6, and multi-repository projects.

Existing Codex app users can update as usual. You can make Codex the default view, use the Codex logo as the app icon, and access desktop Codex projects from the ChatGPT mobile app. The updated desktop app is available globally on every ChatGPT plan, including Free.

June 15–19, 2026

Turn demonstrated workflows into reusable skills

Record & Replay lets you show ChatGPT or Codex a workflow on macOS and turn the demonstration into a reusable skill. Use it for repetitive tasks that are easier to show than describe, then refine the generated skill and replay it with new inputs. Initial availability excludes the EEA, the United Kingdom, and Switzerland, and requires Computer Use.

Continue a chat on another host

Chat handoff moves a chat and its Git state between your local computer and a connected remote host. Codex can create or reuse a worktree on the destination, transfer the chat, and continue from the matching project.

The same desktop release adds bulk actions to scheduled run history, so you can mark every run as read or archive eligible runs together.

Browse and review workspaces from iOS

In the ChatGPT mobile app, Remote added a workspace file browser, a directory picker for new chats, expand-and-collapse controls for diffs, and per-chat or cross-chat MCP approval choices on iOS.

Computer Use, the Chrome extension, Memories, and Chronicle also began rolling out to the EEA, the United Kingdom, and Switzerland. Memories remain off by default in those regions, and Chronicle is an opt-in research preview for ChatGPT Pro subscribers on macOS.

Read the June 15 iOS, June 16 availability, and June 18 app release notes.

June 8–12, 2026

Debug web apps with Browser Developer mode

Developer mode gives Codex controlled access to Chrome DevTools Protocol capabilities in Chrome and the built-in browser. Codex can inspect network traffic, console output, runtime errors, and page state while it profiles or debugs your app. Under Developer mode in Settings > Browser, turn on Enable full CDP access. Codex asks for explicit approval before it uses that access on a website.

Browser use is also up to twice as fast because CDP and DOM snapshot optimizations reduce browser round trips.

Bring your setup to Codex

New migration flows can import supported setup from other coding agents during onboarding. The Codex app also added /init for creating project instructions, plus improved plugin management, browser diagnostics, and completed-chat summaries.

Set up Codex chats from iOS

Remote on iOS can now choose a branch, create a worktree, run an environment setup script, manage goals, and add inline review comments.

Read the June 9 app, June 9 iOS, and June 11 app release notes.

June 1–5, 2026

Build and deploy websites with Sites

Sites lets ChatGPT create, save, deploy, and inspect websites, dashboards, internal tools, web apps, and games hosted by OpenAI. Sites has a dedicated entry point in ChatGPT on the web and desktop, where you can return to projects and manage hosted environment values and secrets without assembling a separate deployment stack.

Use Codex with Amazon Bedrock

You can use Codex with Amazon Bedrock for local workflows with AWS-managed authentication, account controls, and billing. Remote on iOS also added an optional in-app lock, follow-up behavior settings, line wrapping for diffs, and SSH connections to Windows machines. The desktop app added terminal placement controls and activity insights in the profile view.

Read all June 2026 release notes.

May 25–29, 2026

Use Windows apps and control Codex remotely

Computer use added support for seeing, clicking, and typing in Windows desktop apps. Install the Computer Use plugin before starting. On Windows, Codex uses the active desktop and takes over the foreground while the task runs. Remote connections also support Windows. In the ChatGPT mobile app, open Remote to start work on a Windows device, or use a Mac running the ChatGPT desktop app and check progress from elsewhere.

Remote on iOS also added Spotlight and Shortcuts entry points, archived-chat browsing, /side, and options to save or copy rendered images. The desktop app added chat coordination for local projects and worktrees, content and branch-name search for past chats, and consistent visual identifiers for background subagents.

Read the May 25 iOS and May 29 app release notes.

May 18–22, 2026

Give Codex context from any Mac app with Appshots

Appshots send the frontmost app window to Codex with a screenshot and available text when you press both Command keys. Codex gets working context from design tools, dashboards, documents, and other apps without requiring you to copy, paste, or describe what's on screen.

Follow long-running goals

Goal mode left experimental status and is available in the Codex app, IDE extension, and CLI for objectives that can take hours or days. Locked use lets Codex continue approved computer-use work after a Mac locks, including through Remote in the ChatGPT mobile app. ChatGPT Business workspaces can also share reusable plugin bundles with workspace members.

Read the May 21 launch notes.

May 11–15, 2026

Continue desktop work from mobile

In the ChatGPT mobile app, Remote connects to a Mac running the ChatGPT desktop app. Because work runs on the connected host, your projects, files, credentials, plugins, skills, and configuration remain available when you continue from your phone. See Remote connections to set up a host and pick up work from another device.

Automate trusted workflows

Hooks reached general availability for running custom commands at key points in the agent lifecycle. ChatGPT Enterprise admins can also enable Codex access tokens for trusted scripts, schedulers, and private CI runners. Enterprise guidance expanded to cover managed setup and controls for Codex.

Read the May 14 launch notes.

May 4–8, 2026

Work across browser tabs with the Chrome extension

The Chrome extension can work in parallel across tabs in the background without taking over your browser. You control which websites Codex can use, making it practical to combine research, data entry, and verification across web apps in one task.

The Codex app also added dictation cleanup and a custom dictionary for names, file paths, and code symbols. ChatGPT Enterprise workspace owners can allow members to create Codex access tokens for trusted, non-interactive local workflows.

Read the May 5 app, May 5 access-token, and Codex for Chrome launch notes.

April 20–24, 2026

Use GPT-5.5 for complex work

GPT-5.5 arrived in Codex as the recommended model for most tasks, with strengths across implementation, debugging, testing, computer use, research, and finished knowledge-work outputs.

Let Codex operate the browser and review approvals

Computer Use in the built-in browser lets Codex click through local development servers and file-backed pages to reproduce issues and verify fixes. Eligible approval requests can also go through automatic approval review, which shows the review status and risk before the action runs.

Read the April 23 launch notes.

April 13–17, 2026

Preview and operate work in one place

The built-in browser added live previews and page comments, while Computer Use let Codex see and operate macOS apps. Together, they made visual implementation and end-to-end verification part of the same task as the code change.

Start with a chat and keep it moving

Standalone chats made it possible to begin without choosing a project folder. The same release added scheduled tasks inside a chat, pull-request context, richer file previews, and Memories for work that spans chats.

Read the April 16 Codex app release notes.

April 6–10, 2026

Review and ship pull requests in the app

The review experience added collapsible inline comments, inline and detached review modes, and clearer Git and source context. Pull-request activity, comments, and push choices then moved into the app alongside workspace file tabs, so you could inspect a change and respond without switching tools.

Read the April 9 and April 10 Codex app release notes, or learn how to review changes in the app.

March 23–27, 2026

Package workflows as plugins

Plugins launched as installable bundles of skills, connectors, and MCP servers. They made complete workflows easier to discover, install, and share, while redesigned plugin and skill pages made their contents and status clearer. Search for past chats also arrived that week.

Read the task search, plugins launch, and Codex app release notes.

March 16–20, 2026

Branch earlier and choose tools from the composer

You could fork a chat from an earlier message, making it easier to try a new approach without losing the original path. Model and reasoning commands became available while drafting, enabled skills appeared in the @ menu, and GPT-5.4 mini added a faster option for lighter tasks and subagents.

Read the GPT-5.4 mini, chat control, and skill menu release notes.

March 9–13, 2026

Schedule work with the right environment

Scheduled tasks could run locally or in a worktree with an explicit model and reasoning level. Reusable templates made common tasks faster to configure, and custom themes made the workspace easier to personalize.

Let Codex inspect terminal output

Codex also learned to read the integrated terminal for the current chat. It could inspect a running development server or build output directly instead of asking you to paste it.

Read the March 11 and March 12 Codex app release notes.

March 2–6, 2026

Run Codex natively on Windows

The Codex app launched on Windows with native PowerShell and sandbox support, plus worktrees, scheduled tasks, and skills. WSL remained available for developers who preferred a Linux environment.

Move chats between Local and Worktree

Local and Worktree handoff made it possible to move an active chat while preserving its context. GPT-5.4 also arrived in Codex that week for coding, computer use, and longer-context workflows.

Read the Windows launch, worktree handoff, and GPT-5.4 release notes.

February 9–13, 2026

Iterate in real time and branch an approach

GPT-5.3-Codex-Spark entered research preview as a near-instant model for real-time coding iteration. The app also added chat forking and a floating, always-on-top chat window, so you could explore another approach or keep Codex beside an editor or browser.

Read the Spark and Codex app release notes, or see the current model guide.

February 2–6, 2026

The Codex app launches on macOS

The Codex app launched as a desktop workspace for parallel project chats, built-in Git review, worktrees, skills, scheduled tasks, and voice dictation. Those capabilities now live in Codex in the ChatGPT desktop app.

Steer active work and add files

Mid-turn steering made it possible to redirect Codex without stopping an active response, and file attachments expanded beyond images. These patterns became the foundation for steering and queuing follow-ups with the context Codex needs.

Read the Codex app launch notes and February 5 app release notes.

ChatGPT

Source: ChatGPT

Use ChatGPT for ambitious work and software development

Feature Maturity

Source: Feature Maturity

Some ChatGPT and Codex features ship behind a maturity label so you can understand how reliable each one is, what might change, and what level of support to expect.

Pricing

Source: Pricing

ChatGPT Work and Codex share usage. ChatGPT Work usage inside ChatGPT uses the same pricing, credits, and usage limits as Codex.

Pricing options

Free ($0 /month):

Explore Codex capabilities on quick coding tasks.

Get Free

Go ($8 /month):

Use Codex for lightweight coding tasks.

Get Go

Plus ($20 /month):

Power a few focused coding sessions each week.

• Codex on the web, in the CLI, in the IDE extension, and on iOS
• Cloud-based integrations like automatic code review and Slack integration
• The GPT-5.6 model family, including Sol, Terra, and Luna
• GPT-5.6 Luna for higher usage limits on lighter-weight or high-volume workloads
• Flexibly extend usage with ChatGPT credits
• Other ChatGPT features as part of the Plus plan

Get Plus

Pro (From $100 /month):

Choose 5x or 20x higher rate limits than Plus.

Everything in Plus and:

• Access to GPT-5.3-Codex-Spark (research preview), a fast Codex model for day-to-day coding tasks
• 5x or 20x more Codex usage than Plus*
• Unlimited ChatGPT Voice on the $200/month tier; tasks still draw from your Codex usage budget
• Other ChatGPT features as part of the Pro plan

Get Pro

*Learn more about limits on both tiers.

API Key:

Great for automation in shared environments like CI.

• Codex in the CLI, SDK, or IDE extension
• No cloud-based features (GitHub code review, Slack, etc.)
• Model availability follows the API models available to your key
• Pay only for the tokens Codex uses, based on API pricing

Learn more

Business ($20 / user / month*):

Bring Codex into your startup or growing business.

• Access ChatGPT and Codex across desktop and mobile apps
• Larger virtual machines to run cloud chats faster
• Flexibly extend usage with ChatGPT credits
• A secure, dedicated workspace with essential admin controls, SAML SSO, and MFA
• No training on your business data by default. Learn more
• Other ChatGPT features as part of the Business plan

Get Business

*2+ users, billed annually. $25 per user per month when billed monthly.

Enterprise & Edu:

Unlock Codex for your entire organization with enterprise-grade functionality.

Everything in Business and:

• Priority request processing
• Enterprise-level security and controls, including SCIM, EKM, user analytics, domain verification, and role-based access control (RBAC)
• Audit logs and usage monitoring via the Compliance API
• Data retention and data residency controls
• Other ChatGPT features as part of the Enterprise plan

Contact sales

Invite friends and coworkers

Eligible users can send Codex invitations from the profile menu in the lower-left corner of the app. Choose Invite a friend on an eligible personal plan or Invite a coworker in an eligible Business workspace, enter the recipient's email address, and send the invitation.

The invitation dialog shows the current reward, recipient requirements, invite limits, and when rewards expire for your plan or promotion. Personal and Business referral programs have separate rewards and eligibility rules. Referrals aren't currently available for ChatGPT Enterprise.

From June 11 through June 24, 2026, eligible Plus and Pro users can invite up to three friends. When an eligible recipient sends their first Codex message, both people receive a banked rate-limit reset. Banked rate-limit resets are usable for 30 days after they're granted. Business referrals use separate shared-workspace credit rewards; review the current terms before you send an invitation.

Frequently asked questions

How much does Sites cost?

Sites is included with eligible ChatGPT plans during public beta. Availability depends on your plan, region, and workspace settings.

What are the usage limits for my plan?

The number of messages you can send depends on the model used, size and complexity of your tasks, and whether you run them locally or in the cloud. Small scripts or routine functions may consume only a fraction of your allowance, while larger projects, long-running tasks, or extended sessions that require the agent to hold more context will use significantly more per message.

Tasks that look similar can consume different amounts of your allowance. Model choice, context, reasoning, tool use, retrieval, and caching all affect usage, so prompt length alone isn't a reliable estimate.

Choose the GPT-5.6 model that best fits your work:

• Sol is built for the hardest work—complex reasoning, ambiguous problems, advanced coding, and high-stakes decisions.

• Terra is the everyday workhorse for production tasks, reporting, document analysis, coding, and work that requires sound judgment.

• Luna is optimized for fast, high-volume work such as routing, classification, extraction, support, background automation, and focused coding tasks.

  Plus
  
          Local Messages[\*](#shared-limits-plus) / 5h
  
          Cloud chats[\*](#shared-limits-plus) / 5h
  
          Code Reviews / 5h
  
        GPT-5.6 Sol
        10-100
        Not available
        Not available
  
        GPT-5.6 Terra
        25-200
        Not available
        Not available
  
        GPT-5.6 Luna
        250-2,000
        Not available
        Not available
  
        GPT-5.5
        15-80
        Not available
        Not available
  
        GPT-5.4
        20-100
        Not available
        Not available
  
        GPT-5.4 mini
        60-350
        Not available
        Not available
  
            *The usage limits for local messages and cloud chats share a
            **five-hour window**. Additional weekly limits may apply.
  
          For Enterprise/Edu users with flexible pricing, there are no
          fixed rate limits - usage scales with
          [credits](#credits-overview)
  
          Enterprise and Edu plans without flexible pricing have the same
          per-seat usage limits as Plus for most features
  
  Pro 5x
  
          Local Messages[\*](#shared-limits-pro) / 5h
  
          Cloud chats[\*](#shared-limits-pro) / 5h
  
          Code Reviews / 5h
  
        GPT-5.6 Sol
        50-500
        Not available
        Not available
  
        GPT-5.6 Terra
        125-1,000
        Not available
        Not available
  
        GPT-5.6 Luna
        1,250-10,000
        Not available
        Not available
  
        GPT-5.5
        75-400
        Not available
        Not available
  
        GPT-5.4
        100-500
        Not available
        Not available
  
        GPT-5.4 mini
        300-1750
        Not available
        Not available
  
            *The usage limits for local messages and cloud chats share a
            **five-hour window**. Additional weekly limits may apply.
  
          For Enterprise/Edu users with flexible pricing, there are no
          fixed rate limits - usage scales with
          [credits](#credits-overview)
  
          Enterprise and Edu plans without flexible pricing have the same
          per-seat usage limits as Plus for most features
  
  Pro 20x
  
          Local Messages[\*](#shared-limits-pro-20x) / 5h
  
          Cloud chats[\*](#shared-limits-pro-20x) / 5h
  
          Code Reviews / 5h
  
        GPT-5.6 Sol
        200-2,000
        Not available
        Not available
  
        GPT-5.6 Terra
        500-4,000
        Not available
        Not available
  
        GPT-5.6 Luna
        5,000-40,000
        Not available
        Not available
  
        GPT-5.5
        300-1600
        Not available
        Not available
  
        GPT-5.4
        400-2000
        Not available
        Not available
  
        GPT-5.4 mini
        1200-7000
        Not available
        Not available
  
            *The usage limits for local messages and cloud chats share a
            **five-hour window**. Additional weekly limits may apply.
  
          For Enterprise/Edu users with flexible pricing, there are no
          fixed rate limits - usage scales with
          [credits](#credits-overview)
  
          Enterprise and Edu plans without flexible pricing have the same
          per-seat usage limits as Plus for most features
  
  Business
  
          Local Messages[\*](#shared-limits-business) / 5h
  
          Cloud chats[\*](#shared-limits-business) / 5h
  
          Code Reviews / 5h
  
        GPT-5.6 Sol
        10-100
        Not available
        Not available
  
        GPT-5.6 Terra
        25-200
        Not available
        Not available
  
        GPT-5.6 Luna
        250-2,000
        Not available
        Not available
  
        GPT-5.5
        15-80
        Not available
        Not available
  
        GPT-5.4
        20-100
        Not available
        Not available
  
        GPT-5.4 mini
        60-350
        Not available
        Not available
  
            *The usage limits for local messages and cloud chats share a
            **five-hour window**. Additional weekly limits may apply.
  
          For Enterprise/Edu users with flexible pricing, there are no
          fixed rate limits - usage scales with
          [credits](#credits-overview)
  
          Enterprise and Edu plans without flexible pricing have the same
          per-seat usage limits as Plus for most features
  
  API Key
  
          Local Messages[\*](#shared-limits-api-key) / 5h
  
          Cloud chats[\*](#shared-limits-api-key) / 5h
  
          Code Reviews / 5h
  
        GPT-5.6 Sol
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
        GPT-5.6 Terra
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
        GPT-5.6 Luna
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
        GPT-5.5
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
        GPT-5.4
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
        GPT-5.4 mini
  
          [Usage-based](https://platform.openai.com/docs/pricing)
  
        Not available
        Not available
  
            *The usage limits for local messages and cloud chats share a
            **five-hour window**. Additional weekly limits may apply.
  
          For Enterprise/Edu users with flexible pricing, there are no
          fixed rate limits - usage scales with
          [credits](#credits-overview)
  
          Enterprise and Edu plans without flexible pricing have the same
          per-seat usage limits as Plus for most features
  

Usage limits are shared with other agentic features once pricing for those features is effective. This currently includes ChatGPT for Excel on Plus and Pro.

Speed configurations increase credit consumption for all applicable models, so they also use included limits faster. Fast mode consumes credits at a higher rate for supported models. See Speed for supported models and rates. Image generations also use included limits ~3-5x faster on average, depending on image quality and size. GPT-5.3-Codex-Spark is in research preview for ChatGPT Pro users only, and isn't available in the API at launch. Because it runs on specialized low-latency hardware, usage is governed by a separate usage limit that may adjust based on demand.

ChatGPT Voice in Desktop

ChatGPT Voice on desktop uses a separate, plan-dependent allowance measured in rolling five-hour windows. Tasks started through Voice use your existing Codex usage budget. ChatGPT notifies you when you reach either limit.

ChatGPT Voice in Desktop uses a duplex model: GPT-Live manages the live conversation, while GPT-5.6 Terra starts and coordinates tasks in the app.

• Plus: Approximately 15–30 minutes
• Pro 5x ($100/month): Approximately 1–2.5 hours
• Pro 20x ($200/month): Unlimited voice access
• Business: Approximately 45 minutes
• Enterprise / Edu (legacy): Approximately 45 minutes

Unlimited voice access doesn't make Codex tasks unlimited. Tasks started through ChatGPT Voice continue to use your existing Codex usage budget.

For Business, Edu, and Enterprise workspaces with credit-based or pay-as-you-go billing, Desktop voice costs approximately 6 credits per minute. ChatGPT Voice in Desktop is not available via API Key currently.

What happens when you hit usage limits?

We want you to be able to complete work already in progress. If you reach your usage limits during an active turn, the agent will be able to continue working on that turn, subject to fair use limits.

ChatGPT Plus and Pro users who reach their usage limit can purchase additional credits to continue working without needing to upgrade their existing plan.

Business, Edu, and Enterprise plans with flexible pricing can purchase additional workspace credits to continue working.

If you are approaching usage limits, you can also switch to a smaller model to make your usage limits last longer.

All users may also run extra local chats using an API key, with usage charged at standard API rates.

How does image generation count toward usage limits?

Image generation counts toward the same general usage limits as local messages and cloud chats. Image generations use included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. After you reach your included limits, image generation also draws from credits.

Image generation isn't available on the Free plan. When you use Codex with an API key, API pricing applies to image generation instead of included ChatGPT usage limits.

Where can I see my current usage limits?

You can find your current limits in the usage dashboard. If you want to see your remaining limits during an active Codex CLI session, you can use /status.

Check the dashboard every week or two to understand your pace and remaining capacity. If usage is higher than expected, consider whether a smaller model or tighter task scope would still produce a useful result.

What are tokens and credits?

Tokens are small units of information that ChatGPT reads and writes. Your prompt, files, chat history, tool results, and ChatGPT's response all use tokens.

Credits translate token usage into a simpler unit for tracking and managing consumption. The credit cost varies by model, context, reasoning, and tools. After you reach your included limits, available credits let you continue working.

Usage is calculated in credits per million input tokens, cached input tokens, and output tokens. Learn more about tokens.

The rate card below shows the credit cost per million tokens for models and features.

A small subset of Enterprise customers should continue using the legacy rate card until we migrate you to the new token-based pricing. For more information, contact OpenAI sales.

    Credits per 1M tokens

      Input Tokens

      Cached input tokens

      Output Tokens

    GPT-5.6 Sol
    125 credits
    12.5 credits
    750 credits

    GPT-5.6 Terra
    50 credits
    5 credits
    300 credits

    GPT-5.6 Luna
    5 credits
    0.5 credits
    30 credits

    GPT-5.5
    125 credits
    12.50 credits
    750 credits

    GPT-5.4
    62.50 credits
    6.250 credits
    375 credits

    GPT-5.4 mini
    18.75 credits
    1.875 credits
    113 credits

    GPT-5.3-Codex-Spark

      research preview

    GPT-Image-2 (image)
    200 credits
    50 credits
    750 credits

    GPT-Image-2 (text)
    125 credits
    31.25 credits
    250 credits

      GPT-5.6 usage averages 5-40 credits per message.

      Fast mode consumes credits at a higher rate for supported models. See
      Speed for rates.

Speed configurations will increase credit consumption for all models that apply. Fast mode consumes credits at a higher rate for supported models. See Speed for supported models and rates.

Learn more about credits in ChatGPT Plus and Pro.

Learn more about credits in ChatGPT Business, Enterprise, and Edu.

What counts as Code Review usage?

Code Review usage applies only when Codex runs reviews through GitHub—for example, when you tag @Codex for review in a pull request or enable automatic reviews on your repository. Reviews run locally or outside of GitHub count toward your general usage limits.

What can I do to make my usage limits last longer?

The usage limits and credits above are average rates. You can try the following tips to maximize your limits:

• Control the size of your prompts. Be precise with the instructions you give the agent, but remove unnecessary context.
• Limit source material. Provide only relevant files and, when possible, narrow the sources or date range.
• Match the output to the need. Define the audience, format, and length, and separate required work from optional improvements.
• Reduce the size of your AGENTS.md. If you work on a larger project, you can control how much context you inject through AGENTS.md files by nesting them within your repository.
• Limit the number of MCP servers you use. Every MCP server adds more context to your messages and uses more of your limit. Disable MCP servers when you don’t need them.
• Switch to a smaller model for routine tasks. Using GPT-5.6 Terra or GPT-5.6 Luna can extend your local-message usage limits, depending on the model you switch from.

For guidance on choosing and scoping tasks, see Use Work efficiently.

Feature availability

• Feature is currently limited to only specific regions. Check the individual feature documentation to learn more about geo restrictions.

  † Some first party plugins are not available.

Quickstart

Source: Quickstart

Where to use ChatGPT

Use ChatGPT across different surfaces, including the ChatGPT desktop app and ChatGPT on the web. Choose the option that fits your work.

If you're a developer and want to use Codex in your terminal or code editor, try Codex CLI or the Codex IDE extension.

Setup

{/_ prettier-ignore _/}

The ChatGPT desktop app is available for Windows and macOS. Use it for projects, local files, longer tasks, and quick chats.

1. Install the ChatGPT desktop app

   Choose the version for your operating system: 2. Open the ChatGPT desktop app and sign in

   Open the app, then sign in with your ChatGPT account.

   You may also use Codex with an API key. Some features might not be available.

2. Select where ChatGPT should work

   Start a chat, create a project, or open a folder. ChatGPT can read and modify files in the folder you choose. Learn more about chats and projects.

3. Start a chat

           - For research, analysis, or deliverables such as documents, presentations,
             spreadsheets, and Sites, select **ChatGPT**, then switch to **Work** at the
             top of the new chat page, above the composer.
           - For software development with codebase context and developer tools, select
             **Codex** from the ChatGPT dropdown.
           - For a quick question or chat, select **ChatGPT**, then select **Chat**
             in the switcher at the top of the new chat page, above the composer. In
             Codex, point to **New chat**, then select the **Quick chat** icon on its right.
   
           Learn more about [using ChatGPT](https://learn.chatgpt.com/docs/use-chatgpt).
   

4. Send your first message

   Describe your goal and add any files or context ChatGPT needs. Try an example:

   Explore more use cases.

ChatGPT is available on the web and includes Chat and ChatGPT Work.

1. Open ChatGPT and sign in

Go to chatgpt.com and sign in with your ChatGPT account.

2. Start a chat

           - Select **Chat** to ask questions, explore ideas, and work through a topic
             conversationally.
           - Select **Work** to research, analyze information, and create documents,
             presentations, spreadsheets, Sites, or other finished work.
   
           Learn more about [using ChatGPT](https://learn.chatgpt.com/docs/use-chatgpt).
   

3. Select where ChatGPT should work

   Start a chat or select a project. Projects can include chats, files, and instructions.

4. Send your first message

   Describe your goal and add any files or context ChatGPT needs. Try an example:

Next steps

[

Use the ChatGPT desktop app to work with your local projects.

](https://learn.chatgpt.com/docs/app) [

Bring supported setup, projects, and recent work into ChatGPT.

](https://learn.chatgpt.com/docs/import)

Execution Model and Workflows

How Codex reasons through work, tasks, prompting, speed, and multi-agent coordination.

Best practices

Source: Best practices

If you’re new to Codex or coding agents in general, this guide will help you get better results faster. It covers the core habits that make Codex more effective across the CLI, IDE extension, and the ChatGPT desktop app, from prompting and planning to validation, MCP, skills, and scheduled tasks.

Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time.

A useful way to think about this: start with the right context for the task, use AGENTS.md for durable guidance, configure Codex to match your workflow, connect external systems with MCP, turn repeated work into skills, and automate stable workflows.

Strong first use: Context and prompts

Codex is already strong enough to be useful even when your prompt isn't perfect. You can often hand it a hard problem with minimal setup and still get a strong result. Clear prompting isn't required to get value, but it does make results more reliable, especially in larger codebases or higher-stakes tasks.

If you work in a large or complex repository, the biggest unlock is giving Codex the right context for the task and a clear structure for what you want done.

A good default is to include four things in your prompt:

• Goal: What are you trying to change or build?
• Context: Which files, folders, docs, examples, or errors matter for this task? You can @ mention certain files as context.
• Constraints: What standards, architecture, safety requirements, or conventions should Codex follow?
• Done when: What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?

This helps Codex stay scoped, make fewer assumptions, and produce work that's easier to review.

Choose a reasoning level based on how hard the task is and test what works best for your workflow. Different users and tasks work best with different settings.

• Low for faster, well-scoped tasks
• Medium or High for more complex changes or debugging
• Extra High for long, agentic, reasoning-heavy tasks

To provide context faster, try using speech dictation inside the ChatGPT desktop app to dictate what you want Codex to do rather than typing it.

Plan first for difficult tasks

If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.

A few approaches work well:

Use Plan mode: For most users, this is the easiest and most effective option. Plan mode lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation. Toggle with /plan or Shift+Tab.

Ask Codex to interview you: If you have a rough idea of what you want but aren't sure how to describe it well, ask Codex to question you first. Tell it to challenge your assumptions and turn the fuzzy idea into something concrete before writing code.

Use a PLANS.md template: For more advanced workflows, you can configure Codex to follow a PLANS.md or execution-plan template for longer-running or multi-step work. For more detail, see the execution plans guide.

Make guidance reusable with AGENTS.md

Once a prompting pattern works, the next step is to stop repeating it manually. That's where AGENTS.md comes in.

Think of AGENTS.md as an open-format README for agents. It loads into context automatically and is the best place to encode how you and your team want Codex to work in a repository.

A good AGENTS.md covers:

• repo layout and important directories
• How to run the project
• Build, test, and lint commands
• Engineering conventions and PR expectations
• Constraints and do-not rules
• What done means and how to verify work

The /init slash command in the CLI is the quick-start command to scaffold a starter AGENTS.md in the current directory. It's a great starting point, but you should edit the result to match how your team actually builds, tests, reviews, and ships code.

You can create AGENTS.md files at different levels: a global AGENTS.md for personal defaults that sits in ~/.codex, a repo-level file for shared standards, and more specific files in subdirectories for local rules. If there’s a more specific file closer to your current directory, that guidance wins.

Keep it practical. A short, accurate AGENTS.md is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.

If AGENTS.md starts getting too large, keep the main file concise and reference task-specific markdown files for things like planning, code review, or architecture.

When Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md. Guidance stays practical and based on real friction.

Configure Codex for consistency

Configuration is one of the main ways to make Codex behave more consistently across sessions and surfaces. For example, you can set defaults for model choice, reasoning effort, sandbox mode, approval policy, profiles, and MCP setup.

A good starting pattern is:

• Keep personal defaults in ~/.codex/config.toml (Settings > Configuration > Open config.toml in the ChatGPT desktop app)
• Keep repo-specific behavior in .codex/config.toml
• Use command-line overrides only for one-off situations (if you use the CLI)

config.toml is where you define durable preferences such as MCP servers, multi-agent setup, and feature flags. Profile-specific overrides live in separate $CODEX_HOME/profile-name.config.toml files.

Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

If you're new to coding agents, start with the default permissions. Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear.

Note that the CLI, IDE extension, and ChatGPT desktop app all share the same configuration layers. Learn more on the sample configuration page.

Configure Codex for your real environment early. Many quality issues are really setup issues, like the wrong working directory, missing write access, wrong model defaults, or missing tools and connectors.

Improve reliability with testing and review

Don't stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.

Codex can do this loop for you, but only if it knows what “good” looks like. That guidance can come from either the prompt or AGENTS.md.

That can include:

• Writing or updating tests for the change
• Running the right test suites
• Checking lint, formatting, or type checks
• Confirming the final behavior matches the request
• Reviewing the diff for bugs, regressions, or risky patterns

Toggle the diff panel in the ChatGPT desktop app to directly review changes locally. Click on a specific row to provide feedback that gets fed as context to the next Codex turn.

A useful option here is the slash command /review, which gives you a few ways to review code:

• Review against a base branch for PR-style review
• Review uncommitted changes
• Review a commit
• Use custom review instructions

If you and your team have a code_review.md file and reference it from AGENTS.md, Codex can follow that guidance during review as well. This is a strong pattern for teams that want review behavior to stay consistent across repositories and contributors.

Codex shouldn't just generate code. With the right instructions, it can also help test it, check it, and review it.

If you use GitHub Cloud, you can set up Codex to run code reviews for your PRs. At OpenAI, Codex reviews 100% of PRs. You can enable automatic reviews or have Codex reactively review when you @Codex.

Use MCPs for external context

Use MCPs when the context Codex needs lives outside the repo. It lets Codex connect to the tools and systems you already use, so you don't have to keep copying and pasting live information into prompts.

Model Context Protocol, or MCP, is an open standard for connecting Codex to external tools and systems.

Use MCP when:

• The needed context lives outside the repo
• The data changes frequently
• You want Codex to use a tool rather than rely on pasted instructions
• You need a repeatable integration across users or projects

Codex supports both STDIO and Streamable HTTP servers with OAuth.

In the ChatGPT desktop app, go to Settings > MCP servers to see custom and recommended servers. Often, Codex can help you install the needed servers. All you need to do is ask. You can also use the codex mcp add command in the CLI to add your custom servers with a name, URL, and other details.

Add tools only when they unlock a real workflow. Do not start by wiring in every tool you use. Start with one or two tools that clearly remove a manual loop you already do often, then expand from there.

Turn repeatable work into skills

Once a workflow becomes repeatable, stop relying on long prompts or repeated back-and-forth. Use a skill to package the instructions in a SKILL.md file, context, and supporting logic Codex should apply consistently. Skills work across the CLI, IDE extension, and ChatGPT desktop app.

Keep each skill scoped to one job. Start with 2 to 3 concrete use cases, define clear inputs and outputs, and write the description so it says what the skill does and when to use it. Include the kinds of trigger phrases a user would actually say.

Don't try to cover every edge case up front. Start with one representative task, get it working well, then turn that workflow into a skill and improve from there. Include scripts or extra assets only when they improve reliability.

A good rule of thumb: if you keep reusing the same prompt or correcting the same workflow, it should probably become a skill.

Skills are especially useful for recurring jobs like:

• Log triage
• Release note drafting
• PR review against a checklist
• Migration planning
• Telemetry or incident summaries
• Standard debugging flows

The $skill-creator skill is the best place to start to scaffold the first version of a skill. Keep the first version local while you iterate. When it's ready to share broadly, package it as a plugin. One of the most important parts of a skill is the description. It should say what the skill does and when to use it.

Personal skills are stored in $HOME/.agents/skills, and shared team skills can be checked into .agents/skills inside a repository. This is especially helpful for onboarding new teammates.

Use scheduled tasks for repeated work

Once a workflow is stable, you can schedule Codex to run it in the background for you. In the ChatGPT desktop app, scheduled tasks let you choose the project, prompt, cadence, and execution environment for recurring work.

Create a scheduled task from the Scheduled page. Choose the project, prompt, cadence, and whether the task runs in a dedicated Git worktree or in your local environment. The prompt can invoke skills. Learn more about Git worktrees.

Good candidates include:

• Summarizing recent commits
• Scanning for likely bugs
• Drafting release notes
• Checking CI failures
• Producing standup summaries
• Running repeatable analysis workflows on a schedule

A useful rule is that skills define the method and scheduled tasks define the schedule. If a workflow still needs a lot of steering, turn it into a skill first. Once it's predictable, scheduling it can save time.

Use scheduled tasks for reflection and maintenance, not just execution. Review recent chats, summarize repeated friction, and improve prompts, instructions, or workflow setup over time.

Organize long-running chats

Chats accumulate context, decisions, and actions over time, so managing them well has a big impact on quality.

The ChatGPT desktop app lets you pin chats and create worktrees. If you use the CLI, these slash commands are especially useful:

• /experimental to toggle experimental features and add to your config.toml
• /resume to resume a saved chat
• /fork to create a new chat while preserving the original transcript
• /compact when the chat is getting long and you want a summarized version of earlier context. Codex also compacts chats automatically
• /agent when you are running parallel agents and want to switch between the active agent thread
• /theme to choose a syntax highlighting theme
• /apps to use ChatGPT apps directly in Codex
• /status to inspect the current session state

Keep one chat per coherent unit of work. If the work is still part of the same problem, staying in the same chat is often better because it preserves the reasoning trail. Fork only when the work truly branches.

Use Codex’s subagent workflows to offload bounded work from the main thread. Keep the main agent focused on the core problem, and use subagents for tasks like exploration, tests, or triage.

Common mistakes

A few common mistakes to avoid when first using Codex:

• Overloading the prompt with durable rules instead of moving them into AGENTS.md or a skill
• Not letting the agent see its work by not giving details on how to best run build and test commands
• Skipping planning on multi-step and complex tasks
• Giving Codex full permission to your computer before you understand the workflow
• Running live tasks on the same files without using Git worktrees
• Scheduling a recurring task before it's reliable manually
• Treating Codex like something you have to watch step by step instead of using it in parallel with your own work
• Using one chat for an entire project instead of one chat per coherent outcome. This leads to bloated context and worse results over time

Multi-agent operations

Source: Subagents

ChatGPT Work and Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.

In local Codex clients, you can also define custom agents with different model configurations and instructions for different tasks.

Availability

ChatGPT Work exposes subagent workflows and activity to eligible accounts.

Current Codex releases enable subagent workflows by default. Subagent activity appears in the ChatGPT desktop app, Codex CLI, and the IDE extension.

Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.

In ChatGPT Work, ask ChatGPT to delegate independent work to subagents. The agents run in ChatGPT's hosted environment, and the chat shows their activity and results. At most intelligence levels, ask for delegation explicitly. With Ultra, ChatGPT can proactively delegate work when parallel agents would materially improve speed or quality.

Ask Codex in an app chat to delegate independent parts of the work to subagents. Current local Codex releases delegate when you ask directly or when applicable AGENTS.md or skill instructions request it. The app surfaces each subagent thread so you can inspect its work and the summary returned to the main chat.

Ask Codex in an interactive CLI session to use subagents. Codex can also follow applicable AGENTS.md or skill instructions that request delegation. Use /agent to inspect and switch between agent threads while they run. The main thread collects the subagent results into its final response.

Ask Codex in an IDE chat to delegate independent parts of the work to subagents. Codex can also follow applicable AGENTS.md or skill instructions that request delegation. When the background-agent UI is available, active subagents appear above the composer. Expand the panel to see their status, stop all active subagents, or open an individual subagent thread.

Why subagent workflows help

Even with large context windows, models have limits. If you flood the main chat (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

This is often described as:

• Context pollution: useful information gets buried under noisy intermediate output.
• Context rot: performance degrades as the chat fills up with less relevant details.

For background, see the Chroma writeup on context rot.

Subagent workflows help by moving noisy work off the main thread:

• Keep the main agent focused on requirements, decisions, and final outputs.
• Run specialized subagents in parallel for exploration, tests, or log analysis.
• Return summaries from subagents instead of raw intermediate output.

They can also save time when the work can run independently in parallel, and they make larger-shaped tasks more tractable by breaking them into bounded pieces. For example, Codex can split analysis of a multi-million-token document into smaller problems and return distilled takeaways to the main thread.

As a starting point, use parallel agents for read-heavy tasks such as exploration, tests, triage, and summarization. Be more careful with parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead.

Core terms

Codex uses a few related terms in subagent workflows:

• Subagent workflow: A workflow where Codex runs parallel agents and combines their results.
• Subagent: A delegated agent that Codex starts to handle a specific task.
• Agent thread: The thread where a subagent does its work. Supported clients let you open these threads to inspect progress or results.

Triggering subagent workflows

At most intelligence levels, ask for subagents or parallel agent work directly. Ultra enables proactive delegation, so ChatGPT can delegate suitable independent work without a separate request.

Ask for subagents or parallel agent work directly. Codex can also delegate when applicable project or skill instructions request it.

In practice, manual triggering means using direct instructions such as "spawn two agents," "delegate this work in parallel," or "use one agent per point." Subagent workflows consume more tokens than comparable single-agent runs because each subagent does its own model and tool work.

A good subagent prompt should explain how to divide the work, whether Codex should wait for all agents before continuing, and what summary or output to return.

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

Choosing models and reasoning

Different agents need different model and reasoning settings.

In ChatGPT Work, choose a model and an intelligence level from the composer. Available intelligence levels can include Light, Medium, High, Extra High, and Max, depending on the selected model. Ultra is available only to eligible accounts and supported models. It uses maximum reasoning and lets ChatGPT proactively delegate suitable work to subagents.

At other intelligence levels, ask for subagents explicitly when you want work delegated in parallel.

If you don't pin a model or model_reasoning_effort, Codex can choose a setup that balances intelligence, speed, and price for the task. It may favor gpt-5.6-terra for fast scans or a higher-effort gpt-5.6 configuration for more demanding reasoning. When you want finer control, steer that choice in your prompt or set model and model_reasoning_effort directly in the agent file.

For most tasks in Codex, start with gpt-5.6. Use gpt-5.6-terra when you want a faster, lower-cost option for lighter subagent work.

Model choice

• gpt-5.6: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.
• gpt-5.6-terra: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.
• gpt-5.6-luna: Use for fast, narrowly scoped agents handling clear, repeatable, or high-volume work.

Reasoning effort (model_reasoning_effort)

• ultra: Use for the deepest reasoning when the selected model supports it.
• max and xhigh: Use for especially demanding reasoning when the selected model supports these levels.
• high: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).
• medium: A balanced default for most agents.
• low: Use when the task is straightforward and speed matters most.

Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see Models, Config basics, and Configuration Reference.

Orchestration and thread controls

ChatGPT or Codex handles orchestration across agents, including spawning new subagents, routing follow-up instructions, waiting for results, and closing agent threads.

When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.

At most intelligence levels, ChatGPT spawns agents after a direct request. With Ultra, ChatGPT can also delegate proactively when parallel work is useful.

Current local Codex releases spawn agents after a direct request or applicable project or skill instruction.

To see it in action, try the following prompt on your project:

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

Managing subagents

Open Subagents to see read-only Active and Done lists. Select a completed subagent to inspect its details and result. The web sidebar reports subagent activity; it doesn't provide controls to stop or steer an individual subagent.

• Open a subagent thread from the activity shown in the main thread to inspect its work.

• Ask Codex directly to steer a running subagent, stop it, or close completed subagent threads.

• Use /agent in the CLI to switch between active agent threads and inspect the ongoing thread.

• Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.

• When the background-agent panel is available, expand it to inspect status, stop active subagents, or open a subagent thread.

• Ask Codex directly to steer a running subagent, stop it, or close completed subagent threads.

Approvals and sandbox controls

Subagents inherit your current sandbox policy.

ChatGPT Work runs subagents in its hosted environment and doesn't expose a local Codex sandbox or approval-mode control. Subagents use the tools available to the parent chat. Website and connector permissions remain tool-specific.

Subagents inherit the permission mode selected beneath the composer. Choose the permission mode for the parent turn before you ask Codex to delegate work.

In interactive CLI sessions, approval requests can surface from inactive agent threads even while you are looking at the main thread. The approval overlay shows the source thread label, and you can press o to open that thread before you approve, reject, or answer the request.

In non-interactive flows, or whenever a run can't surface a fresh approval, an action that needs new approval fails and Codex surfaces the error back to the parent workflow.

Codex also reapplies the parent turn's live runtime overrides when it spawns a child. That includes sandbox and approval choices you set interactively during the session, such as /permissions changes or --yolo, even if the selected custom agent file sets different defaults.

Subagents inherit the permission mode selected beneath the composer. Choose the permission mode for the parent turn before you ask Codex to delegate work.

You can also override the sandbox configuration for individual custom agents, such as explicitly marking one to work in read-only mode.

Custom agents

Codex ships with built-in agents:

• default: general-purpose fallback agent.
• worker: execution-focused agent for implementation and fixes.
• explorer: read-heavy codebase exploration agent.

To define your own custom agents, add standalone TOML files under ~/.codex/agents/ for personal agents or .codex/agents/ for project-scoped agents.

Each file defines one custom agent. Codex loads these files as configuration layers for spawned sessions, so custom agents can override the same settings as a normal Codex session config. That can feel heavier than a dedicated agent manifest, and the format may evolve as authoring and sharing mature.

Every standalone custom agent file must define:

• name
• description
• developer_instructions

If a custom agent file sets model or model_reasoning_effort, the value in the file takes precedence. Otherwise, Codex resolves each setting independently: an explicit spawn value, then the corresponding [agents] default, then the parent's value. If a spawn selects a different model and neither an explicit nor configured effort is present, Codex uses that model's default effort. Other session settings, such as sandbox_mode, mcp_servers, and skills.config, inherit from the parent when the custom agent file omits them.

Global settings

Global subagent settings still live under [agents] in your configuration.

Notes:

• agents.enabled defaults to true. Set it to false to disable multi-agent tools.
• When you leave agents.max_concurrent_threads_per_session unset, Codex chooses the default. Existing configurations can keep using agents.max_threads as a legacy alias.
• Explicit spawn values override agents.default_subagent_model and agents.default_subagent_reasoning_effort.
• agents.interrupt_message defaults to true. Set it to false to omit the model-visible interruption message from the agent's context.
• If a custom agent name matches a built-in agent such as explorer, your custom agent takes precedence.

Custom agent file schema

You can also include other supported config.toml keys in a custom agent file, such as model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config.

Codex identifies the custom agent by its name field. Matching the filename to the agent name is the simplest convention, but the name field is the source of truth.

Example custom agents

The best custom agents are narrow and opinionated. Give each one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

Example 1: PR review

This pattern splits review across three focused custom agents:

• pr_explorer maps the codebase and gathers evidence.
• reviewer looks for correctness, security, and test risks.
• docs_researcher checks framework or API documentation through a dedicated MCP server.

Project config (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

This setup works well for prompts like:

Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

Example 2: Frontend integration debugging

This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

Project config (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

This setup works well for prompts like:

Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.

Projects and chats

Source: Projects and chats

Use a project to organize related chats and give ChatGPT the context it needs. The Projects view in the ChatGPT desktop app includes ChatGPT projects and local projects that connect to folders on your computer.

Choose a project or start without one

Create a project when work will continue over time, produce more than one output, or depend on the same files and sources. Start a chat without a project when the work is self-contained and doesn't need shared project context.

Use a project to keep related chats, files, instructions, and sources together. The same project can contain chats started with Chat or ChatGPT Work.

Choose a project or chat without one

Create a project when work will continue over time, produce more than one output, or depend on the same files and sources. Start a chat without a project when the work is self-contained and doesn't need shared project context.

Each project has a Chats section that lists project chats and a Sources section for uploaded files and connected context. Project instructions apply across its chats. A ChatGPT project doesn't provide direct access to a folder on your computer, so upload or connect the sources you want ChatGPT to use.

With either option, start a new chat from the project to use its shared files and instructions, then return to it under Chats.

Codex CLI treats the directory where you start it as the project for the chat. Run codex from the directory you want Codex to work in, or pass --cd (-C) to set it explicitly. The CLI doesn't expose the ChatGPT Projects view.

The IDE extension treats the folder or workspace open in your IDE as the local project. In a multi-root workspace, select the workspace root for the chat. The extension doesn't expose the ChatGPT Projects view from the web or desktop app.

Work in a project

The Projects view brings ChatGPT projects and local projects into one place. ChatGPT projects carry project files and context across related chats. A local project gives chats access to one or more folders on your computer, such as a collection of source files or a codebase.

Start a separate chat for each distinct outcome so its messages and results stay focused while the project keeps related work organized.

Work in a project

A ChatGPT project gives its chats access to the same uploaded files, project instructions, and connected sources. Use Chat for a quick chat or ChatGPT Work for a larger deliverable; both appear as chats in the project's Chats section. Start a separate chat for each distinct outcome so its messages and results stay focused while the project preserves shared context.

Work in a project directory

Start Codex from the directory that should provide the chat's file context. Use /new to start a separate chat for each distinct outcome. Use /resume while Codex is open, or run codex resume, to continue a saved chat.

The chat keeps its transcript and recorded working directory, while Codex reads files from the current working tree. Keep durable project guidance in AGENTS.md or checked-in documentation so it is available to future chats.

Work in a workspace

Open the folder or workspace that should provide the chat's file context. Start a new chat for each distinct outcome, then select it from Recent chats to continue it. Chats in the same project can work with the same files, while each chat keeps its own transcript.

The current selection and open files provide context for the current turn. Keep durable project guidance in AGENTS.md or checked-in documentation so it is available to future chats.

Organize projects and chats

Keep active work visible and move finished work out of the way:

• Pin a project to keep it near the top of the sidebar. You can also pin it from the Projects view.
• Pin a chat when you return to it often, even if newer chats appear in the project.
• Rename a chat with a short title that describes its outcome, such as “Q3 launch brief” or “Checkout accessibility review.”
• Search projects from the Projects view. Press Cmd/Ctrl+G to search past chats when you remember a phrase or branch name but not the title.
• Archive a chat when you finish the work. From a project's menu, select Archive chats to archive its chats together.

Pinning doesn't add context or change what ChatGPT can access. It only changes where the project or chat appears in the sidebar.

Restore archived chats from Settings > Archived chats.

Organize projects and chats

Keep active work visible and move finished work out of the way:

• Pin a project to keep it near the top of the sidebar. You can also pin it from the Projects view.
• Pin a chat when you return to it often, even if newer chats appear in the project.
• Rename a chat with a short title that describes its outcome, such as “Q3 launch brief” or “Checkout accessibility review.”
• Search projects from the Projects view. Search past chats with Cmd/Ctrl+K when you remember a phrase or branch name but not the title.
• Archive a chat when you finish the work.

Pinning doesn't add context or change what ChatGPT can access. It only changes where the project or chat appears in the sidebar.

Restore archived chats from Settings > Data Controls > Archived chats.

Use local projects for folders and codebases

Add a local project when ChatGPT needs to read or change files on your computer. Projects don’t need a folder, but you can attach folders as needed.

To add or change folders, open the project's menu and select Edit project. Select Add folder to attach multiple folders. ChatGPT can read and change files in every attached folder. To change the default working directory, point to a folder and select Make primary.

New chats start in the primary folder. Codex also uses that folder as the default for Git operations and automatic discovery of AGENTS.md, skills, and config.toml. Secondary folders remain available for file search, reading, and editing, but Codex doesn't automatically discover those project files from secondary folders.

Use multiple folders when related work lives in different places, like an app and its documentation or a website and its backend. Create separate projects for unrelated work or when each chat should access only one part of a repository. This keeps the working context focused. Remote projects currently support one folder.

Use local environments to define setup actions and common commands for a project. The review pane can show changes across repositories attached to the same project. Pull request and worktree actions target the primary repository. When you start a chat in a worktree, the other folders remain attached.

Projects and worktrees organize work, but the sandbox enforces what local commands can read, change, or access over the network.

Start a chat without a project

Select New chat when the work is self-contained and doesn't need shared project files, instructions, or folder access. Create a project first when several chats will depend on the same context.

Start a chat without a project

Start a chat from ChatGPT Home when the chat doesn't need shared project files, instructions, or sources. You can use Chat or ChatGPT Work; on the web, both create chats.

If the work grows, move it into a project and use clear chat names for each outcome. A project can hold parallel chats for research, drafting, review, and follow-up without mixing every message into one context.

Use Quick chat for a quick question

Quick chat opens an ordinary ChatGPT chat. ChatGPT chats don't appear in the Codex sidebar, which contains your Codex chats and projects.

Point to New chat, then select the Quick chat icon on its right. You can also press

Cmd+Option+N on macOS or Ctrl+Alt+N on Windows. From New chat, you can open an existing ChatGPT chat and add it to a Codex chat.

Bring in other tools and context

• Attach files or image inputs directly to a chat when they apply only to that request.

• Install plugins to bring in context and actions from other services.

• Configure MCP servers when your organization or developer setup exposes tools through Model Context Protocol.

• Use memories, where available, to carry useful context from past work into future chats.

• Pass image inputs to a chat when visual context applies only to that request.

• Install plugins to bring in context and actions from other services.

• Configure MCP servers when your organization or developer setup exposes tools through Model Context Protocol.

• Use memories, where available, to carry useful context from past work into future chats.

• Reference open files or select code in the editor to add context for the current turn.

• Configure MCP servers when your organization or developer setup exposes tools through Model Context Protocol.

• Use memories from the connected Codex host, where available, to carry useful context into future chats.

• Add files and connected sources to the project's Sources section when they should be available across its chats.

• Attach files or image inputs directly to a chat when they apply only to that chat.

• In ChatGPT Work, install plugins to bring in context and actions from other services.

• Use memories, where available, to carry useful context from past work into future chats.

Next steps

• Learn how to write and refine prompts
• Learn how to use ChatGPT
• Continue long-running work

Speed

Source: Speed

ChatGPT Work and Codex share usage. Both use the same pricing, credits, and usage limits. See Codex pricing for details.

Fast mode

Codex offers the ability to increase the speed of the model for increased credit consumption.

Fast mode increases supported model speed by 1.5x and consumes credits at a higher rate than Standard mode. It currently supports GPT-5.6, GPT-5.5, and GPT-5.4. GPT-5.6 and GPT-5.5 consume credits at 2.5x the Standard rate; GPT-5.4 consumes credits at 2x the Standard rate.

Use /fast on, /fast off, or /fast status in the CLI to change or inspect the current setting. You can also persist the default with service_tier = "fast" plus [features].fast_mode = true in config.toml. Fast mode is available in the ChatGPT desktop app, Codex CLI, and IDE extension when you sign in with ChatGPT. Fast mode is a ChatGPT credit feature. With an API key, Codex uses API token pricing instead, and ChatGPT credit multipliers don't apply. API Priority processing has its own billing rate; for GPT-5.6, it costs 2x the Standard API token rate.

Codex-Spark

GPT-5.3-Codex-Spark is a separate fast, less-capable Codex model optimized for near-instant, real-time coding iteration. Unlike fast mode, which speeds up a supported model at a higher credit rate, Codex-Spark is its own model choice and has its own usage limits.

During research preview Codex-Spark is only available for ChatGPT Pro subscribers.

Developers

Source: Developers

Use Codex with codebases, development environments, automation, and your team's tools.

Codex supports everyday code work and deeper integrations across local and cloud environments. Its developer workflows span code review, the integrated terminal, reusable skills and plugins, automation with the SDK and App Server, team tools, and reference material for each surface.

Explore workflows

Development workflows

Review changes and work with development tools in ChatGPT.

• Code review: Review changes and address feedback before you ship.

• Integrated terminal: Run commands and inspect output inside the ChatGPT desktop app.

Extend and automate

Package development workflows and run deterministic automation.

• Build skills: Package instructions and resources for repeatable tasks in ChatGPT and Codex.

• Build plugins: Package skills and MCP servers for ChatGPT and Codex.

• Hooks: Run custom commands when Codex emits lifecycle events.

Environments

Choose where development work runs and how it is isolated.

• Environments: Compare local, cloud, and other ways to run a task.

• Local environments: Configure setup scripts and actions for projects and worktrees.

• Cloud environment: Delegate work to a configured cloud environment.

• Git worktrees: Isolate parallel changes in separate working trees.

Build with Codex

Add Codex to products, systems, and automated workflows.

• Codex SDK: Control Codex programmatically from your application.

• App Server: Integrate with the protocol that powers Codex clients.

• MCP Server: Expose Codex capabilities through Model Context Protocol.

• GitHub Action: Run Codex from GitHub Actions workflows.

• Non-interactive mode: Run Codex from scripts and other automated systems.

Third-party integrations

Delegate and track work from tools your team already uses.

• GitHub: Assign work, review changes, and move toward a pull request.

• Slack: Start Codex chats from external discussions and return results.

• Linear: Assign issues to Codex and follow work through delivery.

Reference

Find commands, settings, and plugin submission errors for developer surfaces.

• CLI customization: Adjust syntax highlighting, themes, and shell behavior.

• Developer commands: Use commands and slash commands in the desktop app, Codex CLI, and IDE extension.

• Developer settings: Configure the desktop app, Codex CLI, and IDE extension for development.

Get started with ChatGPT Work

Source: Get started with ChatGPT Work

Introducing ChatGPT Work

ChatGPT Work is a way to delegate real work to ChatGPT.

Use Chat when you want an answer, explanation, brainstorm, or short draft. Use ChatGPT Work when you want ChatGPT to complete a task with a clear outcome, such as a brief, deck, analysis, recurring update, workflow, or file you can review and use. Learn more about using Chat and ChatGPT Work together.

ChatGPT Work can use your files, plugins, and approved tools to retrieve information, create finished files, run workflows, and complete work that is ready for you to review. You can follow progress, answer questions, change direction, and approve important actions.

On the desktop app, ChatGPT Work can also use local files, apps, and the browser when those tools are available.

If you have used Codex for non-coding work, you can stay in Codex or use ChatGPT Work instead. ChatGPT Work gives you the same core capabilities with an experience designed for everyday work.

What to try first

First, switch to Work. Then choose your first task. Good tasks have a clear outcome, a few source materials, and an output you can review.

Choose local or cloud work

In the desktop app, open the composer control labeled Work locally. If Cloud appears as an option, choose it when you want ChatGPT Work to keep running after you close the app or turn off your computer, or when you want to continue the chat from the web or mobile app. Keep Work locally selected when the task needs files or apps on your computer.

Cloud is also useful for scheduled tasks that research or check websites over time because their runs don't depend on your computer being awake.

Here are three common use cases you can get started with:

Create a presentation

Use ChatGPT Work to turn notes, docs, research, or meeting materials into a structured deck.

Create a comparison spreadsheet

Use ChatGPT Work to turn notes, files, or research into a spreadsheet that compares options and helps you make a decision.

Set up a recurring update

Use scheduled tasks when you want ChatGPT Work to repeat, monitor, or refresh something over time.

Learn more about scheduled tasks.

Best practices for using ChatGPT Work

Use ChatGPT Work when you want ChatGPT to complete a task, create a file, or manage work over time. It is a good fit for tasks that:

• Use multiple sources, plugins, tools, or steps.
• Would take meaningful time to complete manually.
• Produce an output you will review, edit, or reuse.
• Need to be repeated, monitored, or updated over time.

To get a better result, tell ChatGPT the outcome you need, the sources or plugins to use, any constraints to follow, what good looks like, and when to stop for review or approval.

Instead of: Make me a presentation about our customer research.

Learn more about prompting for ChatGPT Work.

Add plugins for more context and better outputs

Plugins connect ChatGPT Work to tools your team uses, like Slack, Google Drive, SharePoint, email, calendars, customer relationship management systems, and project trackers.

• Select Plugins in the left sidebar to view the plugins library.
• Install the plugins most relevant to your work.
• To point ChatGPT to a specific tool, type @ and the plugin name in your prompt.

Learn more about plugins.

Use ChatGPT Work efficiently

ChatGPT Work is best for substantial tasks that involve multiple steps, sources, or tools, or require a completed deliverable. Longer or more complex tasks may use more credits because ChatGPT is doing more on your behalf. Focus on the value of the completed result, rather than the number of prompts.

Keep the task focused by setting useful boundaries. For example: “use only these sources,” “compare the top five options,” or “stop before sending anything.”

Use Chat instead for quick questions, short rewrites, and decisions where you only need advice.

Learn more about working efficiently.

More use cases

Explore practical ChatGPT Work workflows for common teams and tasks.

Long-running work

Source: Long-running work

For work that may take many steps, give ChatGPT a clear outcome, constraints, and definition of done. Keep related work in the same chat so ChatGPT can use the same context to choose the next step and decide when the work is complete.

In the ChatGPT desktop app, enter /goal to start Goal mode. The progress row lets you pause, resume, edit, or clear the goal while ChatGPT works.

For hosted long-running work in ChatGPT web, use ChatGPT Work and put the outcome, constraints, and review criteria directly in your prompt.

Continue in the same web chat to add context, change constraints, or ask for a status update. Use separate chats when independent tasks can run in parallel, and avoid giving two tasks write access to the same connected source. For related work, keep the chats and source files together in a project.

In an interactive Codex CLI session, enter /goal to start Goal mode. Continue the same session to steer the work or ask for a status update.

In the IDE extension chat, enter /goal to start Goal mode for the open workspace. Continue the same chat to steer the task while it runs.

Start a goal

Type /goal in the ChatGPT desktop app, Codex CLI, or the IDE extension. The goal text becomes both the first prompt and the completion criteria for the task.

If the outcome is still unclear, start with /plan. Ask ChatGPT to interview you, identify constraints, and turn the result into a goal with measurable success criteria. Then start the refined goal with /goal.

Define what done means

Write a goal that lets ChatGPT verify its own progress. Include three things when they apply:

For example:

Migrate this codebase from JavaScript to TypeScript. Preserve existing behavior,
compile in strict mode without explicit `any` types, and make the full test suite pass.

Steer a running goal

In the ChatGPT desktop app, the goal progress row appears above the composer. Use it to pause or resume work, edit the goal, or clear it. You can also send follow-up messages while the goal runs to add context or adjust constraints.

Use a side chat when you want a status recap or an explanation without interrupting the main chat. Pause the goal before you expect to lose connectivity, then resume it when you're ready for ChatGPT to continue.

Steer running work

Continue in the same chat to add context, adjust constraints, or ask for a status recap. Start a separate chat when another task can run independently.

Steer a running goal

Send a follow-up message in the same interactive session to add context or adjust constraints. Ask for a status recap when you want Codex to summarize progress before it continues.

Steer a running goal

Continue in the same IDE chat to add context, adjust constraints, or ask for a status recap. Keep the workspace available while the goal is running.

Starting a goal doesn't grant ChatGPT broader access. It keeps the same sandbox and approval policy and pauses when it needs a decision. With automatic approval reviews, a separate reviewer can evaluate eligible requests without expanding those boundaries.

Run goals in parallel

Each chat keeps its own context, messages, results, and goal. Run chats concurrently, but avoid letting two chats change the same files. Use worktrees to give parallel coding chats separate checkouts.

For local work, turn on Prevent sleep while running in settings so your Mac stays awake. Use Pets or system notifications to see when a chat needs input or is ready for review.

Related docs

• Projects and chats
• Goal mode and prompting
• Git worktrees

Related docs

• Projects and chats
• Scheduled tasks
• Sandbox and permissions

Prompting

Source: Prompting

Prompting overview

Prompting is how you tell ChatGPT what you want to know, make, or change. A prompt can be a question, an instruction, or a goal. You don't need technical syntax or a rigid formula. Start in your own words, review the response, and use follow-up messages to shape the result.

A short prompt is often enough. For larger or more important tasks, include the parts that matter:

• Goal: What should ChatGPT do?
• Context: What information or sources will help?
• Output: What format, length, or level of detail do you need?
• Boundaries: What must stay unchanged? What should ChatGPT avoid or check with you before it acts?

Use only the parts that help. You don't need to fill in every item or follow a required format.

Describe the result you need

Start with the result, not a detailed list of steps. Include the audience or format when those details change what ChatGPT should produce.

Turn these meeting notes into a short update for the project team.
Put the decisions and next steps first.

This prompt explains what to create and who will read it. Describe a process when the process itself matters. Otherwise, leave ChatGPT room to search, compare information, and adjust its approach.

Add useful context

Share the information that could change the result. Add only the sources that matter, and explain what ChatGPT should take from each one.

• Attach documents, spreadsheets, presentations, or PDF files when you want ChatGPT to summarize, compare, transform, or create files for review.
• Add a screenshot, diagram, or other image input when the task depends on visual context. Point out the area that matters instead of relying on the image alone.
• Ask ChatGPT to use web search when the answer depends on current information, and ask for sources when you need to check the result.
• Use a project when related chats should share files, sources, or a local folder.

Use connected sources

When ChatGPT has access to connected sources, name where it should look and what it should find. You don't need to describe every search it should run.

Use the latest project plan in Drive and relevant decisions and updates from
the project's Slack channel to prepare a status update.

Connected sources require the matching plugin, and availability can depend on your plan and workspace settings.

Use plugins

Plugins give ChatGPT and Codex reusable instructions and connections to tools such as Google Drive, Gmail, Slack, and GitHub. Both products draw public plugins from the same universal directory. Ask for the result you need and let the active surface choose from the tools available to it. In ChatGPT, type @ in the composer to choose a specific plugin.

[

Find, install, and use plugins in ChatGPT and Codex.

](https://learn.chatgpt.com/docs/plugins)

Personalize ChatGPT

Put preferences that should apply across chats in Settings > Personalization as custom instructions. Keep details that matter only to the current chat in the prompt.

[

Set a default personality, custom instructions, and other app preferences.

](https://learn.chatgpt.com/docs/reference/settings#personalization)

Set boundaries that prevent real problems

Boundaries are the few instructions ChatGPT needs to avoid creating extra work or taking an action you didn't intend. Add one when changing the wrong detail would make the result unusable, or when you want to review something before it affects other people.

• Keep the approved dates and budget figures unchanged.
• Use only the supplied sources. Flag missing information instead of guessing.
• Keep recommendations within the stated budget.
• Prepare the message as a draft. Don't send it.

Focus on the one or two boundaries that matter most. You don't need to control every step ChatGPT takes.

Make the result ready to use

Tell ChatGPT how you plan to use the result. This helps it choose the right length, level of detail, and organization.

• Make this a one-page summary a director can scan before the meeting. Put the decision and next steps first.
• Turn these notes into a follow-up email with the decisions, owners, and due dates.
• Create a clear table of planned versus actual spending and highlight any difference over 10%.

For important work, ask ChatGPT for a final check, such as confirming every action item has an owner and due date or flagging information it couldn't verify. Then review the result yourself before you use or share it.

Improve the result with follow-up messages

Your first prompt doesn't need to be perfect. Review the result, then ask for the specific change you want.

Make the opening more direct, keep the evidence, and move the recommendation
above the background section.

You can add a missing source, correct the direction, ask for another option, or change the level of detail without starting over.

Steering and queuing

When Codex is already working, you can send another message without waiting for the current run to finish:

• Steer adds the message to the current run. Use it to change direction, add a missing detail, or share new information.
• Queue saves the message for the next run. Use it for a follow-up that should wait until the current work finishes.

In the ChatGPT desktop app, choose the default under Settings > General > Follow-up behavior. Queued messages appear above the composer, where you can edit, reorder, send, or delete them. The setting also shows the shortcut for using the other behavior for one message without changing your default.

In Codex CLI, press Enter while Codex is working to steer the current turn, or press Tab to queue the message for the next turn. See the interactive shortcuts for details.

Put the pieces together

For a project update that uses connected sources, a complete prompt might look like this:

Prepare a one-page project status update for Monday's leadership meeting. Use
the latest project plan in Drive and relevant decisions and updates from the
project's Slack channel.

Lead with the decisions leadership needs to make and the next steps. Summarize
progress, risks, owners, and due dates. Keep approved dates and budget figures
unchanged. Flag any conflicting or missing information, and don't send or
publish anything.

Before you finish, check that every next step has an owner and due date.

This prompt covers the Goal, Context, Output, and Boundaries, then asks for a final check without spelling out every step.

Use voice dictation

In the ChatGPT desktop app, hold Ctrl+M while the composer is visible, then start talking. ChatGPT transcribes your speech into the composer so you can review and edit it before sending the prompt.

Prompting examples for Chat

Use Chat for questions, ideas, drafts, and everyday decisions. Start with the outcome you want, then add detail only when it changes the answer.

Understand a topic

Explain how compound interest works for someone who has never invested.
Use one concrete example and define any financial terms you introduce.

Draft and refine writing

Draft a friendly email declining this invitation because I will be traveling.
Keep it under 120 words and leave the door open for a future event.

Compare options

Compare these two phone plans for one person who travels internationally twice
a year. Show the important differences in a table, then recommend one and explain
the tradeoff.

Make a practical plan

Plan five weekday dinners that take less than 30 minutes. Avoid peanuts, reuse
ingredients across meals, and finish with one consolidated shopping list.

Prompting for ChatGPT Work

Use Chat for quick questions, short rewrites, brainstorming, and lightweight drafts. Use ChatGPT Work for tasks that draw on different sources or tools, involve a sequence of steps, make changes, or produce a larger deliverable.

In ChatGPT Work, describe the result you need, provide the source material, name the audience, and explain how you'll review the work. Ask ChatGPT to plan, gather the needed information, create files, and check them before it finishes.

Use ChatGPT Work efficiently

ChatGPT Work is useful for time-consuming or recurring tasks, or for finished files you can reuse. A task that uses more credits can still be worthwhile if it saves time, improves quality, or helps you make an important decision.

Start with one result you can review:

• Include only relevant sources and limit the date range when appropriate.
• Define the audience, output format, and desired length.
• Separate required work from optional improvements or polish.
• Ask for a plan when the approach matters. Require your approval before ChatGPT sends, publishes, or changes information other people rely on.
• Narrow or stop the task if it starts doing work you no longer need.

Review the first result, refine the instructions, and reuse the workflow when it works.

Turn source material into finished files

Use the attached quarterly reports to create a leadership brief and a six-slide
presentation.

The audience is the executive team. Lead with the three decisions they need to
make, distinguish reported facts from your analysis, cite each number to its
source file, and check that the brief and slides agree before you finish.

Research a decision

Research three customer-support platforms for a 50-person company. Compare
pricing, security, integrations, and migration effort using current sources.
Deliver a recommendation memo with links, assumptions, and the questions we
should answer before signing a contract.

Coordinate a launch

Create a launch plan for the attached product brief. Include the timeline,
owners, dependencies, risks, announcement draft, customer FAQ, and a checklist
for launch day. Flag any missing decisions before producing the final files.

For recurring work, first refine the prompt in a normal chat. After the output is reliable, schedule a task inside that chat. Create a standalone scheduled task instead when each scheduled run should start a new chat.

Prompting Codex

Use Codex when you want ChatGPT to work with code, a codebase, or developer tools. A useful Codex prompt names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change.

For a multi-step task, enter /plan in the app composer when you want Codex to investigate and propose an approach before editing. When Goal mode is available, use /goal after the plan to set a persistent goal. See the app slash commands for the current command list.

How to read these examples

Each workflow includes:

• When to use it and which Codex surface fits best (IDE, CLI, or cloud).
• Steps with example user prompts.
• Context notes: what Codex automatically sees vs what you should attach.
• Verification: how to check the output.

Note: The IDE extension automatically includes your open files as context. In the CLI, mention paths explicitly, or attach files with /mention and @ path autocomplete.

Codex runs local commands inside a sandbox that limits file and network access. If a task needs to cross that boundary, Codex follows your approval policy before continuing.

Explain a codebase

Use this when you are onboarding, inheriting a service, or trying to reason about a protocol, data model, or request flow.

Recipe: explain a codebase in IDE

1. Open the most relevant files.

2. Select the code you care about (optional but recommended).

3. Prompt Codex:

   Explain how the request flows through the selected code.
   
   Include:
   - a short summary of the responsibilities of each module involved
   - what data is validated and where
   - one or two "gotchas" to watch for when changing this
   

Verification:

• Ask for a diagram or checklist you can verify:

Summarize the request flow as a numbered list of steps. Then list the files involved.

Recipe: explain a codebase in CLI

1. Start an interactive session:

   codex
   

2. Attach the files (optional) and prompt:

   I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules.
   

Context notes:

• You can use @ in the composer to insert file paths from the workspace, or /mention to attach a specific file.

Fix a bug

Use this when you have a failing behavior you can reproduce locally.

Recipe: fix a bug in CLI

1. Start Codex at the repo root:

   codex
   

2. Give Codex a reproduction recipe, plus the file(s) you suspect:

   Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.
   
   Repro:
   1) Start the app: npm run dev
   2) Go to /settings
   3) Toggle "Enable alerts"
   4) Click Save
   5) Refresh the page: the toggle resets
   
   Constraints:
   - Do not change the API shape.
   - Keep the fix minimal and add a regression test if feasible.
   
   Start by reproducing the bug locally, then propose a patch and run checks.
   

Context notes:

• Supplied by you: the repro steps and constraints (these matter more than a high-level description).
• Supplied by Codex: command output, discovered call sites, and any stack traces it triggers.

Verification:

• Codex should re-run the repro steps after the fix.
• If you have a standard check pipeline, ask it to run it:

After the fix, run lint + the smallest relevant test suite. Report the commands and results.

Recipe: fix a bug in IDE

1. Open the file where you think the bug lives, plus its nearest caller.

2. Prompt Codex:

   Find the bug causing "Saved" to show without persisting changes. After proposing the fix, tell me how to verify it in the UI.
   

Write a test

Use this when you want to define the exact scope to test.

Recipe: write a test in IDE

1. Open the file with the function.

2. Select the lines that define the function. Choose "Add to Codex Thread" from command palette to add these lines to the context.

3. Prompt Codex:

   Write a unit test for this function. Follow conventions used in other tests.
   

Context notes:

• Supplied by "Add to Codex Thread" command: the selected lines (this is the "line number" scope), plus open files.

Recipe: write a test in CLI

1. Start Codex:

   codex
   

2. Prompt with a function name:

   Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.
   

Prototype from a screenshot

Use this when you want to turn a design mock, screenshot, or UI reference into a working prototype.

CLI workflow (image + prompt)

1. Save your screenshot locally (for example ./specs/ui.png).

2. Run Codex:

   codex
   

3. Drag the image file into the terminal to attach it to the prompt.

4. Follow up with constraints and structure:

   Create a new dashboard based on this image.
   
   Constraints:
   - Use react, vite, and tailwind. Write the code in typescript.
   - Match spacing, typography, and layout as closely as possible.
   
   Outputs:
   - A new route/page that renders the UI
   - Any small components needed
   - README.md with instructions to run it locally
   

Context notes:

• The image provides visual requirements, but you still need to specify the implementation constraints (framework, routing, component style).
• Include behavior the image doesn't show in text, such as hover states, validation rules, or keyboard interactions.

Verification:

• Ask Codex to run the dev server (if allowed) and tell you exactly where to look:

Start the dev server and tell me the local URL/route to view the prototype.

IDE extension workflow (image + existing files)

1. Attach the image in the Codex chat (drag-and-drop or paste).

2. Prompt Codex:

   Create a new settings page. Use the attached screenshot as the target UI.
   Follow design and visual patterns from other files in this project.
   

Iterate on UI with live updates

Use this when you want a tight "design → tweak → refresh → tweak" loop while Codex edits code.

CLI workflow (run Vite, then iterate with small prompts)

1. Start Codex:

   codex
   

2. Start the dev server in a separate terminal window:

   npm run dev
   

3. Prompt Codex to make changes:

   Propose 2-3 styling improvements for the landing page.
   

4. Pick a direction and iterate with small, specific prompts:

   Go with option 2.
   
   Change only the header:
   - make the typography more editorial
   - increase whitespace
   - ensure it still looks good on mobile
   

5. Repeat with focused requests:

   Next iteration: reduce visual noise.
   Keep the layout, but simplify colors and remove any redundant borders.
   

Verification:

• Review changes in the browser as Codex updates the code.
• Commit changes that you like and revert those that you don't.
• If you revert or change an edit, tell Codex so it doesn't overwrite your edit when it works on the next prompt.

Delegate refactor to the cloud

Use this when you want to design an approach with local context, then delegate the long implementation to a cloud chat that can run in parallel.

Local planning (IDE)

1. Make sure your current work is committed or at least stashed so you can compare changes cleanly.

2. Ask Codex to produce a refactor plan. If you have the $plan skill available, invoke it explicitly:

   $plan
   
   We need to refactor the auth subsystem to:
   - split responsibilities (token parsing vs session loading vs permissions)
   - reduce circular imports
   - improve testability
   
   Constraints:
   - No user-visible behavior changes
   - Keep public APIs stable
   - Include a step-by-step migration plan
   

3. Review the plan and negotiate changes:

   Revise the plan to:
   - specify exactly which files move in each milestone
   - include a rollback strategy
   

Context notes:

• Planning works best when Codex can scan the current code locally (entrypoints, module boundaries, dependency graph hints).

Cloud delegation (IDE → Cloud)

1. If you haven't already done so, set up a Codex cloud environment.

2. Click on the cloud icon beneath the prompt composer and select your cloud environment.

3. When you enter the next prompt, Codex creates a new chat in the cloud that carries over the existing chat context (including the plan and any local source changes).

   Implement Milestone 1 from the plan.
   

4. Review the cloud diff, iterate if needed.

5. Create a PR directly from the cloud or pull changes locally to test and finish up.

6. Iterate on additional milestones of the plan.

Tasks delegated to the cloud run in isolated environments. Internet access is off during the agent phase unless you enable it for the environment. Learn more about cloud internet access.

Do a local code review

Use this when you want a second set of eyes before committing or creating a PR.

CLI workflow (review your working tree)

1. Start Codex:

   codex
   

2. Run the review command:

   /review
   

3. Optional: provide custom focus instructions:

   /review Focus on edge cases and security issues
   

Verification:

• Apply fixes based on review feedback, then rerun /review to confirm you resolved the issues.

Review a GitHub pull request

Use this when you want review feedback without pulling the branch locally.

Before you can use this, enable Codex Code review on your repository. See Code review.

GitHub workflow (comment-driven)

1. Open the pull request on GitHub.

2. Leave a comment that tags Codex with explicit focus areas:

   @codex review
   

3. Optional: Provide more explicit instructions.

   @codex review for security vulnerabilities and security concerns
   

Update documentation

Use this when you need an accurate, clear documentation change.

IDE or CLI workflow (local edits + local validation)

1. Identify the doc file(s) to change and open them (IDE) or @ mention them (IDE or CLI).

2. Prompt Codex with scope and validation requirements:

   Update the "advanced features" documentation to provide authentication troubleshooting guidance. Verify that all links are valid.
   

3. After Codex drafts the changes, review the documentation and iterate as needed.

Verification:

• Read the rendered page.

Approvals, Sandboxing, and Security

Sandbox behavior, approvals, cyber-safety, and security-specific guidance.

Codex Security CLI FAQ

Source: Codex Security CLI FAQ

Find answers to common questions about scanning repositories and managing security findings from the terminal. For installation and a first scan, start with the CLI quickstart.

Repository scans

Who can use the CLI

The @openai/codex-security package is public. Install the CLI and SDK:

npm install @openai/codex-security

Running scans requires Codex Security access. For best results, use an account verified for Trusted Access for Cyber.

Why does a scan use an API key after sign-in

When your environment includes OPENAI_API_KEY or CODEX_API_KEY, scans without an interactive terminal and JSON and JSONL scans use the environment API key by default, even after a successful ChatGPT or access-token login. Interactive scans with text output ask you to choose when a ChatGPT sign-in is also available. Dry runs don't prompt or load credentials.

To use your stored credentials for a scan, select them explicitly:

npx @openai/codex-security scan . --auth chatgpt

To require an API key from OPENAI_API_KEY or CODEX_API_KEY:

npx @openai/codex-security scan . --auth api-key

To make your stored credentials the automatic default, run unset OPENAI_API_KEY CODEX_API_KEY. For all supported authentication modes, see the CLI reference.

How does bulk repository scanning work

Sign in with GitHub CLI:

gh auth login

Discover and select repositories from a GitHub account or organization:

npx @openai/codex-security bulk-scan

For a prepared list, provide a repository CSV and an output directory:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

See Run bulk security scans for GitHub discovery, the CSV format, campaign results, and available options.

Can an interrupted bulk scan resume

Yes. Run the same bulk-scan command with the original CSV and output directory. Codex Security skips completed repositories.

Add --max-attempts 3 to retry temporary repository or scan errors:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

A completed scan with partial or unknown coverage keeps its results and causes the campaign to exit with code 2. It isn't retried, even with --max-attempts.

How can a scan use architecture and security policies

Pass architecture documents, threat models, or security policies with --knowledge-base:

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Codex Security uses these documents as context for the current scan. For supported file types and directory behavior, see Add security context.

Findings and coverage

Where can teams find earlier scan results

List saved scans for your repository:

npx @openai/codex-security scans list /path/to/repository

Use a scan ID from the results to inspect its findings:

npx @openai/codex-security scans show SCAN_ID

Each completed scan keeps its report, findings, coverage, and supporting artifacts together. See Scan artifacts for the full layout.

What if the CLI can't save scan history

Codex Security keeps scan history in a workbench database. If the default state directory isn't writable, choose a private directory outside the repository:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

How do scans distinguish new and known findings

Compare findings across the two scans:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison automatically matches findings by root cause, reuses saved matches, and identifies new, persisting, reopened, resolved, and unknown findings. A finding counts as resolved only when the later scan covers its original target and affected path without coverage gaps.

How does false-positive feedback work

Inspect the saved scan to find the occurrence ID:

npx @openai/codex-security scans show SCAN_ID

Record why that finding doesn't apply:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Future scans of the same repository receive that explanation as context. They still independently check the current source, controls, and reachability. A dismissal doesn't suppress a rule, path, or vulnerability class.

For command details, see the findings reference.

Why can repeat scans return different findings

AI-assisted scans can vary, even with the same scan configuration. Start by rerunning your baseline scan:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Compare the baseline with the new scan:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Provide shared architecture and security guidance when missing context may contribute to the variation. Matching can identify the same underlying finding across runs, but it doesn't make scans deterministic. Directly recheck any important finding that disappears.

How can a team confirm that a fix worked

After applying a fix, rerun the original scan:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Compare the original findings with the new scan:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Confirm that the new scan covers the original target and affected path without coverage gaps. Then directly recheck the original finding against the current checkout:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

A missing finding or scan comparison alone doesn't prove that a fix worked.

What does incomplete coverage mean

Coverage can be complete, partial, or unknown. Review coverage.json for excluded paths, deferred surfaces, and open questions before treating a scan as evidence of review.

Scans with partial or unknown coverage return exit code 2, even without a severity policy. They still keep any available findings and coverage. A later scan can't establish that an earlier finding no longer exists when it doesn't cover that finding's original path.

Automation and cost

How do scan cost limits work

Set an estimated cost limit in USD before starting the scan:

npx @openai/codex-security scan . --max-cost 5

The limit is an estimate, not a hard spending cap. Requests already in progress can finish above the limit. Codex Security keeps available results when the scan stops.

Can scans check commits and pull requests

Install a pre-commit security check for staged and unstaged changes:

npx @openai/codex-security install-hook

For pull-request checks, scan the committed changes and set a severity threshold:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

A complete scan returns exit code 1 when it finds an issue at or above the selected severity. See Run scans in CI for the complete GitHub Actions workflow, artifact handling, and SARIF export.

Can another application run scans directly

Yes. Use the TypeScript SDK to start scans, select targets, inspect findings and coverage, track progress, and apply cost controls from an application or developer tool.

Codex Security CLI quickstart

Source: Codex Security CLI quickstart

Codex Security helps security and engineering teams find, confirm, and fix vulnerabilities. Use its command-line interface (CLI) to scan repositories you own or have permission to assess, review findings over time, and check changes before they land.

The @openai/codex-security package is public. Running scans requires Codex Security access. For an interactive scan in Codex, start with the Codex Security plugin quickstart. For connected GitHub repositories, see Codex Security cloud setup.

Check the prerequisites

The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings also requires Python 3.10 or later. For more detail, see Authentication and prerequisites.

Set up and verify the CLI

Install the published package:

npm install @openai/codex-security

List the available commands:

npx @openai/codex-security --help

See also CLI reference.

Sign in

For local use, sign in with your ChatGPT account:

npx @openai/codex-security login

On a remote or headless machine, use device authentication:

npx @openai/codex-security login --device-auth

For CI and other automated workflows, set an OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

For AWS credentials, see Amazon Bedrock setup. For OpenRouter or Fireworks, set the provider's API key and select a model with --provider and --model.

To use your ChatGPT sign-in when an API key is also set, select it explicitly:

npx @openai/codex-security scan . --auth chatgpt

To require the environment API key, select API-key authentication:

npx @openai/codex-security scan . --auth api-key

Depending on your account and repository, full-repository scans may also require Trusted Access for Cyber.

Prepare a scan

Choose a repository to scan and a directory to write results.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

If you omit --output-dir, Codex Security saves results in its own persistent state directory. Results can include source excerpts and vulnerability details, so choose a private location and an appropriate retention policy.

If the default state directory isn't writable, select a writable directory outside the scanned repository:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Check the repository, target, and output directory before starting a scan:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

The dry run checks local inputs, including any --knowledge-base paths, without starting Codex, loading credentials, or probing the plugin's Python interpreter.

Run your first scan

Run a standard scan and keep its results in the selected directory:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

Interactive terminals show a live scan dashboard. Add --headless to show plain progress lines instead. CI and terminals without an interactive session use plain progress automatically.

By default, the CLI writes scan progress and its completion summary to stderr. It doesn't print the full scan result to stdout. A completed scan prints a summary like this:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

Token usage and estimated cost appear when available. To print the complete result as machine-readable JSON, request structured output explicitly:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Scans are report-only by default, so findings remain available for local review. You may want to add a severity threshold when you are ready to run scans in CI.

Choose a model and reasoning effort

Scans use gpt-5.6-sol with xhigh reasoning effort by default. Select a different model and effort when the task requires them:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Supported effort levels are minimal, low, medium, high, and xhigh.

Review the results

Open report.md for the readable result. The scan directory also contains the structured files used by automation:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

• scan-manifest.json records the target, scope, producer, and sealed artifacts.
• findings.json records severity, confidence, locations, evidence, and remediation for each finding.
• coverage.json records reviewed surfaces, exclusions, deferred work, open questions, and coverage completeness.

Coverage can be complete, partial, or unknown. Read any deferred areas or open questions before treating the scan as evidence of review. The CLI reference describes the full artifact and output contract.

Choose the next scan

Use a path scan when a repository contains separate services or packages:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Review committed changes between the base revision and HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Review staged and unstaged changes against HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Diff and working-tree scans expect the repository argument to be the Git worktree root. Fetch the selected revisions before starting a diff scan.

Use deep mode when a repository or path needs broader review:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

To control discovery workers, subagents, and when the scan stops:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10

These options require deep mode, which supports repository and path targets, not diff or working-tree scans. Here, --workers controls discovery workers within one scan; bulk-scan --workers controls concurrent repository scans.

Add architecture and security context

Provide architecture documents, threat models, or security policies as scan context. This helps Codex Security evaluate findings against how your system actually works:

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Add custom scan instructions

Add instructions that focus the scan on your security priorities. Use a second file for a follow-up after a validated scan with complete coverage:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

The follow-up runs in the same authenticated session. Both options also work with bulk-scan; a CSV prompt column adds repository-specific instructions.

Set a scan budget

Use --max-cost to stop a scan when its estimated model cost exceeds a limit in USD:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Requests already in progress can finish slightly above the limit. If a scan aborts due to the cost limit, partial scan results remain available on disk.

Scan changes before each commit

Install a Git pre-commit security check for your repository:

npx @openai/codex-security install-hook

The check scans staged and unstaged changes before each commit. It blocks high-severity findings and scan errors without replacing an existing pre-commit script.

Scan repositories in bulk

Sign in to GitHub before discovering repositories:

gh auth login

Discover and select repositories from your GitHub account or organization:

npx @openai/codex-security bulk-scan

The interactive flow excludes archived repositories and forks. It asks you to confirm the selected repositories before scanning.

To scan a prepared repository list, provide a CSV and an output directory:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

Run the same command again to resume an existing bulk scan. Codex Security skips completed repositories. Add --max-attempts 3 when you want to retry temporary repository or scan errors.

For GitHub discovery, CSV preparation, campaign results, and Docker setup, see Run bulk security scans.

Run bulk scans in Docker

If your access includes the Codex Security Docker image, use the supplied hardened Compose configuration and security profile on a Linux Docker host. The host must support unprivileged user namespace creation. Supply a repository CSV, keep results and sign-in state in persistent mounted directories, and provide credentials through your environment or a secret manager:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

The container runs bulk scans without interactive prompts. Use the CLI outside Docker when you want to discover repositories interactively. For private repositories, provide GH_TOKEN or GITHUB_TOKEN through your environment or secret manager. The sign-in requirements, including account and repository access, also apply to containerized scans.

Revisit a saved scan

List the saved scans for your repository:

npx @openai/codex-security scans list "$REPOSITORY"

Copy a scan ID from the results to inspect its findings and configuration:

npx @openai/codex-security scans show SCAN_ID

To mark a reviewed finding as a false positive, explain why the finding doesn't apply:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Later scans consider that explanation but still recheck the current code.

Run the same scan against the current checkout using its original configuration:

npx @openai/codex-security scans rerun SCAN_ID

Compare two scans to find new, persisting, reopened, resolved, or unknown findings:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison automatically matches findings by root cause and reuses saved matches.

For the bulk-scan CSV format, scan-history filters, and command options, see the CLI reference.

Continue with the workflow that fits your goal:

• Run bulk security scans to discover GitHub repositories or scan a pinned CSV inventory.
• Read the CLI FAQ for answers about scan history, false-positive feedback, coverage, and fix verification.
• Run scans in CI to review pull requests, preserve results, and set a severity policy.
• Use the CLI reference to check every flag, output format, artifact, and exit code.
• Integrate the TypeScript SDK to run scans from an application or developer tool.

Codex Security CLI reference

Source: Codex Security CLI reference

Use this reference to check the supported codex-security commands, flags, output formats, and exit behavior. For a guided first scan, start with the CLI quickstart.

The @openai/codex-security package is public. Running scans requires Codex Security access.

Install the published package in your project:

npm install @openai/codex-security

Invoke the installed package as npx @openai/codex-security. You can use codex-security directly when the executable is available on your PATH.

Command overview

usage: codex-security [--version] <command> [options]

The CLI provides these commands:

The CLI also provides these integration commands:

List all available commands:

npx @openai/codex-security --help

Add --help to a command to inspect its arguments and options:

npx @openai/codex-security scan --help

codex-security --version prints the installed version and exits. codex-security info --json reports the SDK and bundled-plugin versions. Neither command requires Python.

Discover commands and connect agents

Print the agent-readable command manifest:

npx @openai/codex-security --llms

Inspect the scan argument schema as JSON:

npx @openai/codex-security scan --schema --format json

Generate shell completions for Bash:

npx @openai/codex-security completions bash

Replace bash with zsh or fish for those shells.

Scan results support --format toon|json|yaml|jsonl and --full-output. This framework-level --format is separate from --export-format, which selects the format of an artifact exported from a completed scan. Global command help also lists md, but scan results don't support Markdown output.

Register the CLI as an MCP server:

npx @openai/codex-security mcp add

Sync Codex Security skills to your agents:

npx @openai/codex-security skills add

MCP exposes only the read-only info metadata command. Scans, exports, authentication, validation, and patching remain CLI-only.

codex-security scan

Run a scan against a repository, selected paths, committed changes, or the working tree.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository defaults to the current directory.

Select scan authentication

Use --auth auto, the default, to select credentials automatically. When both a ChatGPT sign-in and OPENAI_API_KEY or CODEX_API_KEY are available, interactive scans with text output ask which credential to use. CI, JSON and JSONL scans, and other scans without an interactive terminal use the environment API key. Dry runs don't prompt or load credentials.

To use your stored credentials, pass --auth chatgpt:

npx @openai/codex-security scan . --auth chatgpt

To use an environment API key, pass --auth api-key:

npx @openai/codex-security scan . --auth api-key

To make stored credentials the automatic default, run unset OPENAI_API_KEY CODEX_API_KEY.

Use OpenRouter or Fireworks

Select OpenRouter with its API key and an explicit model:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Select Fireworks with its API key and an explicit model:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Both providers also support bulk-scan.

Use Amazon Bedrock

Select Amazon Bedrock with --provider amazon-bedrock and specify an explicit Bedrock model with --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Set AWS_REGION and authenticate with AWS_BEARER_TOKEN_BEDROCK, standard AWS access keys, an AWS profile, web identity, container credentials, or the default AWS credential chain. Bedrock scans use AWS credentials instead of --auth, ChatGPT sign-in, or an OpenAI API key. Both scan and bulk-scan support --provider.

Select the scan target

Choose one target type for each scan.

--path, --diff, and --working-tree are mutually exclusive. --head requires --diff, and --base requires --working-tree. Deep mode supports repository and path targets.

Diff and working-tree scans require the repository argument to be the Git worktree root. The selected refs must exist in that checkout.

Scan the entire repository:

npx @openai/codex-security scan .

Scan selected paths:

npx @openai/codex-security scan . --path src --path tests

Scan committed changes:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Scan staged and unstaged changes:

npx @openai/codex-security scan . --working-tree --base HEAD

Run a deeper review of the repository:

npx @openai/codex-security scan . --mode deep

Configure deep scans

Use these options with --mode deep to control discovery concurrency and runtime:

--subagents accepts zero or a positive integer. The other options require a positive integer. These options aren't available for standard scans.

For example, limit a deep scan to two discovery workers and ten total runs:

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10

Set persistent defaults in ~/.codex/codex-security/config.toml, or in $CODEX_HOME/codex-security/config.toml when you set CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10

Command-line options override these defaults. scan --workers controls discovery workers within one scan; bulk-scan --workers controls concurrent repository scans.

Add security context

Use --knowledge-base PATH to provide architecture documents, threat models, or security policies. Repeat the option for more files or directories:

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Supported documents include .md, .markdown, .txt, .pdf, and .docx files. The CLI searches directories recursively, rejects linked input paths, skips linked directory entries, and keeps extracted document content outside the saved scan results.

Add scan instructions

To add scan instructions, provide a text or Markdown file with --scan-prompt-file. Use --post-scan-prompt-file to run follow-up instructions in the same authenticated session after a completed scan with complete coverage:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

For example, use the scan prompt to focus on authorization boundaries and ask the follow-up to write a new post-scan-summary.md in the scan directory.

Set output and policy options

Use these options to keep artifacts, preserve earlier results, or create a machine-readable result.

The cost limit is an estimate, not a hard spending cap. Requests already in progress can finish slightly above the limit. If a scan aborts due to the cost limit, partial scan results remain available on disk.

When you omit --output-dir, results persist under $CODEX_HOME/state/plugins/codex-security/scans/. CODEX_HOME defaults to ~/.codex. Set CODEX_SECURITY_STATE_DIR to keep results under $CODEX_SECURITY_STATE_DIR/scans/ instead. These directories can contain source excerpts and vulnerability details, so manage their permissions and retention accordingly.

The workbench keeps scan history in $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Setting CODEX_SECURITY_STATE_DIR also moves the workbench database.

The output directory must be outside the scanned directory and any enclosing Git worktree. A scan can replace an existing result directory with --archive-existing.

To preserve earlier results before reusing an output directory:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Scans are report-only by default. Add --fail-on-severity to evaluate a severity policy in CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

A dry run checks local inputs, including knowledge-base documents, without loading credentials, starting Codex, or probing the plugin's Python interpreter:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Configure the runtime

Use runtime options when you need an explicit model, interpreter, plugin, or Codex configuration value.

To select a different model and reasoning effort without writing TOML:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Quote string values passed through --codex so the TOML parser receives a string:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Install a Git pre-commit security check for the current repository:

npx @openai/codex-security install-hook

The check scans staged and unstaged changes before each commit and blocks high-severity findings or scan errors. It respects core.hooksPath and does not replace an existing pre-commit script. Set a different severity threshold when needed:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Discover and scan GitHub repositories, or run a resumable scan from a repository CSV:

For a complete guide to GitHub discovery, CSV inventories, campaign results, and containerized scans, see Run bulk security scans.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Run npx @openai/codex-security bulk-scan without arguments to select repositories interactively. This flow requires a GitHub CLI sign-in.

To choose a model and reasoning effort during interactive discovery:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

For a prepared repository list, provide a CSV and --output-dir:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

The CSV requires id, repository, and revision columns. Revisions must be full commit hashes. Optional scope, mode, and prompt columns configure individual repositories:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authorization boundaries.

Use --knowledge-base PATH to share security documents across every repository. Use --scan-prompt-file FILE to add shared scan instructions; the CSV prompt column adds repository-specific instructions after that shared prompt. --post-scan-prompt-file FILE runs follow-up instructions after each completed scan with complete coverage.

--workers limits simultaneous repository scans and defaults to 4. --mode defaults to standard, and --max-attempts defaults to 1. Set --max-attempts to retry repository or scan errors. Completed scans with incomplete coverage aren't retried. Their results remain available, and the command returns exit code 2.

Run the same command again to resume from an existing output directory. The CLI skips completed scans, including scans with incomplete coverage.

For containerized campaigns, see Run bulk scans in Docker.

codex-security scans

Find saved scans

List saved scans for the current directory:

npx @openai/codex-security scans

List scans for a different repository:

npx @openai/codex-security scans list /path/to/repository

Find scans stored under a specific output directory:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Inspect or repeat a scan

Show a saved scan's results and configuration:

npx @openai/codex-security scans show SCAN_ID

Rerun the scan against the current checkout using its original configuration:

npx @openai/codex-security scans rerun SCAN_ID

Match and compare findings

Compare two scans to find new, persisting, reopened, resolved, and unknown findings:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison automatically matches findings that share the same root cause and reuses saved matches. To save matches explicitly, use scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A finding is unknown when the later scan has incomplete coverage or doesn't cover the finding's original location. Add --force to match when you need to recompute an existing match.

To match all completed scans for the current repository, including scans from other checkouts:

npx @openai/codex-security scans match --all

Scan results can vary even when you rerun the same configuration. Matching and comparison track changes; they don't make results deterministic or prove that a vulnerability no longer exists. Use validate to recheck a security-critical finding against the current code.

codex-security findings

Record a reviewed finding as a false positive:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Inspect the saved scan to identify the finding occurrence:

npx @openai/codex-security scans show SCAN_ID

Record a specific explanation for the false positive:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

The reason must not be empty. Codex Security saves the decision for the repository and provides it as context to future scans. Each scan independently rechecks the current source, controls, and reachability. A previous decision doesn't suppress a rule, path, or vulnerability class.

codex-security export

Export CSV, JSON, or SARIF from a completed, sealed scan. Export validates the scan artifacts before writing output and leaves the Codex runtime and credentials untouched.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir is the completed scan directory.

--source-root works only with --export-format sarif. JSON preserves the sealed findings document. CSV contains portable finding columns and does not include local workbench triage state.

Without --output, the CLI writes SARIF to results.sarif, JSON to findings.json, and CSV to findings.csv in the current working directory. Exports can contain source excerpts and vulnerability details. Run the command outside the repository or pass --output with a private path outside the scanned checkout.

Write SARIF to a file:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Write SARIF to stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Export findings as JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Export findings as CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate and codex-security patch

Check whether a candidate finding is valid:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Generate a fix with the bundled remediation skill:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Each argument can contain literal text or point to a file. Both commands work against the current directory. Use validate to directly recheck an original finding after a fix or when a later scan no longer reports it. A scan comparison alone doesn't prove that a fix worked. External tools can use these commands without rebuilding the scanner.

Use --effort to select reasoning effort for either command:

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout, and info

Sign in interactively:

npx @openai/codex-security login

Use device authentication on a remote or headless machine:

npx @openai/codex-security login --device-auth

Check the current sign-in:

npx @openai/codex-security login status

Remove the stored sign-in:

npx @openai/codex-security logout

Store an API key by passing it on stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Store an enterprise access token:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Inspect read-only SDK and bundled-plugin metadata:

npx @openai/codex-security info --json

When you expose the CLI as an MCP server, info is the only available command. Scans, exports, sign-in, validation, and patching remain CLI-only.

Read scan output

By default, scans send progress, completion summaries, and errors to stderr without writing the complete scan result to stdout. Request --json, --format, or --full-output to send structured scan results to stdout.

Interactive terminals show a live dashboard with the current scan phase, reviewed files, activity, token usage, and estimated cost. CI and redirected output use plain-text progress. Add --headless to use plain-text progress in an interactive terminal:

npx @openai/codex-security scan . --headless

Verbose diagnostics

Add --verbose to print redacted lifecycle, authentication, progress, and cost diagnostics to stderr:

npx @openai/codex-security scan . --verbose

Set CODEX_SECURITY_LOG_LEVEL=debug to enable the same diagnostics without the flag. LOG_LEVEL=debug also enables diagnostics when CODEX_SECURITY_LOG_LEVEL is unset.

These logging controls apply only to the CLI. Credentials and provider identifiers remain redacted, and structured scan results remain on stdout.

Completion summary

A completed scan writes its finding count, severity breakdown, coverage, elapsed time, report path, and result directory to stderr. It includes token usage and estimated cost when available:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Informational findings count toward the summary total. Severity policies evaluate only critical, high, medium, and low findings.

JSON output

scan --json writes one complete JSON document to stdout. Its top-level shape is:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

Progress, completion summaries, archive notices, and errors remain on stderr. A completed scan still prints the full JSON result when a severity policy returns exit 1 or incomplete coverage returns exit 2.

codex-security scan --json emits one JSON document. codex exec --json emits a JSON Lines event stream. Use the output format that matches the command you run.

Scan artifacts

A completed scan keeps the readable report and structured artifacts together:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

The structured files serve different jobs:

Coverage completeness has three values:

• complete: The scan records complete coverage for its selected scope.
• partial: The scan records deferred work or other coverage limits.
• unknown: The scan reports coverage completeness as unknown.

Review deferred surfaces, explicit exclusions, and open questions before using coverage as evidence for a security decision.

Exit codes and signals

The CLI uses these exit codes:

Any scan with partial or unknown coverage returns 2, even without a severity policy. When you request structured output, completed scans still write the available results to stdout. The CLI prints the location of any partial output after an interruption or runtime error.

Authentication and prerequisites

Set OPENAI_API_KEY or CODEX_API_KEY, sign in with npx @openai/codex-security login, or use an existing file-backed Codex sign-in. For OpenRouter or Fireworks, set the provider's API key and select a model. For Amazon Bedrock, use a Bedrock API key or the standard AWS credential chain instead.

For credential selection, see Select scan authentication.

For CI, keep the API key scoped to the scan step and use a trusted workflow.

The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings also requires Python 3.10 or later. Python 3.10 also requires tomli. Use --python or PYTHON to select an interpreter when automatic discovery is unsuitable.

Continue with the CLI quickstart, bulk-scan guide, CLI FAQ, CI guide, or TypeScript SDK guide.

Codex Security cloud FAQ

Source: Codex Security cloud FAQ

This FAQ covers Codex Security cloud. For local scans and workflows that run in a Codex task, see the Codex Security plugin quickstart.

{/_ vale Microsoft.Auto = NO /} {/ vale Vale.Spelling = NO _/}

Cloud security FAQ: getting started

What is Codex Security?

Software security remains one of the hardest and most important problems in engineering. Codex Security is an LLM-driven security analysis toolkit that inspects source code and returns structured, ranked vulnerability findings with proposed patches. It helps developers and security teams discover and fix security issues at scale.

Why does it matter?

Software is foundational to modern industry and society, and vulnerabilities create systemic risk. Codex Security supports a defender-first workflow by continuously identifying likely issues, validating them when possible, and proposing fixes. That helps teams improve security without slowing development.

What business problem does Codex Security solve?

Codex Security shortens the path from a suspected issue to a confirmed, reproducible finding with evidence and a proposed patch. That reduces triage load and cuts false positives compared with traditional scanners alone.

How does Codex Security work?

Codex Security runs analysis in an ephemeral, isolated container and temporarily clones the target repository. It performs code-level analysis and returns structured findings with a description, file and location, criticality, root cause, and a suggested remediation.

For findings that include verification steps, the system executes proposed commands or tests in the same sandbox, records success or failure, exit codes, stdout, stderr, test results, and any generated diffs or artifacts, and attaches that output as evidence for review.

Does it replace SAST?

No. Codex Security complements SAST. It adds semantic, LLM-based reasoning and automated validation, while existing SAST tools still provide broad deterministic coverage.

Features

What is the analysis pipeline?

Codex Security follows a staged pipeline:

1. Analysis builds a threat model for the repository.
2. Commit scanning reviews merged commits and repository history for likely issues.
3. Validation tries to reproduce likely vulnerabilities in a sandbox to reduce false positives.
4. Patching integrates with Codex to propose patches that reviewers can inspect before opening a PR.

It works alongside engineers in GitHub, Codex, and standard review workflows.

What languages are supported?

Codex Security is language-agnostic. In practice, performance depends on the model's reasoning ability for the language and framework used by the repository.

What outputs do I get after the scan completes?

You get ranked findings with criticality, validation status, and a proposed patch when one is available. Findings can also include crash output, reproduction evidence, call-path context, and related annotations.

How is customer code isolated?

Each analysis and validation job runs in an ephemeral Codex container with session-scoped tools. Artifacts are extracted for review, and the container is torn down after the job completes.

Does Codex Security auto-apply patches?

No. The proposed patch is a recommended remediation. Users can review it and push it as a PR to GitHub from the findings UI, but Codex Security does not auto-apply changes to the repository.

Does the project need to be built for scanning?

No. Codex Security can produce findings from repository and commit context without a compile step. During auto-validation, it may try to build the project inside the container if that helps reproduce the issue. For environment setup details, see Codex cloud environments.

How does Codex Security reduce false positives and avoid broken patches?

Codex Security uses two stages. First, the model ranks likely issues. Then auto-validation tries to reproduce each issue in a clean container. Findings that successfully reproduce are marked as validated, which helps reduce false positives before human review.

How long do initial scans take, and what happens after that?

Initial scan time depends on repository size, build time, and how many findings proceed to validation. For some repositories, scans can take several hours. For larger repositories, they can take multiple days. Later scans are usually faster because they focus on new commits and incremental changes.

What is a threat model?

A threat model is the scan-time security context for a repository. It combines a concise project overview with attack-surface details such as entry points, trust boundaries, auth assumptions, and risky components. For more detail, see Improving the threat model.

How is a threat model generated?

Codex Security prompts the model to summarize the repository architecture and security entry points, classify the repository type, run specialized extractors, and merge the results into a project overview or threat model artifact used throughout the scan.

Does it replace manual security review?

No. Codex Security accelerates review and helps rank findings, but it does not replace code-level validation, exploitability checks, or human threat assessment.

Can I edit the threat model?

Yes. Codex Security creates the initial threat model, and you can update it as the architecture, risks, and business context change. For the editing workflow, see Improving the threat model.

Do I need to configure a scan before using threat modeling?

Yes. Threat-model guidance is tied to how and what you scan, so you need to configure the repository first. See Codex Security setup.

What does the proposed patch contain?

The proposed patch contains a minimal actionable diff with filename and line context when a remediation can be generated for the finding.

Does the patch directly modify my PR branch?

No. The workflow generates a diff, patch file, or suggested change for maintainers and reviewers to inspect before applying.

Validation

What is auto-validation?

Auto-validation is the phase that tries to reproduce a suspected issue in an isolated container. It records whether reproduction succeeded or failed and captures logs, commands, and related artifacts as evidence.

What happens if validation fails?

The finding remains unvalidated. Logs and reports still capture what was attempted so engineers can retry, investigate further, or adjust the reproduction steps.

{/_ vale Microsoft.Auto = YES /} {/ vale Vale.Spelling = YES _/}

Codex Security cloud setup

Source: Codex Security cloud setup

This page walks you from initial access to reviewed findings and remediation pull requests in Codex Security cloud.

Confirm you've set up Codex cloud first. If not, see Codex cloud to get started.

1. Access and environment

Codex Security cloud scans GitHub repositories connected through Codex cloud.

• Confirm your workspace has access to Codex Security cloud.
• Confirm the repository you want to scan is available in Codex cloud.

Go to Codex environments and check whether the repository already has an environment. If it doesn't, create one there before continuing.

Open environments

2. New security scan

After the environment exists, go to Create a security scan and choose the repository you just connected.

Create a security scan

Codex Security scans repositories from newest commits backward first. It uses this to build and refresh scan context as new commits come in.

To configure a repository:

1. Select the GitHub organization.
2. Select the repository.
3. Select the branch you want to scan.
4. Select the environment.
5. Choose a history window. Longer windows provide more context, but backfill takes longer.
6. Click Create.

3. Initial scans can take a while

When you create the scan, Codex Security first runs a commit-level security pass across the selected history window. The initial backfill can take a few hours, especially for larger repositories or longer windows. If findings aren't visible right away, this is expected. Wait for the initial scan to finish before opening a ticket or troubleshooting.

Initial scan setup is automatic and thorough. This can take a few hours. Don’t be alarmed if the first set of findings is delayed.

4. Review scans and improve the threat model

Review scans

When the initial scan finishes, open the scan and review the threat model that was generated. After initial findings appear, update the threat model so it matches your architecture, trust boundaries, and business context. This helps Codex Security rank issues for your team.

If you want scan results to change, you can edit the threat model with your updated scope, priorities, and assumptions.

After initial findings appear, revisit the model so scan guidance stays aligned with current priorities. Keeping it current helps Codex Security produce better suggestions.

For a deeper explanation of threat models and how they affect criticality and triage, see Improving the threat model.

5. Review findings and patch

After the initial backfill completes, review findings from the Findings view.

Open findings

You can use two views:

• Recommended Findings: an evolving top 10 list of the most critical issues in the repo
• All Findings: a sortable, filterable table of findings across the repository

Click a finding to open its detail page, which includes:

• a concise description of the issue
• key metadata such as commit details and file paths
• contextual reasoning about impact
• relevant code excerpts
• call-path or data-flow context when available
• validation steps and validation output

You can review each finding and create a PR directly from the finding detail page.

Review findings and create a PR

Security setup references

• Codex Security gives the product overview.
• Codex Security cloud FAQ covers common cloud questions.
• Improving the threat model explains how to improve scan context and finding prioritization.

Codex Security plugin changelog

Source: Codex Security plugin changelog

Use this changelog to see what changed in Codex Security and which plugin versions are available from each installation source.

Latest release in the hosted Codex Security catalog: 0.1.17.

Check the plugin version in your current Codex environment before you use a feature from a newer release. Reopening or rerunning a saved scan doesn't pin the installed plugin version.

These versions apply to the Codex Security plugin. The Codex app, Codex CLI, TypeScript SDK, and plugin app have separate version numbers.

0.1.17 (August 5, 2026)

Follow scan progress as it happens

• Track the current scan phase, elapsed time, active workers, reviewed files, and token usage from a single live progress view.
• See repository review progress update as files finish instead of waiting for a scan to complete.

Resume interrupted deep scans

• Continue an in-progress deep scan after its coordinator restarts without repeating completed file reviews.
• Preserve completed discovery results, scan ownership, and pending work across app updates or interrupted scan sessions.

Start and complete scans with less overhead

• Start standard, change, and deep scans directly in native workflows without opening the retired embedded scan widget.
• Reuse completed scan summaries without reloading every finding unless you request the complete structured results.

0.1.16 (August 4, 2026)

Track measured scan usage

• Review total, input, cached input, and output token usage across the main scan and its delegated workers.
• Distinguish complete, partial, and unavailable measurements instead of showing missing usage as zero.

Run deeper scans with consistent results

• Use the same threat-modeling, discovery, validation, attack-path analysis, and reporting phases for standard and deep scans.
• Configure deep scan workers, per-worker delegation, saturation, and discovery limits from the CLI or SDK.
• Run deep scans with the model's supported worker runtime and recover older scan state without losing existing scan history.
• Generate the primary report for change and deep scans without requiring separate vulnerability write-ups or hardening recommendations.

Keep scan guidance and repository targets accurate

• Update security guidance during an active scan and carry it into later phases and delegated deep scan workers.
• Preserve repository URLs, pull request references, and longer security context without allowing network access you didn't request.
• Fail scans when the repository or scan target changes during execution so automation doesn't accept stale findings.
• Honor enterprise proxy and trusted certificate settings in managed network environments.

Write clearer vulnerability reports

• Produce source-backed vulnerability reports that separate observed behavior from unverified hypotheses.
• Include realistic proof-of-concept limitations, affected versions, security boundaries, and actionable remediation guidance.

0.1.15 (July 30, 2026)

Keep scans accurate as projects change

• Persist scan lifecycle and model metadata so scan history and progress remain consistent across reloads.
• Preserve completed scans when project files change and avoid reusing SQLite scan directories.

Give feedback and recover findings

• Submit false-positive feedback for findings from completed scans.
• Recover malformed finding records during finalization instead of failing the completed scan.

Handle more repository layouts and paths

• Preserve literal candidate paths and expand ~ in CODEX_HOME during preflight.
• Handle Git-related target validation errors without crashing and support nested Git repositories in scan snapshots.
• Keep Windows and sandbox path handling consistent during scan recovery.

Reduce unnecessary scan work

• Keep standard-scan discovery adaptive to the repository and candidate list.
• Stop retrying policy failures and remove the legacy fan-out prompt.

0.1.14 (July 28, 2026)

Review scan history and recurring findings

• Filter repositories, findings, and scan history with bounded result pages and clearer status details.
• Rerun a scan with its saved settings and compare completed scans to distinguish new, persisting, resolved, and not-rescanned findings.
• Group worktrees from the same repository and use stable repository and finding identities across views.

Define repository security policy

• Use $codex-security:define-security-policy to review or update scoped SECURITY.md guidance for trust boundaries, security invariants, reportable findings, severity, exclusions, and accepted risk.
• Apply the closest policy file while bounding its size and rejecting symbolic links that leave the repository.

Review findings before tracking them

• Select up to 25 findings from a completed scan for tracking in Linear or GitHub Issues.
• Return the selected findings to Codex for review and approval instead of creating issues directly from the findings workspace.

Run standard scans with a simpler workflow

• Use one deterministic in-scope file list and a compact candidate ledger for standard repository and scoped-path scans.
• Preserve the existing manifest, findings, coverage, report, and SARIF outputs while reducing repeated scan stages.

0.1.13 (July 25, 2026)

Review findings across more environments

• Keep real security findings when affected code is local, internal, used for training, or not deployed to production.
• Use deployment and exposure context to calibrate severity and confidence instead of automatically suppressing the finding.

0.1.12 (July 23, 2026)

Run deeper scans with clearer progress

• Run deep scans that coordinate workers across an entire repository or a selected directory.
• Carry your model and reasoning settings into delegated scan work.
• See preflight results, scan progress, available worker capacity, and fallback behavior before and during a scan.

Review and rerun previous scans

• Open current and previous scans from the security scan list.
• Reopen a saved scan in the findings workspace, or rerun it to refresh the results.
• See clearer completion states and more consistent finding details and scan history.

Configure scans with fewer interruptions

• Start scans from the native setup flow without leaving your current task.
• Keep scan setup in the side panel, even when Codex is in full-screen mode.
• Dismiss setup when you don't need it and keep that preference for later scans.

Review and remediate validated findings

• Keep validated low-severity findings in completed results.
• Review more consistent finding details across scans, reports, and exports.
• Retry remediation and carry relevant scan context into follow-up fixes.

Export results for existing security workflows

• Export completed findings as JSON, CSV, or SARIF.
• Generate SARIF results locally for code-scanning and security-tool integrations.
• Preserve consistent finding details across exported formats.

0.1.11 (July 10, 2026)

Produce detailed finding and hardening reports

• Generate one source-backed vulnerability report for every reportable scan finding, with supporting proof-of-concept files when available.
• Review a structural hardening portfolio that analyzes the complete finding set, engineering tradeoffs, migration options, and supporting diagrams.
• Use report.md as the entry point to these derived outputs under findings/ and hardening/. Keep the full scan directory together when sharing or archiving results.

Run reporting workflows directly

• Use $codex-security:vulnerability-writeup to turn disclosure documents, rough findings, PoCs, and source code into polished reports without first running a Codex Security scan.
• Use $codex-security:propose-security-hardening to develop evidence-backed structural or architectural options from scans, findings, incident or assessment documents, and source code.

Apply repository guidance and coverage consistently

• Define threat-model context, security invariants, reportable finding criteria, exclusions, and severity context in root or nested SECURITY.md files. The closest applicable file takes precedence.
• Improve repository review coverage before validation while preserving explicitly deferred surfaces and proof gaps.
• Review deleted source files in change scans and expand the default repository review coverage before validation.
• Check deep-scan phase skills, delegated workers, and worker capacity before a deep scan starts.

0.1.10 (June 23, 2026)

Improve Jira and Linear ticket intake

• Ask before importing Linear sub-issues and preserve parent-child relationships in the results.
• Distinguish missing connections, insufficient permissions, inaccessible tickets, and temporary connector failures.
• Stop instead of creating a verdict when the requested ticket content isn't available.
• Assign unique positive integer ranks starting at 1 within each confirmed or needs-review queue.

Review code changes more reliably

• Compare an inspected commit with its actual parent and preserve the diff target in the findings workspace.
• Report unavailable patch state instead of reviewing a different change.
• Review more consistent triage results and finding context.

0.1.9 (June 18, 2026)

Review scans in the findings workspace

• Review completed scans in a dedicated workspace that brings findings, coverage, severity, confidence, and scan artifacts together.
• Filter and sort findings, including sorting by highest confidence, while preserving your workspace state during refreshes.
• Open a finding to review source evidence, validation details, reachability, impact, and remediation guidance in one place.

Run scans with less setup

• Run standard scans against Git repositories, individual folders, or codebases without Git history. Deep scans can also target a specific folder.
• Cancel an active scan explicitly, resume an interrupted scan without another setup prompt, and receive a warning before starting concurrent deep scans.
• Follow clearer setup and progress states, with more compact progress summaries and errors that remain visible until you address them.

Export portable, verifiable results

• Use a consistent completed-scan format with a manifest, structured findings, coverage data, and a Markdown report derived from the same canonical result.
• Export findings as JSON, CSV, or SARIF for analysis, archiving, and integration with other security tools.
• Complete scans more reliably, including when Windows paths or scan locking affect filesystem access.

Triage and track existing findings

• Triage existing findings from scanners, advisories, bug bounty reports, GitHub, Jira, Linear, or Codex Security results against the current codebase. The triage workflow returns an evidence-backed verdict and a prioritized action queue.
• Track selected validated findings in Linear, Jira, or GitHub issues, or create a private draft GitHub Security Advisory when the repository meets the advisory requirements.
• Review duplicate checks, source context, destination visibility, and the exact proposed content before approving a write. Codex reads the result back after creation or update to verify it.

0.1.7 (June 4, 2026)

Run evidence-backed security reviews

• Scan an authorized repository or selected folder for security vulnerabilities.
• Run repeated discovery across an entire repository when you need more thorough coverage.
• Review pull requests, commits, branch differences, and local patches for security regressions.
• Move each candidate through threat modeling, finding discovery, validation, and impact analysis before generating scan reports.
• Fix one accepted finding with a focused patch, regression coverage, and verification of the original issue.

Codex Security plugin quickstart

Source: Codex Security plugin quickstart

Codex Security scans your code for vulnerabilities and validates plausible findings. For each reportable issue, it gives you the evidence and remediation guidance you need to review the result. Scan only code you own or have permission to assess.

Follow this quickstart to install the plugin and run a read-only scan of a local repository in Codex.

This page covers the Codex Security plugin in the desktop app or Codex CLI. To scan a connected GitHub repository in Codex cloud, see Codex Security cloud setup.

Install the plugin

1. Open Codex in the ChatGPT desktop app.
2. Open Plugins, search for Codex Security, or use the button below:

Install the Codex Security plugin

3. Confirm the plugin is enabled, then open Security in the sidebar.

4. In your terminal, go to the repository you want to assess and start Codex:

   codex
   

5. Enter /plugins, search for Codex Security, and select Install plugin.

6. Enter /new to start a new chat for the repository.

To install Codex Security for a local repository, use the ChatGPT desktop app or Codex CLI.

The hosted desktop-app catalog and public Codex CLI marketplace can offer different plugin versions. Check the plugin changelog before you rely on a feature or start a long-running scan. If Security doesn't appear in the desktop-app sidebar, update the app and plugin and confirm that the plugin is enabled.

Run your first scan

For the best scan quality, use gpt-5.6-sol with xhigh reasoning effort.

Choose a repository and configure a new security scan before you start it.

1. Open the scan setup

   Select Security in the sidebar, open Scans, and select + Scan.

2. Choose the codebase and scan area

   Select an existing repository or use another folder. Choose Codebase, leave Deep scan off, and select the entire repository or one folder. Confirm that the branch and revision identify the code you intended to scan.

3. Add relevant context

   Choose the model and reasoning effort. Open Additional context only when you need to describe a specific attack vector, security-sensitive area, or repository detail that should guide the review.

   Turn on additional context to describe attack vectors, focus areas, and
   relevant security guidance.
   

4. Start the scan

   Select Start scan and follow the scan phases in the Security workbench. Select View activity to inspect the Codex task that performs the scan.

5. Review the result

   Open the completed scan to inspect findings, coverage, and available report artifacts. Use Findings to review issues across scans or Repositories to inspect a repository's scan history.

   Review scan results, findings, and coverage in the Security workbench.
   

6. Ask for an ordinary scan

   Send this prompt in the new chat:

   Run a Codex Security scan on this repository.
   

7. Let the scan finish

   Codex runs the scan in the terminal without opening a setup workspace. Keep the task running until Codex reports that it is complete. If Codex identifies a configuration limitation, review the limitation and the exact proposed change before you approve a configuration update.

8. Review the result

   Review the summary in the terminal, then open the generated report.md for the complete result.

Run this local plugin workflow in the ChatGPT desktop app or Codex CLI.

What the scan creates

Completed scans remain available in Scans. Review their findings and coverage in the Security workbench, or inspect related findings and repository history in Findings and Repositories. The scan also creates the files below.

Every completed scan reports a summary in the terminal and creates the files below.

Run this local plugin workflow in the ChatGPT desktop app or Codex CLI.

• report.md, the primary readable entry point to the scan results.
• findings//, when detailed vulnerability reports and supporting proof-of-concept files are available.
• hardening/, when structural hardening guidance and supporting proposals or diagrams are available.
• Structured scan data in scan-manifest.json, findings.json, and coverage.json for automation and integrations. You normally don't need to open these files yourself.

Keep the full scan directory together when sharing or archiving results so the links from report.md continue to work.

Choose your next workflow

• Use the Security workbench to manage saved scans, findings, repositories, and scan activity in the desktop app.
• Run a scan from the CLI if you have beta access and need a repeatable terminal workflow with structured results.
• Run a standard or scoped scan to review a repository or one folder with the default workflow.
• Run a deep scan for a more thorough scan when you can allow for a longer runtime.
• Review code changes to assess a pull request, commit, branch range, or working-tree patch.
• Triage a backlog to review existing security findings.
• Fix and verify a finding after you accept one finding for remediation.
• Export or track findings to create JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a private draft GitHub Security Advisory.
• Write vulnerability reports to turn supplied findings, disclosure notes, source, and PoCs into self-contained reports.
• Propose security hardening to consider structural or architectural options based on scan results or other security evidence.

Codex Security TypeScript SDK

Source: Codex Security TypeScript SDK

Use the Codex Security TypeScript SDK to run security scans on repositories and code changes from your application or developer tool. The SDK returns typed findings, coverage details, and paths to scan artifacts. For longer scans, it supports preflight checks, cost limits, progress callbacks, and cancellation.

The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22.13.0 or later. Scanning also requires Python 3.10 or later.

The Codex Security SDK is publicly available on GitHub. Running scans requires Codex Security access. For general coding agents, see the Codex SDK guide. For terminal and CI workflows, see the Codex Security CLI quickstart.

Set up the SDK

Install the SDK:

npm install @openai/codex-security

Before starting a scan, set OPENAI_API_KEY or CODEX_API_KEY, use an existing file-backed Codex sign-in, or configure another provider. Amazon Bedrock uses AWS credentials; OpenRouter and Fireworks use provider-specific API keys and configuration.

For best results, use an account verified for Trusted Access for Cyber. Signing in or providing an API key does not grant Trusted Access.

Run a scan

Create one CodexSecurity client, run a standard repository scan, and close the client when the work completes. Pass outputDir to choose a private results directory outside the enclosing Git worktree.

If you omit outputDir, Codex Security saves results in its own persistent state directory. Results can include source excerpts and vulnerability details, so choose appropriate permissions and retention policies.

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run starts the scan, waits for completion, validates the sealed artifacts, and returns a ScanResult. close releases the isolated runtime and supports repeated calls.

Check inputs with preflight

Use preflight to check a repository, target, mode, knowledge-base documents, output location, and Codex configuration before starting a scan:

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: ["/path/to/architecture.md"],
  outputDir: "/path/outside/repository/results",
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

Preflight leaves the Codex runtime and credentials untouched. It also leaves plugin and Python discovery for the scan itself. This makes preflight useful for checking user input before a long-running or credentialed operation.

To preview archival for an existing result directory, set archiveExisting: true:

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

The returned archiveDir previews the archive naming. The final path can differ because run generates its own unique destination. Capture the actual archive path with onOutputArchived:

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

The scan archives the earlier results and starts with an empty output directory.

Choose a scan target

The SDK supports repository, path, committed-diff, and working-tree targets. The default target is the complete repository.

Scan selected paths

Pass an array of paths inside the repository:

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Paths can identify files or directories. The SDK resolves each path inside the repository and removes duplicates.

Scan committed changes

Use DiffTarget.refs to scan committed changes between two locally available Git revisions:

import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

The head defaults to HEAD. Diff targets require the repository argument to be the Git worktree root.

Scan the working tree

Use DiffTarget.workingTree to scan staged and unstaged changes against a base revision:

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

The base defaults to HEAD. Fetch the selected revisions before starting a diff or working-tree scan.

Select deep mode

Set mode: "deep" for a repository or path scan that needs broader review:

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
});

Deep mode supports repository and path targets. Use standard mode for diff and working-tree scans. The optional settings control concurrent discovery workers, subagents per worker, consecutive discovery runs without new findings, and the total number of discovery runs. They require mode: "deep".

Add a security knowledge base

Pass architecture documents, threat models, or security policies through knowledgeBasePaths:

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

The SDK accepts files or directories and searches directories recursively. Supported document formats are .md, .markdown, .txt, .pdf, and .docx. The SDK rejects linked input paths, skips linked directory entries, and keeps extracted document content outside the saved scan results.

Add scan and follow-up instructions

Use scanPrompt to focus the scan and postScanPrompt to request a follow-up after a completed scan:

const result = await security.run("/path/to/repository", {
  scanPrompt: "Focus on tenant isolation and authorization checks.",
  postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});

The follow-up runs in the same authenticated session only after the scan finishes with complete coverage.

Set a scan budget

Set maxCostUsd to stop a scan when its estimated model cost exceeds a limit. Use onCost to track cost as the scan runs:

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

The limit estimates spending but isn't a hard cap, so requests already in progress can finish slightly above it. If the scan exceeds the limit, the SDK throws ScanCostLimitExceededError and preserves the available results.

Work with scan results

ScanResult exposes the structured documents, scan metadata, and artifact paths:

Use the structured findings and coverage directly:

for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

Coverage completeness is complete, partial, or unknown. Review deferred surfaces, exclusions, and open questions before using a scan as evidence for a security decision.

result.toJSON() returns the manifest, findings, coverage, scan and thread identifiers, reportPath, artifactsDir, sarifPath, and turn metadata in one JSON-ready object.

Track or cancel a scan

Pass ScanOptions callbacks to report scan startup, worker progress, and connection retries:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onProgress(progress) {
    console.log(progress.phase, progress.filesCompleted, progress.filesTotal);
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onReconnect(attempt, maxAttempts) {
    console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
  },
  onObserverError(observer, error) {
    console.error(`${observer} failed`, error);
  },
});

console.log(result.reportPath);

Pass an AbortSignal when cancellation comes from a request, job controller, or timeout:

import { ScanInterruptedError } from "@openai/codex-security";

const controller = new AbortController();

try {
  const scan = security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: controller.signal,
  });

  controller.abort();
  await scan;
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

An interrupted scan can leave partial output in scanDir. Preserve that directory when the result needs investigation.

Applications that display scan setup progress can also use the ScanOptions lifecycle callbacks:

Trusted Access status is granted, not_granted, or unknown. Missing or unknown access also triggers onWarning.

Configure the runtime and credentials

Pass runtime configuration when you need a specific plugin, interpreter, or Codex setting:

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-5.6-terra",
    model_reasoning_effort: "high",
  },
});

pluginPath accepts a plugin directory or ZIP. pythonPath selects the plugin interpreter. codexOverrides merges supported values into the isolated Codex configuration. Scans use gpt-5.6-sol with extra-high reasoning effort by default. Set model and model_reasoning_effort in codexOverrides to use a different model or reasoning effort. To use Amazon Bedrock, set model_provider and model in codexOverrides.

For OpenRouter or Fireworks, also provide the matching API key and a complete provider configuration in codexOverrides. For example, set OPENROUTER_API_KEY and configure OpenRouter:

const security = new CodexSecurity({
  codexOverrides: {
    model: "anthropic/claude-sonnet-4.5",
    model_provider: "openrouter",
    model_providers: {
      openrouter: {
        name: "OpenRouter",
        base_url: "https://openrouter.ai/api/v1",
        env_key: "OPENROUTER_API_KEY",
        wire_api: "responses",
      },
    },
  },
});

For Fireworks, change both openrouter keys to fireworks, set name to Fireworks AI, set env_key to FIREWORKS_API_KEY, use https://api.fireworks.ai/inference/v1 as base_url, and select a Fireworks model.

The client also exposes supported authentication methods:

A login handle provides waitForInstructions, authUrl, verificationUrl, userCode, wait, and cancel so an application can present and complete the selected sign-in flow. The SDK can reuse a file-backed Codex sign-in. API keys are a useful fit for CI and server-side automation.

When both an API key and a stored sign-in are available, the SDK uses the API key by default. To use your ChatGPT sign-in instead, select it for the scan:

const result = await security.run("/path/to/repository", {
  auth: "chatgpt",
});

Set auth: "api-key" to require an environment API key. preflight accepts the same auth option.

Handle scan errors

Catch the exported error class that matches the action your application can take:

Continue with the CLI quickstart, CI guide, or CLI reference.

Export and track security findings

Source: Export and track security findings

Use a completed Codex Security scan for either of these handoffs:

• Export creates a portable JSON, CSV, or SARIF file.
• Track findings prepares selected findings as Linear, GitHub, or Jira issues, or as one private draft GitHub Security Advisory. Codex checks for duplicates and waits for your approval before writing.

Neither workflow changes the sealed scan bundle.

Available artifact links and export formats depend on your Codex surface and installed plugin version. Check the plugin changelog before you use a format in automation.

Export a portable artifact

In the desktop app, open a completed scan from Security > Scans. Use its available artifact links to inspect report.md, findings.json, scan-manifest.json, coverage.json, or a SARIF report when present.

To create another supported format, ask Codex to export findings from the completed scan without modifying its sealed bundle:

Export the findings from [completed scan directory] as [JSON, CSV, or SARIF]. Do not modify the sealed scan bundle or upload its contents.

Choose the format that fits your destination:

Open the coverage, findings, scan manifest, Markdown report, or SARIF
artifact from a completed scan.

Select Markdown report to open report.md in your configured external editor. The editor depends on your system settings; the example below shows the generated report contents.

Review the scan scope, threat model, validated findings, and detailed report
links in the generated Markdown report.

Use the returned artifact path. If another tool needs the complete scan context, keep the original scan-manifest.json, findings.json, and coverage.json together. Exporting doesn't upload findings to a code-scanning service.

Track selected findings

Run $codex-security:track-findings with one validated finding or an explicitly selected batch of up to 25 findings from the same sealed scan. Each run uses one provider and one destination. A private draft GitHub Security Advisory accepts only one finding.

To prepare a Linear issue, send:

Use $codex-security:track-findings to prepare finding [finding ID] from
[completed scan directory] for the Linear team [team] and project [project, if
any]. Check for duplicates and show me the exact issue title, body, metadata,
and destination. Do not create or update anything until I approve that payload.

To prepare a GitHub issue, send:

Use $codex-security:track-findings to prepare finding [finding ID] from
[completed scan directory] for GitHub repository [owner/repository]. Check open
and closed issues for duplicates and show me the exact issue title, body,
metadata, repository visibility, and authenticated transport. Do not create or
update anything until I approve that payload.

To prepare a Jira issue, send:

Use $codex-security:track-findings to prepare finding [finding ID] from
[completed scan directory] for Jira project [project key] as [issue type].
Check for duplicates and show me the exact issue summary, description,
metadata, and destination. Do not create or update anything until I approve
that payload.

Jira tracking requires the Atlassian Rovo plugin in Codex. Reusing an issue requires read access; creating or updating one requires read and write access.

To prepare a private draft GitHub Security Advisory, send:

Use $codex-security:track-findings to prepare finding [finding ID] from
[completed scan directory] as a private draft GitHub Security Advisory in
[owner/repository]. Verify the sealed source revision, repository, affected
paths, package metadata, and duplicate state. Show me the exact advisory
payload, authenticated GitHub CLI identity, and disclosure warnings. Do not
create anything until I approve that payload.

Draft advisories require one finding from a sealed git_revision scan, the verified public canonical source repository, and administrator access. The workflow doesn't batch, update, publish, or close advisories. Use an approved private issue destination when the source doesn't meet those requirements.

Review the proposed write

1. Confirm the finding ID and fingerprint came from the intended sealed scan.
2. Confirm the provider, exact Linear team, GitHub repository, Jira project, or advisory repository, and the live destination visibility.
3. Review the duplicate outcome: create, reuse, update, or blocked.
4. Read the complete proposed title, body, source locations, and provider metadata. Remove exploit detail or internal evidence that the destination shouldn't expose.
5. Approve only that exact payload. A changed destination, visibility, finding set, or body requires a new preview.

Sensitive findings should go to a private destination. Creating an issue in an internal or public GitHub repository requires an explicit visibility warning and approval of the complete content. Treat a draft advisory description as eventually public and remove credentials, private evidence, and unnecessary exploit details before approval.

Review and approve external actions in the Codex conversation. Approval doesn't create a separate issue or advisory screen in the Security workbench.

Verify the tracked item

After you approve the proposed write, Codex rechecks the sealed source, destination, access, and duplicate state. For a batch, it processes findings one at a time and stops at the first uncertain result. Creation, update, or reuse is complete only after Codex reads the exact issue back and verifies its binding identifiers and content.

Keep the returned canonical issue or advisory URL with your triage record. Continue with Fix and verify a finding when the owner accepts the item for remediation.

Fix and verify security findings

Source: Fix and verify security findings

Use Codex Security to turn an accepted security finding into a focused, verified patch. You can work in the Security workbench or run the remediation workflow from a prompt, the command line, or CI/CD. Codex validates the issue and, when testing is safe and practical, adds a focused regression test that fails before the fix and passes after it. It also checks that legitimate behavior still works. If a regression test is unsafe or infeasible, Codex records the proof gap and provides the strongest repeatable validation artifact instead.

Start with one accepted finding and review the proposed patch and verification evidence. If the workflow meets your standards, process other accepted findings one at a time in separate Codex tasks or CI/CD jobs. Keeping each task scoped makes its code changes and evidence easier to review.

Fix a finding in the UI

Open an accepted finding from Findings or a completed scan in Scans. Review its evidence, then use Patch to generate, review, apply, and verify one focused fix.

1. Generate a focused patch

   Open the finding, select the Patch tab, and select Generate patch. Codex validates or reproduces the issue when feasible and writes a patch artifact without modifying the selected checkout.

2. Review the proposed diff

   Read every changed source, regression test, and validation artifact. Reject broad refactors, unrelated cleanup, or changes that weaken another security control.

3. Apply the patch locally

   Select Apply patch only after the diff is acceptable. Codex applies the exact generated patch to the working tree and records that state. Review the working-tree diff before continuing.

4. Verify the fix

   Select Verify fix. Codex reruns the original reproducer or the strongest available exploit check. If a regression test is safe and practical, Codex checks that it fails before the fix and passes after it. If the test is unsafe or infeasible, Codex records the proof gap and provides the strongest repeatable validation artifact instead. It also checks legitimate behavior, nearby bypasses, and relevant repository tests.

5. Close the finding deliberately

   Verification doesn't automatically close a finding. Review the commands, results, and remaining proof gap, then close the finding with an accurate reason or keep it open for more work.

   Review the generated security fix before applying it to your checkout.

Fix a finding from the CLI

Use the Codex CLI for an accepted finding from a scan, ticket, advisory, disclosure, security assessment, or internal review.

Install Codex Security in the CODEX_HOME that codex exec uses before you run these commands. A fresh CI runner doesn't include marketplace plugins by default.

Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.

Include the known source, sink, attacker input, impact, expected invariant, reproducer, affected files, and validation command. Codex can inspect the repository for missing technical details. It should ask before assuming a product policy or intended security invariant.

For an automated run, check out the code, make the finding report available, and install the plugin in the runner's CODEX_HOME. Then enable workspace writes and pass the prompt to codex exec:

codex exec --sandbox workspace-write 'Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.'

Scan and fix findings in CI/CD

Install Codex Security in the runner's CODEX_HOME before you invoke either skill. The commands below use the installed plugin; they don't install it.

In CI/CD, separate the change scan from remediation and require the scan to leave the checkout unchanged. Preserve the completed scan directory as a job artifact, review the findings, and start a separate Codex task or job for each finding accepted for remediation.

By default, codex exec uses a read-only sandbox. Run both the change scan and remediation with --sandbox workspace-write. The scan needs that permission to save temporary artifacts, but its prompt must still require Do not modify the checkout. Remediation needs the same permission to write the focused patch and verification evidence. See Permissions and safety.

For each scan and accepted finding:

1. Resolve the base and head revisions for the change.
2. Run $codex-security:security-diff-scan against that diff without modifying the checkout.
3. Preserve the complete scan directory and select the findings to fix.
4. Invoke $codex-security:fix-finding once for each accepted finding, passing its finding ID and completed scan directory.
5. Generate one focused patch and add a regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and use the strongest repeatable validation artifact instead.
6. Verify the original issue and legitimate behavior. Return each patch, test or fallback validation artifact, verification command, and any proof gap independently.

First, scan the change without modifying the checkout:

codex exec --sandbox workspace-write 'Use $codex-security:security-diff-scan to review changes from <base-revision> to <head-revision> for security regressions. Do not modify the checkout.'

Then fix one accepted finding from the completed scan:

codex exec --sandbox workspace-write 'Use $codex-security:fix-finding to fix finding <finding-id> from <completed-scan-directory>. Validate the finding, generate one minimal patch, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.'

Repeat the second command in an independent task or job for each remaining accepted finding. After verification, merge each patch through your normal code-review and release process. To hand findings to another team before remediation, see Export or track findings.

Improving the threat model

Source: Improving the threat model

Learn what a threat model is and how editing it improves Codex Security's suggestions.

What a threat model is

A threat model is a short security summary of how your repository works. In Codex Security, you edit it as a project overview, and the system uses it as scan context for future scans, prioritization, and review.

Codex Security creates the first draft from the code. If the findings feel off, this is the first thing to edit.

A useful threat model calls out:

• entry points and untrusted inputs
• trust boundaries and auth assumptions
• sensitive data paths or privileged actions
• the areas your team wants reviewed first

For example:

Public API for account changes. Accepts JSON requests and file uploads. Uses an internal auth service for identity checks and writes billing changes through an internal service. Focus review on auth checks, upload parsing, and service-to-service trust boundaries.

That gives Codex Security a better starting point for future scans and finding prioritization.

Improving and revisiting the threat model

If you want to improve the results, edit the threat model first. Use it when findings are missing the areas you care about or showing up in places you don't expect. The threat model changes future scan context.

Some users copy the current threat model into Codex, use a chat to improve it based on the areas they want reviewed more closely, and then paste the updated version back into the web UI.

Where to edit

To review or update the threat model, go to Codex Security scans, open the repository, and click Edit.

Threat model references

• Codex Security cloud setup covers repository setup and findings review.
• Codex Security gives the product overview.
• Codex Security cloud FAQ covers common cloud questions.

Propose security hardening

Source: Propose security hardening

Use $codex-security:propose-security-hardening to turn a collection of security evidence into structural or architectural hardening options. The workflow can analyze a completed Codex Security scan or start from supplied findings, disclosure reports, incident reviews, assessment documents, and source code.

The result is a design portfolio, not a patch, and doesn't prove that it fixes a vulnerability. Codex changes the repository only after you select an option and explicitly ask it to make that change.

Prepare the evidence

Provide the workflow with:

• A scan directory or an explicit collection of findings and reports.
• The target source tree and relevant revision or snapshot when available.
• PoCs, traces, incident evidence, or assessment material that supports the findings.
• Constraints for performance, memory, compatibility, reliability, operations, delivery time, or change scope.

The workflow uses the evidence to identify repeated broken invariants, dispersed controls, privileged choke points, weak isolation boundaries, and recurring remediation patterns. It can also conclude that local fixes are more proportionate than an architectural change.

Run the workflow

Send a prompt like:

Use $codex-security:propose-security-hardening to analyze [scan directory or finding paths] against [source tree and revision]. Develop evidence-backed structural hardening options with engineering tradeoffs, before-and-after diagrams, a migration plan, and an implementation handoff. Do not modify the repository.

Review the portfolio

A useful portfolio should:

• Connect each proposed change to concrete findings, source, and threat-model evidence.
• Describe the current design and the security invariants the new design should preserve.
• Compare distinct options, including residual risk, performance, reliability, operations, compatibility, and migration cost.
• Recommend an option only when the evidence supports it, with explicit assumptions and open questions.
• Include rollout, validation, rollback, and implementation guidance.
• Separate observed facts, inferences, and proposed design properties.

Review the evidence and tradeoffs before choosing an option. An architecture diagram or design recommendation doesn't replace validation of the original findings or the implemented fix.

Use hardening guidance from a scan

When a standard, deep, or change scan has reportable findings, Codex runs this workflow once after the detailed vulnerability reports are ready. It writes the portfolio to hardening/hardening.md, structured analysis to hardening/hardening.json, and supporting proposals or diagrams under hardening/. The scan links the portfolio from report.md.

Keep the full scan directory together so those links remain usable. To review the individual reports that inform the portfolio, see Write vulnerability reports.

Review code changes for security

Source: Review code changes for security

Run a security change review to find regressions in one Git-backed change set. Codex reviews each changed source-like file and its directly supporting code. It doesn't expand the review into a full repository audit.

To scan an entire repository instead of a specific change, see Run a security scan.

Run a manual review

In the desktop app, open Security, select Scans, and select + Scan. Choose the repository, then select Changes. Review uncommitted changes, a single commit, or a base and head revision. Deep scan isn't available for a changes scan.

You can also ask Codex to review uncommitted changes in a conversation:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

For a commit or branch range, specify both revisions when needed:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

You can also name a pull request when its base and head revisions are available in the local checkout.

Confirm the change in setup

1. Select Changes.
2. Confirm the checked-out repository, current branch, and latest commit.
3. Under Changes to review, choose:
   • Uncommitted changes for the current working tree.
   • The latest commit for a single-commit review.
   • A base and head revision for a branch or pull-request range.
4. Confirm that the summary describes the change you intended to review.
5. Select Start scan.

Codex doesn't check out another branch or switch the selected working tree. If a requested revision isn't available locally, fetch it before the review or provide a locally available base and head.

Act on findings

After reviewing the results, fix and verify an accepted finding or export and track findings.

Automate reviews in CI/CD

If you have access to the beta standalone CLI, see Run Codex Security in CI for structured JSON, a severity policy, and SARIF upload. Continue with this section to invoke the installed plugin skill through codex exec.

Run $codex-security:security-diff-scan in CI when the runner can invoke the Codex CLI without interaction. First, install the CLI without exposing the scan credential:

npm install --global @openai/codex

Install the Codex Security plugin in the CLI:

codex plugin add codex-security@openai-curated

The install command uses the public Codex CLI plugin marketplace, which can offer a different version from the hosted desktop-app catalog. Check the plugin changelog before you depend on a specific plugin version or feature in CI.

Next, provide an OpenAI API key from your CI secret store as CODEX_SECURITY_API_KEY. Expose the credential only for the scan:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

The writable sandbox lets the scan create temporary artifacts. The prompt still requires Codex to leave the source checkout unchanged.

The scan writes its output to $TMPDIR/codex-security-scans///:

The findings.json schema defines the complete structure. The schema includes these fields:

For example, this command prints one tab-separated row per finding:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

These examples assume a trusted Linux runner with Node.js and npm, Git, Python 3, jq, and the provider's command-line tools. The npm global package prefix must be writable.

Choose the example for your CI provider:

Scan results can include sensitive vulnerability details. Keep artifacts private, and publish findings only after reviewing the audience, content, and required approvals.

name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

Create a masked CODEX_SECURITY_API_KEY CI/CD variable and review the scan artifacts privately before sharing findings.

codex-security-review:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'
  variables:
    GIT_DEPTH: "0"
  script:
    - |
      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY
      export CODEX_HOME="/tmp/codex-home-$CI_JOB_ID"
      export TMPDIR="/tmp/codex-security-$CI_JOB_ID"
      export BASE_REVISION="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
      export HEAD_REVISION="${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}"
      npm install --global @openai/codex
      codex plugin add codex-security@openai-curated
      CODEX_API_KEY="$codex_security_api_key" codex exec \
        --sandbox workspace-write \
        "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."
  after_script:
    - |
      unset CODEX_SECURITY_API_KEY
      scan_root="/tmp/codex-security-$CI_JOB_ID/codex-security-scans"
      if [ -d "$scan_root" ]; then
        tar -czf codex-security-artifacts.tar.gz -C "$scan_root" .
      fi
  artifacts:
    when: always
    paths:
      - codex-security-artifacts.tar.gz

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    fetchDepth: 0

  - bash: |
      set -euo pipefail
      export CODEX_HOME="$AGENT_TEMPDIRECTORY/codex-home"
      npm install --global @openai/codex
      codex plugin add codex-security@openai-curated
    displayName: Install Codex Security

  - bash: |
      set -euo pipefail
      export CODEX_HOME="$AGENT_TEMPDIRECTORY/codex-home"
      export TMPDIR="$AGENT_TEMPDIRECTORY/codex-security"
      export HEAD_REVISION="$SYSTEM_PULLREQUEST_SOURCECOMMITID"
      export BASE_REVISION="$(git merge-base HEAD^1 "$HEAD_REVISION")"
      CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
        --sandbox workspace-write \
        "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."
    displayName: Review code changes
    condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True'))
    env:
      CODEX_SECURITY_API_KEY: $(CODEX_SECURITY_API_KEY)

  - publish: $(Agent.TempDirectory)/codex-security/codex-security-scans
    artifact: codex-security-review
    condition: always()

For Azure Repos, configure a Build validation branch policy to run the pipeline on pull requests.

pipeline {
  agent { label 'linux' }
  stages {
    stage('Codex Security review') {
      when {
        allOf {
          changeRequest()
          expression { !env.CHANGE_FORK?.trim() }
        }
      }
      steps {
        sh '''#!/usr/bin/env bash
          set -euo pipefail
          export CODEX_HOME="/tmp/codex-home-$BUILD_TAG"
          export TMPDIR="/tmp/codex-security-$BUILD_TAG"
          mkdir -p "$TMPDIR"
          git fetch --no-tags origin "$CHANGE_TARGET"
          target="$(git rev-parse FETCH_HEAD)"
          git fetch --no-tags origin "$CHANGE_BRANCH"
          git rev-parse FETCH_HEAD > "$TMPDIR/head"
          git merge-base "$target" "$(cat "$TMPDIR/head")" > "$TMPDIR/base"
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated
        '''
        withCredentials([string(credentialsId: 'codex-security-api-key', variable: 'CODEX_SECURITY_API_KEY')]) {
          sh '''#!/usr/bin/env bash
            set +x
            set -euo pipefail
            export CODEX_HOME="/tmp/codex-home-$BUILD_TAG"
            export TMPDIR="/tmp/codex-security-$BUILD_TAG"
            export HEAD_REVISION="$(cat "$TMPDIR/head")"
            export BASE_REVISION="$(cat "$TMPDIR/base")"
            CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
              --sandbox workspace-write \
              "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."
          '''
        }
      }
      post {
        always {
          sh '''#!/usr/bin/env bash
            set -euo pipefail
            scan_root="/tmp/codex-security-$BUILD_TAG/codex-security-scans"
            if [ -d "$scan_root" ]; then
              tar -czf codex-security-artifacts.tar.gz -C "$scan_root" .
            fi
          '''
          archiveArtifacts artifacts: 'codex-security-artifacts.tar.gz', allowEmptyArchive: true
        }
      }
    }
  }
}

The examples skip forked pull requests. Run credentialed jobs only from a protected pipeline definition and only for contributors trusted with the scan credential. Archive codex-security-scans to keep the structured findings, manifest, coverage artifacts, report.md, and its linked findings/ and hardening/ outputs together. Start with advisory results and review coverage and runtime before making the job a required check.

For API-key handling and sandbox controls, see Non-interactive mode. If your organization permits the Codex GitHub Action, it can install the CLI at runtime, but you must still install the plugin first and point the action's codex-home input at the same CODEX_HOME.

Run a Codex Security scan

Source: Run a Codex Security scan

Start with a standard Codex Security scan for an initial review or a routine repository or component assessment. It runs the full scan workflow once.

For a more thorough assessment, review the results and then run a deep scan. Deep scans take longer and search more extensively.

Choose the scan area

In the desktop app, open Security, select Scans, and select + Scan. Choose an existing repository or another folder, then select Codebase.

Scan the whole repository when you need broad coverage and the repository is a reasonable review unit. For a monorepo, choose one folder when a service, package, or component has a clear owner and security boundary.

You can also start a scan from a Codex conversation:

Use $codex-security:security-scan to scan this repository for security vulnerabilities.

To focus that conversation on a particular folder, identify the component:

Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.

For a large monorepo, start with one meaningful product or service boundary.

Configure the scan

For the best scan quality, use gpt-5.6-sol with xhigh reasoning effort.

1. Select Codebase and leave Deep scan off.
2. Confirm the selected repository, current branch, and latest revision.
3. Set Scan area to the entire repository or choose one folder.
4. Choose a model and reasoning effort.
5. Open Additional context only when it changes the review. Useful context names attacker-controlled inputs, trust boundaries, sensitive actions, or a specific area to prioritize.
6. Select Start scan.

Add SECURITY.md to the repository root for persistent security guidance. Describe the threat model, security invariants, reportable finding criteria, exclusions, and severity context. Add nested SECURITY.md files for directory-specific guidance. When policies conflict, the file closest to the code takes precedence. Codex Security treats these files as policy context, not executable instructions.

Use AGENTS.md for supported build and validation commands and other repository-specific instructions.

Let the phases complete

A scan runs these phases in order:

1. Threat modeling identifies assets, entry points, trust boundaries, and security invariants.
2. Finding discovery reviews the requested code for plausible broken controls and source-to-sink paths.
3. Validation tests or otherwise checks each candidate and records evidence or proof gaps.
4. Impact and path analysis evaluates each candidate's realistic paths, impact, and severity.
5. Reporting records validated findings, coverage, and scan metadata. Detailed per-finding reports are optional for standard scans.
6. Structural hardening, when available, analyzes the finding set and creates design guidance.
7. Finalization validates the structured scan contract and generates report.md, including links to any detailed reports or hardening guidance.

The workbench shows the active scan phase and any progress the plugin reports. Select View activity to inspect the Codex task. Wait for the complete result instead of judging early candidates or stopping because one phase takes longer than another.

Review the completed scan

Review the result in this order:

1. Confirm the target, revision, and scan area.

2. Read reviewed surfaces and every explicit deferred or follow-up area.

3. For each finding, inspect the root control or sink, attacker-controlled input, validation method, remaining uncertainty, realistic reachability, severity rationale, and proposed remediation.

4. Dismiss findings whose evidence doesn't support the claimed path or impact.

5. Select one accepted finding before starting a fix.

   Review the finding's severity, validation status, root cause, and attack path.

Reopen a previous scan

Open Security, then select a saved scan from Scans to review its findings, coverage, and available report artifacts. To assess the latest code, start a new scan for the same repository. The new scan doesn't replace the earlier scan or its artifacts.

Use the results

Use the Security workbench to review findings, coverage, and follow-up areas without inspecting raw JSON. Open report.md when available for the readable entry point to the complete scan directory. Keep the directory together when you share or archive it: the report links to detailed reports in findings/ and structural hardening guidance in hardening/ when those optional artifacts are available.

Behind the workspace, each scan preserves scan-manifest.json, findings.json, and coverage.json for automation and integrations. You normally don't need to open these files yourself.

For portable artifacts or external issue tracking, see Export or track findings.

Next step

After you accept a finding, use Fix and verify a finding to generate and review one bounded patch. Don't ask Codex to fix every finding from a scan in one chat.

Run a deep security scan

Source: Run a deep security scan

Run a deep scan when you need a more thorough review and can allow for a longer runtime. Deep scans search a repository more extensively and can reduce variability between runs.

Start with a standard scan to check your scope and results. Then use a deep scan when you need a more thorough assessment.

Choose between standard and deep scans

Configure deep-scan runtime

To control a deep scan's concurrency and duration, create or edit ~/.codex/codex-security/config.toml. If you set CODEX_HOME, use $CODEX_HOME/codex-security/config.toml instead.

For example, this profile runs a shorter scan with limited concurrency:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10

Lower values can reduce scan time and token use but may miss findings. Configuration changes apply to new deep scans, not scans already in progress.

Start the deep scan

In the desktop app, open Security, select Scans, and select + Scan. Choose a repository or another folder, select Codebase, and turn on Deep scan. The scan covers the entire selected repository or folder.

You can also start a repository-wide deep scan from a Codex conversation:

Use $codex-security:deep-security-scan to run a deep security scan of this repository.

For one component in a monorepo, identify the folder explicitly:

Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.

For a scoped deep scan in the desktop app, select the folder as the codebase. The scan covers the entire selected folder.

Confirm setup and preflight

For the best scan quality, use gpt-5.6-sol with xhigh reasoning effort.

1. Select Codebase and turn on Deep scan.
2. Confirm that the repository or selected folder is the code you intended to scan.
3. Choose a model and reasoning effort.
4. Open Additional context for concrete attack vectors, sensitive application areas, or repository context that the code can't reveal.
5. Select Start scan.
6. Review any setup or capability warning before you approve a configuration change.

Deep scans require delegated workers. If the current runtime doesn't meet the capability requirements, use a standard scan or try again when enough capacity is available.

Discovery workers inherit your selected model and reasoning settings. Follow the saved scan from Scans, or select View activity to inspect its Codex task. Check the plugin changelog before you update the plugin or start a long-running scan.

Track the active deep-scan phase and inspect its Codex activity before
reviewing the completed result.

Review the result

Deep scans use the same saved scan details and complete scan directory as standard scans. Open the completed scan in Scans or review its findings in Findings. When available, report.md links to one detailed report for each reportable finding and a structural hardening portfolio when findings remain. Keep the linked findings/ and hardening/ directories with the report when sharing or archiving the result.

Review the coverage summary before the findings. Even a deep scan has limits, so check deferred surfaces and remaining proof gaps before drawing a conclusion. For a finding you accept, continue with Fix and verify a finding.

To review a pull request, commit, branch range, or local patch, use Review code changes. A deep scan never substitutes for the diff-focused workflow.

Run bulk security scans

Source: Run bulk security scans

Use npx @openai/codex-security bulk-scan to review repositories in one campaign. Discover repositories from your personal GitHub account or an organization, or provide a CSV that pins every repository to an exact Git revision.

The @openai/codex-security package is public. Running scans requires Codex Security access. Follow the CLI quickstart to install the CLI and sign in.

Choose a repository source

Both workflows save progress, preserve per-repository results, and let you resume a campaign after an interruption.

Discover GitHub repositories

Sign in with GitHub CLI:

gh auth login

Start an interactive bulk scan:

npx @openai/codex-security bulk-scan

The CLI guides you through these steps:

1. Choose your personal GitHub account or an organization.
2. Review repositories active within the last 90 days.
3. Search the repository list and select repositories to scan.
4. Choose a directory for scan results.
5. Review the selected repositories and confirm the campaign.

Discovery excludes archived repositories and forks. The CLI records the exact default-branch commit for each selected repository in /repositories.csv. No scans start until you confirm the selection.

To use GitHub Enterprise Server, first sign in to your GitHub host:

gh auth login --hostname github.example.com

Set GH_HOST when you start repository discovery:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

Interactive discovery requires a terminal. For CI, containers, or a prepared repository list, use a CSV inventory instead.

Create a repository CSV

Create a CSV with one row for each repository and pinned revision:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

The CSV supports these columns:

To find a local repository's full commit SHA, run:

git -C /path/to/repository rev-parse HEAD

Run a campaign from CSV

Pass the CSV and a private output directory outside the repositories:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

--workers controls concurrent repository scans and defaults to 4. It does not set the number of discovery workers within each deep scan; configure those limits through [deep_scan]. Use --mode deep to select deep scanning for rows without their own mode. Each CSV row can still choose its own scan mode and repository scope.

The CLI checks out each pinned revision, scans the selected target, records the result, and removes the temporary repository checkout. A repository counts as complete only when its scan has complete coverage and all required result artifacts exist.

Share security context and instructions

Add architecture documents, threat models, or security policies to every scan with --knowledge-base. Repeat the flag for more files or directories:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

To add shared scan instructions or run a follow-up after each completed scan, provide prompt files:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

The CLI appends each repository's CSV prompt after the shared scan instructions. Follow-up instructions run in the same authenticated session only after a validated scan has complete coverage. Prompt file paths resolve from your current directory.

Choose a model and reasoning effort

Bulk scans use gpt-5.6-sol with xhigh reasoning effort by default. To choose another model and effort for a CSV campaign:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

The same options work during interactive repository discovery:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Supported effort levels are minimal, low, medium, high, and xhigh.

To use OpenRouter or Fireworks, set OPENROUTER_API_KEY or FIREWORKS_API_KEY, respectively, and specify --provider and --model. For credentials and examples, see OpenRouter or Fireworks setup or Amazon Bedrock setup.

Review campaign results

The output directory contains the pinned campaign, an append-only results ledger, and separate artifacts for each repository and attempt:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json records the repositories, pinned revisions, scopes, scan modes, and shared or repository-specific instructions in the campaign.
• results.jsonl records each repository attempt, its status, artifact directory, and any available cost or error details.
• report.md provides a readable report for one repository attempt.
• findings.json and coverage.json record that attempt's findings and reviewed scope.

Export one completed repository scan when you need a portable result:

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Results can contain source excerpts and vulnerability details. Keep the output directory private, outside scanned repositories, and subject to an appropriate retention policy.

Resume a campaign

Run the original command with the same CSV and output directory:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

The CLI resumes unfinished repository scans and skips completed ones. Scans with incomplete coverage aren't retried. Their results remain available, and the command exits with code 2.

Don't change the repository inventory or scan and follow-up instructions for an existing output directory. The CLI checks the pinned manifest and rejects a different campaign. Use a new output directory when you change repositories, revisions, scopes, scan modes, or shared or repository-specific instructions.

Retry repository errors

Use --max-attempts to retry a repository after a temporary checkout or scan error:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

The default is one attempt per repository. Every attempt receives its own receipt and artifact directory. Retries cover checkout errors, scan failures, and missing required artifacts. Completed scans with incomplete coverage aren't retried.

Bulk scans use these exit codes:

Run bulk scans in Docker

The Codex Security repository includes a hardened Compose configuration for automated CSV campaigns on a Linux Docker host. The host must support unprivileged user namespace creation.

Keep the repository CSV, scan results, and sign-in state mounted in persistent directories. Supply OpenAI credentials through the environment or a secret manager. For private GitHub repositories, provide GH_TOKEN or GITHUB_TOKEN the same way.

Run the image with the mounted CSV and output directory:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Use the same mounted CSV and output directory to resume the campaign. For GitHub Enterprise Server, set CODEX_SECURITY_GIT_HOST to your GitHub host.

For every available flag, see the bulk-scan command reference. For common questions about scan coverage and findings, see the CLI FAQ.

Run Codex Security in CI

Source: Run Codex Security in CI

Run the Codex Security CLI in CI to review the exact changes in a pull request or merge request, keep findings and coverage, and optionally fail the check at a chosen severity. Start with advisory results, review scan quality and runtime, then add a severity policy that fits your repository.

Install the public @openai/codex-security package. Running scans still requires Codex Security access.

This guide includes examples for GitHub Actions and GitLab CI/CD. The same scan and export commands work in other CI systems.

Prepare the workflow

Store an OpenAI API key in your CI provider's secret store as CODEX_SECURITY_API_KEY.

Map this secret directly to the scan step's OPENAI_API_KEY environment variable. Keep the credential scoped to the scan process and use --auth api-key to select it explicitly.

The runner needs:

• Node.js 22.13.0 or later.
• Python 3.10 or later.
• The published @openai/codex-security package, installed outside the repository checkout.
• The pull-request or merge-request head and base history so Git can calculate the merge base.

Add the GitHub Actions workflow

For private or internal repositories, enable GitHub Code Security before you upload SARIF.

Create .github/workflows/codex-security.yml. Before checking out the pull request, install @openai/codex-security under $RUNNER_TEMP/codex-security so the trusted executable is available at $RUNNER_TEMP/codex-security/node_modules/.bin/codex-security:

name: Codex Security scan

on:
  pull_request:

jobs:
  codex-security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: "26"

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
        with:
          python-version: "3.14"

      - name: Install Codex Security
        run: |
          set -euo pipefail
          npm install \
            --prefix "$RUNNER_TEMP/codex-security" \
            --ignore-scripts \
            --no-audit \
            --no-fund \
            @openai/codex-security

      - name: Verify Codex Security
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
        run: |
          set -euo pipefail
          test -x "$CODEX_SECURITY_BIN"
          "$CODEX_SECURITY_BIN" --version

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan the pull request
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
        run: |
          set -euo pipefail
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          "$CODEX_SECURITY_BIN" scan . \
            --diff "$BASE_REVISION" \
            --head "$HEAD_SHA" \
            --auth api-key \
            --output-dir "$SCAN_DIR" \
            --json > "$RUNNER_TEMP/codex-security.json"

      - name: Export SARIF
        id: export-sarif
        if: always()
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
          SARIF_FILE: ${{ runner.temp }}/codex-security.sarif
        run: |
          set -euo pipefail
          if test -f "$SCAN_DIR/scan-manifest.json"; then
            "$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
              --export-format sarif \
              --source-root "$GITHUB_WORKSPACE" \
              --output "$SARIF_FILE"
            echo "available=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload SARIF
        if: always() && steps.export-sarif.outputs.available == 'true'
        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
        with:
          sarif_file: ${{ runner.temp }}/codex-security.sarif
          ref: refs/pull/${{ github.event.pull_request.number }}/head
          sha: ${{ github.event.pull_request.head.sha }}
          category: codex-security

      - name: Preserve scan results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: codex-security-results
          path: |
            ${{ runner.temp }}/codex-security-results
            ${{ runner.temp }}/codex-security.json
          if-no-files-found: warn
          retention-days: 7

The workflow checks out the pull-request head, calculates its merge base, and scans the committed changes between those revisions. Full history keeps the target exact. persist-credentials: false keeps the repository token out of the checked-out Git configuration. Installing the CLI before checkout and running its absolute path keeps repository-controlled executables away from the scan credential. --auth api-key explicitly selects the scoped API key. The scan saves its history in a writable state directory outside the repository.

--json writes one complete JSON document to stdout, so the workflow can save it directly. Progress, completion summaries, and errors remain on stderr. This differs from codex exec --json, which emits a JSON Lines event stream.

The export step reads a completed, sealed scan and writes SARIF. It leaves the Codex runtime and credentials untouched. Scan artifacts can contain vulnerable source snippets, evidence, and remediation details. Choose access controls and a short retention window appropriate for your repository.

Add the GitLab CI/CD pipeline

GitLab can ingest SARIF 2.1.0 reports on GitLab Ultimate 19.2 or later. Add a masked and hidden CODEX_SECURITY_API_KEY CI/CD variable before you run the pipeline.

Add the security stage and Codex Security job to the root .gitlab-ci.yml. Keep any existing stages and jobs in the file. The example scans merge-request changes by default. Set CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH to "true" to also scan the complete default branch:

variables:
  CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH: "false"

stages:
  - test
  - security

codex-security:
  stage: security
  image: node:26-bookworm-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'
      variables:
        CODEX_SECURITY_SCAN_SCOPE: "diff"
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH == "true"'
      variables:
        CODEX_SECURITY_SCAN_SCOPE: "full"
  variables:
    GIT_DEPTH: "0"
    CODEX_SECURITY_CLI_DIR: "/tmp/codex-security-cli"
  before_script:
    - |
      set -eu
      apt-get update -qq
      apt-get install -y -qq --no-install-recommends \
        ca-certificates \
        git \
        python3 \
        ripgrep
      npm install \
        --prefix "$CODEX_SECURITY_CLI_DIR" \
        --ignore-scripts \
        --no-audit \
        --no-fund \
        @openai/codex-security
      export CODEX_SECURITY_BIN="$CODEX_SECURITY_CLI_DIR/node_modules/.bin/codex-security"
      test -x "$CODEX_SECURITY_BIN"
      "$CODEX_SECURITY_BIN" --version
  script:
    - |
      set -eu
      if test -z "${CODEX_SECURITY_API_KEY:-}"; then
        echo "Set the CODEX_SECURITY_API_KEY CI/CD variable." >&2
        exit 2
      fi

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY

      case "${CODEX_SECURITY_SCAN_SCOPE:-}" in
        diff)
          BASE_SHA="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
          HEAD_SHA="$CI_COMMIT_SHA"
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          set -- --diff "$BASE_REVISION" --head "$HEAD_SHA"
          echo "Scanning committed changes from $BASE_REVISION to $HEAD_SHA."
          ;;
        full)
          set -- --mode standard
          echo "Scanning the complete default branch at $CI_COMMIT_SHA."
          ;;
        *)
          echo "Unsupported Codex Security scan scope: ${CODEX_SECURITY_SCAN_SCOPE:-unset}" >&2
          exit 2
          ;;
      esac

      export CODEX_SECURITY_STATE_DIR="/tmp/codex-security-state-$CI_JOB_ID"
      SCAN_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      JSON_FILE="/tmp/codex-security-$CI_JOB_ID.json"
      SARIF_FILE="/tmp/codex-security-$CI_JOB_ID.sarif"

      install -d -m 700 "$CODEX_SECURITY_STATE_DIR" "$SCAN_DIR"

      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          "$@" \
          --auth api-key \
          --output-dir "$SCAN_DIR" \
          --json > "$JSON_FILE"
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      install -d -m 700 codex-security-artifacts/results
      cp -R "$SCAN_DIR"/. codex-security-artifacts/results/
      if test -s "$JSON_FILE"; then
        cp "$JSON_FILE" codex-security-artifacts/codex-security.json
      fi
      printf '%s\n' "$scan_exit" > codex-security-artifacts/scan-exit-code.txt

      export_exit=0
      if test -f "$SCAN_DIR/scan-manifest.json"; then
        set +e
        "$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
          --export-format sarif \
          --source-root "$CI_PROJECT_DIR" \
          --output "$SARIF_FILE"
        export_exit="$?"
        set -e
        if test -s "$SARIF_FILE"; then
          cp "$SARIF_FILE" codex-security-artifacts/codex-security.sarif
        fi
      fi

      if test "$scan_exit" -ne 0; then
        exit "$scan_exit"
      fi
      exit "$export_exit"
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/codex-security.sarif

By default, the job runs only for merge requests from branches in the same project, so fork pipelines don't receive the scan credential. Set CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH to "true" at the group, project, or pipeline level to also run a standard full scan on the default branch. Full scans take longer and cost more than diff scans.

GIT_DEPTH: "0" provides the history needed to calculate the merge base from CI_MERGE_REQUEST_DIFF_BASE_SHA and CI_COMMIT_SHA for merge-request scans.

The job installs the CLI under /tmp, runs it by absolute path, and exposes the API key only to the scan process. artifacts: when: always preserves the SARIF report when the scan fails, while artifacts:access: maintainer limits access to detailed scan results.

Changes to .gitlab-ci.yml can expose CI/CD variables, so review pipeline changes before running the job. If you protect CODEX_SECURITY_API_KEY, GitLab makes it available only for same-project merge requests between protected branches and only when the user can access the target branch.

Choose a severity policy

Both examples are report-only because they omit --fail-on-severity. Once you are ready to make findings affect the check, add a threshold to the scan command:

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --fail-on-severity high

The supported thresholds are critical, high, medium, and low. A threshold includes findings at that severity and above.

The scan step uses these exit codes:

A scan with partial or unknown coverage returns 2, even without a severity policy. The CLI still writes its available findings and coverage. Review the deferred areas in coverage.json before treating the check as conclusive.

Retry with an existing result directory

Use a fresh runner directory for each CI job. For a persistent or self-hosted runner, preserve an earlier result with --archive-existing:

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --archive-existing

The command archives the earlier results and starts with an empty scan directory.

Troubleshoot a CI scan

• Unknown Git ref or unexpected diff: Fetch the base and head history, calculate the merge base, and pass both revisions explicitly.
• Protected or non-empty output directory: Choose a private directory outside the enclosing Git worktree. Use --archive-existing when the directory already contains results.
• Missing credentials: Confirm that CODEX_SECURITY_API_KEY is available to the trusted workflow or pipeline and mapped directly to the scan process's OPENAI_API_KEY environment variable.
• Scan history error: Set CODEX_SECURITY_STATE_DIR to a writable directory outside the repository.
• Python setup error: Confirm that the runner uses Python 3.10 or later.
• Incomplete coverage: Review coverage.json, including deferred surfaces and open questions, then rerun with an appropriate target or environment.
• SARIF export error: Confirm that the scan completed and the full scan directory is available. Export validates the sealed artifacts before writing SARIF.
• SARIF upload error: For GitHub Actions, confirm that your organization turned on GitHub Code Security for the repository and the workflow grants actions: read, contents: read, and security-events: write. For GitLab CI/CD, confirm that the project uses GitLab Ultimate 19.2 or later and that the job uploads a SARIF 2.1.0 file through artifacts:reports:sarif.

For every command, flag, artifact, and output field, see the CLI reference. For an interactive plugin-based CI review, see Review code changes for security.

Security Review

Source: Security Review

Codex Security Review is available in research preview. It is available to ChatGPT Enterprise, Business, Edu, and Pro customers; it is not available on Plus. During the introductory period, Codex Security Review does not consume ChatGPT credits. Usage limits may apply.

Codex Security Review is an additional review for customers that want to pay particular attention to security issues in pull requests.

Codex Security Review goes deeper than Code Review on security-specific risks by analyzing the pull request diff, supporting repository context, and configured threat models or security guidance. Code Review can also identify security-related issues as part of its general review, so you may see occasional overlap between findings.

Before you start

To configure automatic Codex Security Review, you need:

• Codex Security Review research preview access for your workspace
• Codex cloud set up with a connected GitHub repository
• GitHub push or admin permission for the repository settings

An existing Codex Security scan is optional.

Configure Codex Security Review

1. Go to Codex settings.
2. Under Repository preferences, choose which pull requests get Codex Security Review:
   • Follow personal lets each contributor opt in with their personal Codex Security Review settings.
   • Review all PRs applies to every pull request in the repository.
   • Review team PRs, when available, applies to pull requests opened by members of your ChatGPT workspace, not members of a GitHub team.
3. Choose when Codex Security Review runs:
   • On PR open runs independently when a pull request is opened.
   • Every push runs independently after new commits are pushed.
   • Whenever code review runs requires Code Review and runs Codex Security Review alongside it.

Add threat-model context

You can configure a threat model to give Codex context about your application's assets, trust boundaries, security assumptions, and repository-specific risks. If the repository has an existing Codex Security scan configuration, you can use its threat model. Otherwise, provide the path to a threat model file checked into the repository. If you do not specify a source, Codex regenerates the threat model for every review.

Set reporting thresholds

By default, automatic Codex Security Reviews report High and Critical findings, while manually requested reviews report Medium, High, and Critical findings. You can change the minimum severity independently for automatic and manual reviews, and add path-based overrides.

Findings posted to a pull request inherit that pull request's GitHub visibility. Anyone who can view the pull request can view those findings, including on public repositories or pull requests from contributors outside your workspace. Choose reporting thresholds carefully for repositories where pull request comments may be broadly visible. The reporting threshold controls what Codex posts to GitHub; the full Codex Security Review report remains in Codex.

Request a Codex Security Review

To request a Codex Security Review manually, add this comment to a pull request:

@codex security review

Codex reacts while the review is running, then posts findings that meet your manual reporting threshold directly on the pull request. Open the associated Codex task and select the Security Report tab to view the full report, including severity, attack path, supporting evidence, validation, and remediation guidance. If no issues meet the reporting threshold, Codex does not post findings to the pull request.

Related docs

• Review GitHub pull requests with Codex explains Code Review and the GitHub integration.
• Codex Security gives the product overview.
• Codex Security cloud setup explains repository scans and findings review.
• Improving the threat model explains how to tune repository context.

Triage a backlog

Source: Triage a backlog

Use $codex-security:triage-finding to review existing security findings against the current repository. This workflow performs a read-only static analysis: Codex treats each finding as an unproven claim and inspects repository evidence without executing the code.

Run this workflow from a Codex project scoped to the repository you want to assess. Codex must be able to read the repository's source code. Jira and Linear connectors can provide finding data, while GitHub findings require authenticated GitHub REST access. Neither replaces access to the source code.

Under the hood, Codex starts from the cited code or version information. It traces the claimed attacker-controlled source, relevant security controls, dangerous sink, and reachable path. It also checks the product surface and trust boundary, looks for contradictory evidence, and records proof gaps. Codex then returns one verdict per finding and ranks the findings that need action or further review.

This differs from $codex-security:validation, which can build or run code, create a focused test or proof of concept, or exercise a real interface to reproduce or disprove a finding. Use triage to classify and rank an existing backlog. Use validation when runtime evidence could resolve a finding that static evidence leaves uncertain.

Backlog triage starts from existing findings. To search the repository for new vulnerabilities, run a security scan. Triage doesn't modify the repository or implement fixes.

Choose the findings to triage

You can supply one finding or a collection from these sources:

Codex keeps one result for every supplied finding, in input order, so each source finding stays traceable. It doesn't merge or drop findings that look like duplicates.

Run read-only triage

For pasted findings or local artifacts, send a prompt like:

Use $codex-security:triage-finding to triage these existing security findings against this repository:

[Paste the findings or provide the artifact path.]

For Jira or Linear issues, identify the issue set and keep the source system read-only:

Use $codex-security:triage-finding to import and triage the security findings from [Jira or Linear issue URLs, identifiers, or query] against this repository.
Do not change the source issues.

For GitHub findings, name the repository and source:

Use $codex-security:triage-finding to import and triage [code scanning, Dependabot vulnerabilities and malware, security advisories and private vulnerability reports, or all] from [owner/repository] against this repository.

To use the GitHub repository attached to the current Codex project, specify only the finding source:

Use $codex-security:triage-finding to import and triage [code scanning, Dependabot vulnerabilities and malware, security advisories and private vulnerability reports, or all] from GitHub against this repository. Use the GitHub repository attached to the current Codex project.

The workflow proceeds in this order:

1. Collect and organize the findings

   Codex retrieves any requested issue or GitHub content, preserves source identifiers and references, and creates one triage item per input. It builds the complete item list before assigning verdicts.

2. Confirm the repository context

   Codex resolves the current repository and revision when available. It reads SECURITY.md when present so supported versions, trusted inputs, product boundaries, and out-of-scope surfaces inform the assessment.

3. Inspect the static evidence

   For each finding, Codex traces the claimed attacker-controlled source, relevant security control, vulnerable sink, reachable path, and supported security boundary. It records supporting evidence, evidence against the claim, and proof gaps.

4. Assign verdicts and ranks

   Codex assigns a verdict and confidence to every finding. It ranks confirmed and needs_review findings by exploitability in separate queues.

Review the results

Exploitability ranks use positive integers starting at 1, independently within each verdict queue. This keeps remediation priorities separate from unresolved review work. Rank 1 is the most exploitable confirmed finding or the highest-priority needs_review finding in that result set. The rank isn't a scanner severity score, and not_actionable findings aren't ranked.

For each finding, review:

• the rationale for the verdict and rank
• supporting evidence and evidence against the claim
• open questions and remaining proof gaps
• the affected location and component
• the product surface and source trust level
• the recommended next step
• the $codex-security:fix-finding handoff, when the finding is confirmed

Triage is complete when every supplied finding has one result, Codex preserves its source identifier, and any uncertainty is explicit. Jira, Linear, and other backlog records remain unchanged unless you ask Codex to write back after reviewing the triage results.

Next steps

• confirmed: After a person accepts the finding for remediation, use $codex-security:fix-finding to fix and verify it. Triage prepares a prompt-ready handoff but doesn't invoke the skill automatically.

• needs_review: If running code can resolve the proof gap, use $codex-security:validation to perform bounded dynamic validation. Pass the finding claim, affected locations, preconditions, static evidence, and proof gaps from the triage result:

  Use $codex-security:validation to dynamically validate finding [triage item ID or source ID] from the backlog triage result. Use the strongest realistic, bounded method, record exactly what was tested, and preserve any remaining proof gaps.
  

  Unlike triage, validation may build or run code, create a focused test or proof of concept, or exercise a real interface. Review the proposed commands before approving them and keep Codex approval and security policies in place.

• needs_review: If the finding depends on product policy or deployment context, answer the listed open questions before changing code.

• not_actionable: Keep the evidence with your triage record. Codex doesn't automatically close or update the source ticket.

• To look for vulnerabilities beyond the supplied backlog, run a security scan.

Use the Codex Security workbench

Source: Use the Codex Security workbench

The Security workbench brings your scans, findings, and repositories together in the Codex desktop app. Codex performs scan analysis in a regular task, while the workbench keeps the scan and its results available when you return.

Install and enable the Codex Security plugin, then select Security in the desktop-app sidebar.

If Security doesn't appear, confirm that the plugin is installed and enabled. Update the desktop app and plugin if needed, and check whether your workspace administrator allows the plugin.

Start a scan

For the best scan quality, use gpt-5.6-sol with xhigh reasoning effort.

1. Open Scans and select + Scan.

2. Select an existing repository or choose another folder.

3. Choose Codebase to scan a repository or Changes to review a Git-backed change.

4. For a standard codebase scan, select the entire repository or a folder.

5. For a deep scan, first select the repository or folder as the codebase, then turn on Deep scan. Deep scans review the entire selected codebase.

6. For a changes scan, select uncommitted changes, a commit, or a revision range. Deep scan isn't available for changes scans.

7. Choose a model and reasoning effort. Open Additional context to describe relevant attack vectors, focus areas, or other security context.

8. Select Start scan.

   Choose a repository and configure a scan in the Security workbench.

See Run a security scan, Run a deep security scan, or Review code changes for security for details about each scan type.

Follow scan progress

The scan page shows the current phase and any scan progress the plugin reports. For a standard scan, phases include threat modeling, discovery, validation, impact and path analysis, reporting, and finalization.

Select View activity to open the Codex task that runs the scan. You can leave the workbench and return to Scans without losing a saved scan. To stop work intentionally, open the scan and select Stop scan.

When the scan completes, open its results to review the target, revision, findings, coverage, and available report artifacts.

Review findings, severity, scan coverage, and artifacts after a scan
completes.

Review findings across scans

Open Findings to inspect saved findings across repositories and scans. Search or filter the list, then select a finding to review its summary, source evidence, validation, and impact.

Use Summary for the finding details and Patch when you want to generate, review, apply, or verify a focused fix. See Fix and verify security findings for the remediation workflow.

The Findings tab shows findings from saved Codex Security scans. Imported tickets and other existing security issues remain part of the separate backlog triage workflow.

Inspect repository history

Open Repositories to browse available repositories and folders. Select a repository to inspect its scan history, latest scanned revision, and open findings. From repository details, open a previous scan or view the findings associated with that repository.

If a repository has no scans, start a scan from its details or select + Scan in the workbench.

Start a scan from a conversation

You can also ask Codex to run the installed Codex Security plugin in a regular conversation. Scans that use the shared plugin workbench appear in Scans, so you can return to their progress and results from the Security workbench.

For terminal-based scans and automation, see the Codex Security CLI quickstart.

Write vulnerability reports

Source: Write vulnerability reports

Use $codex-security:vulnerability-writeup to create a self-contained report for each distinct vulnerability. You can start from Codex Security scan results or use supplied findings, disclosure notes, PoCs, and source code directly. A Codex Security scan isn't required.

Prepare the evidence

Provide the workflow with:

• The findings, disclosure notes, or assessment documents to review.
• The target source tree and affected revision or release.
• Existing PoCs, logs, traces, screenshots, or diagnostic output.
• Fix commits or diffs when available.
• The authorization boundary for any testing.

Source access is important because Codex checks each claim against the affected code before writing the final report. If the source or affected revision isn't available, decide whether an explicitly labeled, lower-confidence report is useful before proceeding.

Run the workflow

Send a prompt like:

Use $codex-security:vulnerability-writeup to create one self-contained report for each distinct vulnerability in [input paths]. Verify the claims against [source path and revision], preserve or improve the supplied PoCs, and write the reports to [output directory]. Do not test public or production systems.

Codex inventories the supplied material, groups reports that describe the same root cause and vulnerable path, and creates one report directory per distinct vulnerability. Each directory contains a descriptively named Markdown report and a poc/ directory when supporting PoC files are available.

Review each report

Before distributing a report, confirm that it:

• Traces the bug from the attacker-controlled entry point to the broken security invariant and impact.
• Distinguishes verified behavior from hypotheses and unresolved constraints.
• Includes focused source excerpts with paths, functions, and the affected revision.
• Includes usable PoC source, build or run instructions, representative output, and safety limitations when a PoC is practical.
• Uses portable paths and doesn't depend on internal storage or local absolute paths.

Never test a public or production target unless you have explicit authorization for that exact target.

Use reports from a scan

When a deep or change scan has reportable findings, Codex runs this workflow once per finding during final reporting. Detailed reports are optional for standard scans. When Codex generates detailed reports, it writes each report to findings//.md, stores supporting files under findings//poc/, and links the report from report.md.

Keep the complete scan directory together when sharing or archiving a scan. To look for improvements that address patterns across the reports, continue with Propose security hardening.

Agent approvals & security

Source: Agent approvals & security

Codex helps protect your code and data and reduces the risk of misuse.

This page covers how to operate Codex safely, including sandboxing, approvals, and network access. If you are looking for Codex Security, the product for scanning connected GitHub repositories, see Codex Security.

By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

For a high-level explanation of how sandboxing works across the ChatGPT desktop app, Codex CLI, and IDE extension, see sandboxing. For a broader enterprise security overview, see the Codex security white paper.

Sandbox and approvals

Codex security controls come from two layers that work together:

• Sandbox mode: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.
• Approval policy: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).

Codex uses different sandbox modes depending on where you run it:

• Codex cloud: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.
• Codex CLI / IDE extension: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

In the Auto preset (for example, --sandbox workspace-write --ask-for-approval on-request), Codex can read files, make edits, and run commands in the working directory automatically.

Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to read-only mode with the /permissions command.

Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

Network access

For the ChatGPT desktop app, Codex CLI, or IDE extension, the default workspace-write sandbox mode keeps network access turned off unless you enable it in your configuration:

[sandbox_workspace_write]
network_access = true

Network isolation

Network access is controlled through destination rules that apply to scripts, programs, and subprocesses spawned by commands. When command network access is already enabled, turn on the network_proxy feature to constrain that traffic to the network policy you configure.

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

For a one-off CLI session, use the boolean shorthand when you only need the toggle, and the table form when you also set policy options:

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

The feature changes how enabled network access is enforced; it does not grant network access by itself. Use sandbox_workspace_write.network_access with workspace-write config to decide whether commands have network access at all:

• Network off + network_proxy on: network stays off, and the feature does nothing.
• Network on + network_proxy off: network stays on with unrestricted direct outbound access.
• Network on + network_proxy on: network stays on, and outbound traffic is constrained by the configured network policy.

Admin-managed experimental_network requirements are separate from the user feature toggle. They can configure and start sandboxed networking without features.network_proxy, but they do not turn on network access when the active sandbox keeps it off. See Managed configuration for the administrator-side requirements.toml shape.

Network policy

Domain rules are allowlist-first:

• Exact hosts match only themselves.
• *.example.com matches subdomains such as api.example.com, but not example.com.
• **.example.com matches both the apex and subdomains.
• A global * allow rule matches any public host that is not denied. Treat * as broad network access and prefer scoped rules when you can.
• deny always wins over allow, and global * is only valid for allow rules.

Local and private destinations

By default, allow_local_binding = false blocks loopback, link-local, and private destinations:

• Specific exceptions: add an exact local IP literal or localhost allow rule when a command needs one local target.
• Broader access: set allow_local_binding = true only when you intentionally want wider local/private reach.
• Wildcards: wildcard rules do not count as explicit local exceptions.
• Resolved addresses: hostnames that resolve to local/private IPs stay blocked even if they match the allowlist.

DNS rebinding protections

Before allowing a hostname, Codex performs a best-effort DNS and IP classification check:

• Lookups that fail or time out are blocked.
• Hostnames that resolve to non-public addresses are blocked.
• The check reduces DNS rebinding risk, but it does not eliminate it. Preventing rebinding completely would require pinning resolved IPs through the transport layer.

If hostile DNS is in scope, enforce egress controls at a lower layer too.

Dangerous settings

Two settings deliberately widen the trust boundary:

• dangerously_allow_non_loopback_proxy = true can expose proxy listeners beyond loopback.
• dangerously_allow_all_unix_sockets = true bypasses the Unix socket allowlist.

Use them only in tightly controlled environments. When Unix socket proxying is enabled, listeners stay loopback-only even if non-loopback binding was requested, so sandboxed networking does not become a remote bridge into local daemons.

network_proxy is off by default. When you enable it:

You can also control the web search tool without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using --yolo or another full access sandbox setting, web search defaults to live results. Use --search or set web_search = "live" to allow live browsing, or set it to "disabled" to turn the tool off:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

Set web_search = "indexed" when external web access should be gated by the search index. Use caution when enabling network access or web search in Codex. Prompt injection can cause the agent to fetch and follow untrusted instructions.

Defaults and recommendations

• On launch, Codex detects whether the folder is version-controlled and recommends:
  • Version-controlled folders: Auto (workspace write + on-request approvals)
  • Non-version-controlled folders: read-only
• Depending on your setup, Codex may also start in read-only until you explicitly trust the working directory (for example, via an onboarding prompt or /permissions).
• The workspace includes the current directory and temporary directories like /tmp. Use the /status command to see which directories are in the workspace.
• To accept the defaults, run codex.
• You can set these explicitly:
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

Protected paths in writable roots

In the default workspace-write sandbox policy, writable roots still include protected paths:

• /.git is protected as read-only whether it appears as a directory or file.
• If /.git is a pointer file (gitdir: ...), the resolved Git directory path is also protected as read-only.
• /.agents is protected as read-only when it exists as a directory.
• /.codex is protected as read-only when it exists as a directory.
• Protection is recursive, so everything under those paths is read-only.

Run without approval prompts

You can disable approval prompts with --ask-for-approval never or -a never (shorthand).

This option works with all --sandbox modes, so you still control Codex's level of autonomy. Codex makes a best effort within the constraints you set.

If you need Codex to read files, make edits, and run commands with network access without approval prompts, use --sandbox danger-full-access (or the --dangerously-bypass-approvals-and-sandbox flag). Use caution before doing so.

For a middle ground, approval_policy = { granular = { ... } } lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, request_permissions prompts, and skill-script approvals.

Automatic approval reviews

By default, approval requests route to you:

approvals_reviewer = "user"

Automatic approval reviews apply when approvals are interactive, such as approval_policy = "on-request" or a granular approval policy. Set approvals_reviewer = "auto_review" to route eligible approval requests through a reviewer agent before Codex runs the request:

approval_policy = "on-request"
approvals_reviewer = "auto_review"

For the full reviewer lifecycle, trigger conditions, configuration precedence, and failure behavior, see Auto-review.

The reviewer evaluates only actions that already need approval, such as sandbox escalations, blocked network requests, request_permissions prompts, or side-effecting app and MCP tool calls. Actions that stay inside the sandbox continue without an extra review step.

The reviewer policy checks for data exfiltration, credential probing, persistent security weakening, and destructive actions. Low-risk and medium-risk actions can proceed when policy allows them. The policy denies critical-risk actions. High-risk actions require enough user authorization and no matching deny rule. Prompt-build, review-session, and parse failures fail closed. Timeouts are surfaced separately, but the action still does not run.

The default reviewer policy is in the open-source Codex repository. Enterprises can replace its tenant-specific section with guardian_policy_config in managed requirements. Local [auto_review].policy text is also supported, but managed requirements take precedence. For setup details, see Managed configuration.

In the ChatGPT desktop app, these reviews appear as automatic review items with a status such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also include a risk level and user-authorization assessment for the reviewed request.

Automatic review uses extra model calls, so it can add to Codex usage. Admins can constrain it with allowed_approvals_reviewers.

Common sandbox and approval combinations

For non-interactive runs, use codex exec --sandbox workspace-write; Codex keeps older codex exec --full-auto invocations as a deprecated compatibility path and prints a warning.

With --ask-for-approval untrusted, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

Configuration in config.toml

For the broader configuration workflow, see Config basics, Advanced Config, and the Configuration Reference.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

You can also save presets as profile files, then select them with codex --profile profile-name:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

Test the sandbox locally

To see what happens when a command runs under the Codex sandbox, use these Codex CLI commands:

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

The sandbox command is also available as codex debug, and the platform helpers have aliases (for example codex sandbox seatbelt and codex sandbox landlock).

OS-level sandbox

Codex enforces the sandbox differently depending on your OS:

• macOS uses Seatbelt policies and runs commands using sandbox-exec with a profile (-p) that corresponds to the --sandbox mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing /System) to preserve common tool compatibility.
• Linux uses bwrap plus seccomp by default.
• Windows uses the Linux sandbox implementation when running in Windows Subsystem for Linux 2 (WSL2). WSL1 was supported through Codex 0.114; starting in 0.115, the Linux sandbox moved to bwrap, so WSL1 is no longer supported. When running natively on Windows, Codex uses a Windows sandbox implementation.

If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the WSL guide.

When running natively on Windows, configure the native sandbox mode in config.toml:

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

See the Windows setup guide for details.

When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid bwrap, or seccomp operations that Codex needs.

In that case, configure your Docker container to provide the isolation you need, then run codex with --sandbox danger-full-access (or the --dangerously-bypass-approvals-and-sandbox flag) inside the container.

Run Codex in Dev Containers

If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

Use the Codex secure devcontainer example as a reference implementation. The example installs Codex, common development tools, bubblewrap, and firewall-based outbound controls.

Devcontainers provide substantial protection, but they do not prevent every attack. If you run Codex with --sandbox danger-full-access or --dangerously-bypass-approvals-and-sandbox inside the container, a malicious project can exfiltrate anything available inside the devcontainer, including Codex credentials. Use this pattern only with trusted repositories, and monitor Codex activity as you would in any other elevated environment.

The reference implementation includes:

• an Ubuntu 24.04 base image with Codex and common development tools installed;
• an allowlist-driven firewall profile for outbound access;
• VS Code settings and extension recommendations for reopening the workspace in a container;
• persistent mounts for command history and Codex configuration;
• bubblewrap, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

To try it:

1. Install Visual Studio Code and the Dev Containers extension.
2. Copy the Codex example .devcontainer setup into your repository, or start from the Codex repository directly.
3. In VS Code, run Dev Containers: Open Folder in Container... and select .devcontainer/devcontainer.secure.json.
4. After the container starts, open a terminal and run codex.

You can also start the container from the CLI:

devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

The example has three main pieces:

• .devcontainer/devcontainer.secure.json controls container settings, capabilities, mounts, environment variables, and VS Code extensions.
• .devcontainer/Dockerfile.secure defines the Ubuntu-based image and installed tools.
• .devcontainer/init-firewall.sh applies the outbound network policy.

The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

Inside the container, choose one of these modes:

• Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for bwrap to create the inner sandbox.
• If the container is your intended security boundary, run Codex with --sandbox danger-full-access inside the container so Codex does not try to create a second sandbox layer.

Version control

Codex works best with a version control workflow:

• Work on a feature branch and keep git status clean before delegating. This keeps Codex patches easier to isolate and revert.
• Prefer patch-based workflows (for example, git diff/git apply) over editing tracked files directly. Commit frequently so you can roll back in small increments.
• Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

Monitoring and telemetry

Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

Overview

• Codex turns off OTel export by default to keep local runs self-contained.
• When enabled, Codex emits structured log events covering chats, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.
• Codex tags exported events with service.name (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

Enable OTel (opt-in)

Add an [otel] block to your Codex configuration (typically ~/.codex/config.toml), choosing an exporter and whether to log prompt text.

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

• exporter = "none" leaves instrumentation active but doesn't send data anywhere.
• To send events to your own collector, pick one of:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex batches events and flushes them on shutdown. Codex exports only telemetry produced by its OTel module.

Event categories

Representative event types include:

• codex.conversation_starts (model, reasoning settings, sandbox/approval policy)
• codex.api_request (attempt, status/success, duration, and error details)
• codex.sse_event (stream event kind, success/failure, duration, plus token counts on response.completed)
• codex.websocket_request and codex.websocket_event (request duration plus per-message kind/success/error)
• codex.user_prompt (length; content redacted unless explicitly enabled)
• codex.tool_decision (approved/denied, source: configuration vs. user)
• codex.tool_result (duration, success, output snippet)

Associated OTel metrics (counter plus duration histogram pairs) include codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event, and codex.tool.call (with corresponding .duration_ms instruments).

For the full event catalog and configuration reference, see the Codex configuration documentation on GitHub.

Security and privacy guidance

• Keep log_user_prompt = false unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.
• Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.
• Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.
• Review local data retention settings (for example, history.persistence / history.max_bytes) if you don't want Codex to save session transcripts under CODEX_HOME. See Advanced Config and Configuration Reference.
• If you run the CLI with network access turned off, OTel export can't reach your collector. To export, allow network access in workspace-write mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.
• Review events periodically for approval/sandbox changes and unexpected tool executions.

OTel is optional and designed to complement, not replace, the sandbox and approval protections described above.

Managed configuration

Enterprise admins can configure Codex security settings for their workspace in Managed configuration. See that page for setup and policy details.

Auto-review

Source: Auto-review

Auto-review replaces manual approval at the sandbox boundary with a separate reviewer agent. The main Codex agent still runs inside the same sandbox, with the same approval policy and the same network and filesystem limits. The difference is who reviews eligible escalation requests.

Auto-review only applies when approvals are interactive. In practice, that means approval_policy = "on-request" or a granular approval policy that still surfaces the relevant prompt category. With approval_policy = "never", there is nothing to review.

How auto-review works

At a high level, the flow is:

1. The main agent works inside read-only or workspace-write.
2. When it needs to cross the sandbox boundary, it requests approval.
3. If approvals_reviewer = "auto_review", Codex routes that approval request to a separate reviewer agent instead of stopping for a person.
4. The reviewer decides whether the action should run and returns a rationale.
5. If the action is approved, execution continues. If it is denied, the main agent is instructed to find a materially safer path or stop and ask the user.

Auto-review is a reviewer swap, not a permission grant. It does not expand writable_roots, enable network access, or weaken protected paths. It only changes how Codex handles actions that already need approval.

When it triggers

Auto-review evaluates approval requests that would otherwise pause for a human. These include:

• Shell or exec tool calls that request escalated sandbox permissions.
• Network requests blocked by the current sandbox or policy.
• File edits outside the allowed writable roots.
• MCP or app tool calls that require approval based on their tool annotations or configured approval mode.
• Computer Use access to a new website or domain.

Auto-review does not run for routine actions already allowed inside the sandbox. If a command can run under the active sandbox_mode, or a tool call stays within the allowed policy, the main agent continues without review.

Computer Use is a separate case. App approvals for Computer Use still surface directly to the user, so Auto-review does not replace those app-level prompts.

What auto-review blocks

At a high level, Auto-review is designed to block actions such as:

• sending private data, secrets, or credentials to untrusted destinations
• probing for credentials, tokens, cookies, or session material
• broad or persistent security weakening
• destructive actions with significant risk of irreversible damage

The exact policy lives in the open-source Codex repository: policy_template.md and policy.md. That policy can be customized per enterprise with guardian_policy_config or per user with local [auto_review].policy.

What the reviewer sees

The reviewer is itself a Codex agent with a narrower job than the main agent: decide whether a specific boundary-crossing action should run.

The reviewer sees a compact transcript plus the exact approval request. That typically includes user messages, surfaced assistant updates, relevant tool calls and tool outputs, and the action now being proposed for approval. It can also perform read-only checks to gather missing context, but it does so rarely.

Hidden assistant reasoning is not included. Auto-review sees retained chat items and tool evidence, not private chain-of-thought.

Denials and failure behavior

An explicit denial is not treated like an ordinary sandbox error. Codex returns the review rationale to the main agent and adds a stronger instruction:

• Do not pursue the same outcome via workaround, indirect execution, or policy circumvention.
• Continue only with a materially safer alternative.
• Otherwise, stop and ask the user.

Codex also applies a rejection circuit breaker per turn. In the current open-source implementation, Auto-review interrupts the turn after 3 consecutive denials or 10 denials within a rolling window of the last 50 reviews in the same turn.

Any non-denial resets the consecutive-denial counter. When the breaker trips, Codex emits a warning and aborts the current turn with an interrupt rather than letting the agent loop on more escalation attempts.

Timeouts are surfaced separately from explicit denials, and the main agent is informed that a timeout alone is not proof that the action is unsafe.

There is also an explicit override path for denied actions. In the current open-source TUI, run /approve to open the Auto-review Denials picker, then select one recent denied action to approve for one retry. Codex records up to 10 recent denials per task. That approval is narrow: it applies to the exact denied action, not similar future actions; it is recorded for one retry in the same context; and the retry still goes through Auto-review. Under the hood, Codex injects a developer-scoped approval marker for that exact action. The reviewer then sees that explicit user override as context, but it still follows policy and can deny again if policy says the user cannot overwrite that class of denial.

Configuration

For setup details, see Managed configuration.

The default reviewer policy is in the open-source Codex repository: core/src/guardian/policy.md. Enterprises can replace its tenant-specific section with guardian_policy_config in managed requirements. Individual users can also set a local [auto_review].policy in their config.toml, but managed requirements take precedence:

[auto_review]
policy = """
YOUR POLICY GOES HERE
"""

To customize the policy, copy the whole default policy wording first, then iterate based on your individual risk profile.

Reduce review volume without weakening security

Auto-review works best when the sandbox already covers your common safe workflows. If too many mundane actions need review, fix the boundary first instead of teaching the reviewer to approve noisy escalations forever.

In practice, the highest-leverage changes are:

• Add narrow writable_roots for scratch directories or neighboring repos you intentionally use.
• Add narrowly scoped prefix rules. Prefer precise command prefixes such as ["cargo", "test"] or ["pnpm", "run", "lint"] over broad patterns such as ["python"] or ["curl"]. Broad rules often erase the very boundary Auto-review is meant to guard.

Auto-review session transcripts are retained under ~/.codex/sessions by default, so you can ask Codex to analyze past traffic there before changing policy or permissions.

Limits

Auto-review improves the default operating point for long-running agentic work, but it is not a deterministic security guarantee.

• It only evaluates actions that ask to cross a boundary.
• It can still make mistakes, especially in adversarial or unusual contexts.
• It should complement, not replace, good sandbox design, monitoring, and organization-specific policy.

For the research rationale and published evaluation results, see the Alignment Research post on Auto-review.

Cyber Safety

Source: Cyber Safety

GPT-5.3-Codex is the first model we are treating as High cybersecurity capability under our Preparedness Framework, which requires additional safeguards. These safeguards include training the model to refuse clearly malicious requests like stealing credentials.

In addition to safety training, automated classifier-based monitors detect signals of suspicious cyber activity and route high-risk traffic to a less cyber-capable model (GPT-5.2). We expect a very small portion of traffic to be affected by these mitigations, and are working to refine our policies, classifiers, and in-product notifications.

Why we’re doing this

Over recent months, we’ve seen meaningful gains in model performance on cybersecurity tasks, benefiting both developers and security professionals. As our models improve at cybersecurity-related tasks like vulnerability discovery, we’re taking a precautionary approach: expanding protections and enforcement to support legitimate research while slowing misuse.

Cyber capabilities are inherently dual-use. The same knowledge and techniques that underpin important defensive work — penetration testing, vulnerability research, high-scale scanning, malware analysis, and threat intelligence — can also enable real-world harm.

These capabilities and techniques need to be available and easier to use in contexts where they can be used to improve security. Our Trusted Access for Cyber pilot enables individuals and organizations to continue using models for potentially high-risk cybersecurity activity without disruption.

How it works

Developers and security professionals doing cybersecurity-related work or similar activity that could be mistaken by automated detection systems may have requests rerouted to GPT-5.2 as a fallback. We expect a very small portion of traffic to affected by mitigations, and are actively working to calibrate our policies and classifiers.

The latest alpha version of the Codex CLI includes in-product messaging for when requests are rerouted. This messaging will be supported in all clients in the next few days.

Accounts impacted by mitigations can regain access to GPT-5.3-Codex by joining the Trusted Access program below.

We recognize that joining Trusted Access may not be a good fit for everyone, so we plan to move from account-level safety checks to request-level checks in most cases as we scale these mitigations and strengthen cyber resilience.

Trusted Access for Cyber

We are piloting "trusted access" which allows developers to retain advanced capabilities while we continue to calibrate policies and classifiers for general availability. Our goal is for very few users to need to join Trusted Access for Cyber.

To use models for potentially high-risk cybersecurity work:

• Users can verify their identity at chatgpt.com/cyber
• Enterprises can request trusted access for their entire team by default through their OpenAI representative

Security researchers and teams who may need access to even more cyber-capable or permissive models to accelerate legitimate defensive work can express interest in our invite-only program⁠. Users with trusted access must still abide by our Usage Policies⁠ and Terms of Use⁠.

False positives

Legitimate or non-cybersecurity activity may occasionally be flagged. When rerouting occurs, the responding model will be visible in API request logs and in with an in-product notice in the CLI, soon all surfaces. If you're experiencing rerouting that you believe is incorrect, please report via /feedback for false positives.

Permissions

Source: Permissions

{/_ vale Microsoft.FirstPerson = NO _/}

Permission modes

Permissions control how ChatGPT (in the desktop app) and Codex (in the CLI or IDE) handle local actions, such as editing files, running commands, and using the internet. The mode you choose sets the boundary for what ChatGPT can do on its own and what needs review.

For most work, start with Ask for approval. It lets ChatGPT work within the current workspace and pauses before reaching beyond that boundary.

Select different modes below to understand how each one works.

Enable modes

When you're using the ChatGPT desktop app for the first time, you need to enable modes in application settings.

Ask for approval is always available. To add Approve for me (called Auto-review in settings) or Full access to the permissions menu, open Settings > General in the ChatGPT desktop app, then turn on the mode under Permissions. Enabling a mode makes it available in the menu; it doesn't select the mode or change an existing chat.

The available modes can depend on your local configuration and your organization's requirements. A mode that isn't allowed appears disabled.

How permissions work

Two controls work together:

• The sandbox defines which files and network resources ChatGPT can access.
• Approvals determine when ChatGPT pauses before an action or sends the request to automatic review.

Changing who reviews a request doesn't expand the sandbox. For example, Approve for me keeps the same workspace boundary as Ask for approval; it sends requests to cross that boundary to automatic review.

Use the permissions control below the composer in the ChatGPT desktop app or IDE extension.

In the CLI, enter /permissions. For technical details, see Sandbox, automatic review, or permission profiles.

Permissions

Source: Permissions

Beta. Permission profiles are under active development and may change.

Permission profiles do not compose with the older sandbox settings. Configure either default_permissions and [permissions], or sandbox_mode / sandbox_workspace_write, but not both. If sandbox_mode appears in any loaded config file, you pass --sandbox, or the selected config profile sets sandbox_mode, Codex uses those older sandbox settings instead of default_permissions.

Managed allowed_permission_profiles is the exception: it makes Codex use permission profiles. Remove older settings such as sandbox_mode and [sandbox_workspace_write] before deploying a managed profile allowlist. For a mixed-version enterprise rollout, you can keep the managed allowed_sandbox_modes requirement as a temporary compatibility constraint until every client runs Codex 0.138.0 or later.

Permission profiles let you apply least-privilege boundaries to local commands Codex runs on your behalf. A profile is a named policy that combines filesystem rules, which define what commands can read or write, with network rules, which define which destinations commands can reach.

Use profiles to give Codex enough access for the current chat without granting broad access to your machine or network. For example, a read-only profile can let Codex inspect a project without editing it, while a write-capable profile can limit edits to selected workspace roots.

Local permission profiles are supported on macOS, Linux, WSL, and native Windows. See Scope and enforcement for platform-specific details and caveats.

For Codex cloud network settings, see Internet Access.

Define and select a profile

Codex includes three built-in permission profiles:

• :read-only keeps local command execution read-only.
• :workspace allows writes inside the active workspace roots and system temp directories.
• :danger-full-access removes local sandbox restrictions and should be used only when that broad access is intentional.

Create a named profile under [permissions.], then set the top-level default_permissions key to that profile name or to one of the built-ins above. In this example, project-edit is a user-defined profile name, not a built-in value.

Enterprise administrators can define profiles and restrict which profiles users may select through managed requirements.toml. Once allowed_permission_profiles is present, omitted profiles are denied, including omitted built-ins and profiles added in future Codex versions. See Control available permission profiles for the recommended managed configuration.

Custom profiles use two related concepts:

• [permissions..workspace_roots] adds concrete directories that should count as workspace roots for that profile.
• [permissions..filesystem.":workspace_roots"] defines the filesystem rules Codex applies inside every effective workspace root: the current session's runtime workspace roots plus the profile-defined roots above.

Profiles also use the normal config-layer model. Higher-precedence layers can add or replace entries under the same profile name without restating the whole profile.

For example, an organization-level config and a user-level config can extend the same profile independently:

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

When server is active, both workspace roots participate in the effective profile.

default_permissions = "project-edit"

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

This profile:

• Reads the minimal runtime paths common developer tools need.
• Applies the same workspace-root rules to the current session and the profile-defined roots.
• Keeps IDE-adjacent settings such as .devcontainer/ read-only under each root.
• Denies matching environment files with a glob rule.
• Allows network access only through the configured domain policy.

Inside an active profile, narrower deny rules stay in force even when a broader path is readable or writable. For example, a profile can make workspace roots writable while still setting a matching .env path to deny.

Extend a profile

Use extends when a profile is mostly the same as a built-in or another named profile. Prefer extending a built-in profile over starting from scratch so baseline protections carry forward. Extending :workspace, for example, keeps the workspace root's .codex directory read-only unless you explicitly override it. Set the parent once, then add or override only the rules that differ.

default_permissions = "project-edit"

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

This profile starts with :workspace, keeps matching .env files denied, and allows requests to api.openai.com. A profile can extend :read-only, :workspace, or another named profile. It cannot extend :danger-full-access; Codex also rejects unknown parents and inheritance cycles.

Configuration spec

Filesystem permissions

Filesystem entries use read, write, or deny:

More specific entries override broader entries. When two entries target the same path, deny takes precedence over write, and write takes precedence over read.

This precedence lets a profile describe a broad working area first, then carve out files or directories that should stay unreadable:

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

In this example, the workspace root stays writable, .devcontainer/ stays readable without becoming writable, and matching environment files remain unavailable to sandboxed commands.

A more specific path can also reopen a narrower subtree inside a broader deny:

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Supported path forms:

On native Windows, home-relative paths can also use backslashes, such as ~\work.

Use :root only when a profile intentionally needs broad read coverage:

[permissions.audit.filesystem]
":root" = "read"

Use nested entries under :workspace_roots to scope access to workspace-root relative subpaths:

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

Nested subpaths must stay inside their workspace root. Parent traversal such as ../other-repo is rejected.

Deny reads with exact paths or globs

Use deny for files or subtrees that Codex should not read, even when a broader profile rule grants access nearby. Exact paths work well for stable locations such as ~/.ssh. Glob patterns work better when a profile needs to cover a family of sensitive files whose exact locations vary across repositories.

When a glob sits under :workspace_roots, Codex interprets it relative to each effective workspace root. For example:

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

This rule denies reads for matching .env files found beneath each runtime or profile-defined workspace root. Use it when you want to preserve normal workspace writes while keeping environment files, generated secrets, or similar credential-bearing files unreadable.

deny glob patterns are supported as deny-read rules. read or write globs are less portable on Linux, WSL, and native Windows sandboxing, so prefer exact paths or subtree rules such as "docs/**" = "read" when possible.

On Linux, WSL, and native Windows, an unbounded ** deny-read pattern may need bounded pre-expansion before the sandbox starts. Set glob_scan_max_depth when you use an unbounded pattern such as "**/*.env" = "deny":

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth must be at least 1. Higher values scan deeper before sandbox startup, which can add startup work on Linux, WSL, and native Windows. If you prefer not to use bounded expansion, enumerate explicit depths such as *.env, */*.env, and */*/*.env.

Add reusable workspace roots to the profile when the same rules should apply to more than the current session root:

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

When this profile is active, Codex applies the :workspace_roots rules to the current session's runtime workspace roots and to each enabled profile-defined workspace root.

On native Windows, drive-letter paths such as D:\work and UNC paths such as \\server\share are supported as absolute paths.

Network permissions

Set enabled = true to allow network access for the selected profile:

[permissions.project-edit.network]
enabled = true

When network access is enabled, Codex uses full network behavior by default. Most profiles should also define domain rules:

[permissions.project-edit.network.domains]
"example.com" = "allow"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over allow

The network sandbox proxy binds to local listeners by default:

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

Leave these listener settings at their defaults unless you are integrating with a specific runtime. The dangerously_* network keys are escape hatches for specialized environments and should not be used for ordinary local development.

Local and private networks

Codex applies a local/private-network guard by default as a defense against DNS rebinding and accidental access to local services. To intentionally allow a literal local target, allowlist the exact host or IP literal:

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

Set allow_local_binding = true only when the profile must reach allowlisted hostnames that resolve to local or private addresses:

[permissions.project-edit.network]
enabled = true
allow_local_binding = true

[permissions.project-edit.network.domains]
"localhost" = "allow"

Unix sockets

Unix socket proxying is a local escape hatch for tools such as Docker. Use it sparingly:

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Use deny to reject a socket path, including an inherited allow entry. Denied socket paths are omitted from the effective allowlist.

When Unix sockets are enabled, keep proxy listeners bound to loopback addresses.

Migrate from older sandbox settings

Permission profiles replace the older combination of sandbox_mode and sandbox_workspace_write when you want one reusable profile to describe both filesystem and network behavior. Use one system or the other for a session, not both.

Suggested starting points:

• For a read-only workflow, use the built-in :read-only profile or define a custom profile with read access only where needed.
• For workspace editing, use the built-in :workspace profile or define a custom profile that writes through :workspace_roots and adds only the extra temp or cache paths the workflow needs.
• For unrestricted local execution, use :danger-full-access only when you intentionally want the broadest local access model.

Profiles describe the local default posture for a session. Organization-managed requirements can still add restrictions that user configuration should not broaden. See Managed configuration for admin-enforced filesystem and network constraints.

Scope and enforcement

Permission profiles define the boundaries for local sandboxed command execution. Use them together with approval policies and the separate controls for connectors, MCP servers, the built-in browser, Computer Use, and Codex cloud.

What profiles control

• Local command execution: Permission profiles govern sandboxed commands that run on your machine. Connectors, MCP servers, browser or computer-use surfaces, Codex cloud environment settings, and approved escalations use their own controls.
• Filesystem writes: A write-capable profile can create persistent changes. Treat writes to scripts, build steps, package manager hooks, shell startup files, and shared directories as sensitive because later tools or users can execute those files outside the original sandbox context.
• Outbound destinations: Network domain rules constrain where sandboxed command traffic can go through the network proxy. They do not determine whether an allowed destination is trustworthy, and wildcard allow rules stay broad.
• Local services: Local and private network targets are blocked by default. Allowlisting localhost, private IPs, Unix sockets, or setting allow_local_binding = true explicitly opens access to local services.

How enforcement works

• On macOS, Codex uses Seatbelt sandbox profiles. If the selected policy cannot be enforced by the platform sandbox, Codex refuses to run the command instead of silently running it unsandboxed.
• On Linux and WSL, Codex uses bubblewrap and seccomp, with Landlock available for compatibility fallback paths. The strongest enforcement path depends on user namespaces and kernel support; restricted container hosts can force compatibility paths, and unsupported split policies are refused.
• On native Windows, elevated sandboxing is strongest because it can use dedicated lower-privilege sandbox users, filesystem permission boundaries, and firewall rules. unelevated sandboxing is a fallback with weaker network isolation and cannot enforce every split read/write carveout, so unsupported policies are refused. Use WSL when you need the Linux sandbox model.

Operational guidance

Choose the narrowest profile that still lets the task complete, especially when you grant writes or outbound network access. Keep approval policy, secret handling, and allow rules aligned with that access level.

Common profiles

Read-only with network allowlist

default_permissions = "readonly-net"

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"

File access limited to workspace

Here is an example of a permission profile that will make your workspace folders writable by Codex while denying reads to the rest of the filesystem (with limited exceptions, as determined by :minimal).

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

Workspace write without network

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

Workspace write with public web access

default_permissions = "workspace-net"

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

Use the global "*" allow rule only when you intend to allow public network access. Deny rules can narrow a broad allowlist.

Sandbox

Source: Sandbox

The sandbox is the boundary that lets the agent act autonomously without giving it unrestricted access to your machine. When a local chat runs commands in the ChatGPT desktop app, Codex CLI, or IDE extension, those commands run inside a constrained environment instead of running with full access by default.

That environment defines what the agent can do on its own, such as which files it can modify and whether commands can use the network. When a task stays inside those boundaries, the agent can keep moving without stopping for confirmation. When it needs to go beyond them, the approval flow takes over.

Sandboxing and approvals are different controls that work together. The sandbox defines technical boundaries. The approval policy decides when the agent must stop and ask before crossing them.

What the sandbox does

The sandbox applies to spawned commands, not just to built-in file operations. If the agent runs tools like git, package managers, or test runners, those commands inherit the same sandbox boundaries.

Codex uses platform-native enforcement on each OS. The implementation differs between macOS, Linux, WSL2, and native Windows, but the idea is the same across surfaces: give the agent a bounded place to work so routine tasks can run autonomously inside clear limits.

Why it matters

The sandbox reduces approval fatigue. Instead of asking you to confirm every low-risk command, the agent can read files, make edits, and run routine project commands within the boundary you already approved.

It also gives you a clearer trust model for agentic work. You aren't just trusting the agent's intentions; you are trusting that the agent is operating inside enforced limits. That makes it easier to let the agent work independently while still knowing when it will stop and ask for help.

Getting started

The default permissions mode applies sandboxing automatically.

Prerequisites

On macOS, sandboxing works out of the box using the built-in Seatbelt framework.

On Windows, Codex uses the native Windows sandbox when you run in PowerShell and the Linux sandbox implementation when you run in WSL2.

On Linux and WSL2, install bubblewrap with your package manager first:

sudo apt install bubblewrap

sudo dnf install bubblewrap

Codex uses the first bwrap executable it finds on PATH. If no bwrap executable is available, Codex falls back to a bundled helper, but that helper requires support for unprivileged user namespace creation. Installing the distribution package that provides bwrap keeps this setup reliable.

Codex surfaces a startup warning when bwrap is missing or when the helper can't create the needed user namespace. On distributions that restrict this AppArmor setting, prefer loading the bwrap AppArmor profile so bwrap can keep working without disabling the restriction globally.

Ubuntu AppArmor note: On Ubuntu 25.04, installing bubblewrap from Ubuntu's package repository should work without extra AppArmor setup. The bwrap-userns-restrict profile ships in the apparmor package at /etc/apparmor.d/bwrap-userns-restrict.

On Ubuntu 24.04, Codex may still warn that it can't create the needed user namespace after bubblewrap is installed. Copy and load the extra profile:

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

apparmor_parser -r loads the profile into the kernel without a reboot. You can also reload all AppArmor profiles: