Guide

OpenAI Codex: CLI, desktop app, IDE extension and setup

Updated

On this page

OpenAI Codex is a coding agent you can run in four places. These are the Codex CLI in your terminal, the ChatGPT desktop app, an IDE extension, and Codex Cloud at chatgpt.com/codex. You sign in with a ChatGPT account or an OpenAI API key. Local clients share the same MCP server configuration in ~/.codex/config.toml, and Codex reads project instructions from AGENTS.md. Orbtile shows every Codex session on a Logitech MX Creative Keypad or a phone.

Logitech MX Creative Keypad running Orbtile with a Codex session waiting for approval

OpenAI Codex surfaces: CLI, desktop app, IDE and cloud

SurfaceWhere it runsHow to startCore workflows
Codex CLI (codex)macOS, Linux and Windows terminalscodex for the terminal UI, or codex exec for scripts and CITerminal coding loops, sandboxed commands and non-interactive automation
ChatGPT desktop appmacOS, Windows and LinuxOpen the app, or run codex appParallel projects, Git worktrees, terminal, browser, file previews, plugins, skills and scheduled tasks
Codex IDE extensionVS Code, VS Code Insiders, Cursor and WindsurfThe Codex icon, or Codex: Open Codex SidebarPrompts with open files and selections, focused diffs and hand-off to Codex web
Built-in IDE integrationsXcode and JetBrains IDEsThe IDE's own integrationEditor-native Codex workflows
Codex Cloud (chatgpt.com/codex)Cloud environments run by OpenAIWork in > CloudBackground tasks that continue while your computer is asleep
Codex on mobileChatGPT mobile appCodex in the mobile appStart, guide, approve and review tasks on a connected computer

Working in the Codex IDE extension

The extension's marketplace ID is openai.chatgpt. In VS Code, Cursor or Windsurf, choose the Codex icon. If it is hidden, run Codex: Open Codex Sidebar from the Command Palette. Xcode and JetBrains IDEs provide their own integrations instead.

  • Reference open files, selected code and recent chats from the composer.
  • Read a summary, inspect a focused diff and follow up in the same chat.
  • Create Git checkpoints before and after a task so you can revert changes.
  • Connect Codex web when a task needs more time and room.

See Codex app vs Codex CLI: desktop app and terminal compared.

Install and authenticate OpenAI Codex on macOS, Linux and Windows

Install the Codex CLI

The openai/codex repository is licensed under the Apache-2.0 License. On macOS or Linux, run the shell installer. On Windows, use PowerShell:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The installers download from https://releases.openai.com/codex by default and fall back to GitHub Releases. To force GitHub Releases, set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM to false:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

You can also install with npm or Homebrew, or download an executable from a GitHub Release:

npm install -g @openai/codex
brew install --cask codex

Then run codex to get started. See OpenAI Codex CLI: install, commands, config.toml and codex exec.

Set up the ChatGPT desktop app on Windows and WSL2

Install the app from the Microsoft Store or with winget. If PowerShell blocks scripts, OpenAI suggests the RemoteSigned execution policy. Check Microsoft's guide before you change it.

winget install --id 9PLM9XGG6VKS -s msstore
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

By default, the app uses the Windows-native Codex agent. It supports a native Windows sandbox when the agent runs in PowerShell. You can choose a default editor for Open, such as Visual Studio or VS Code. You can also pick a terminal: PowerShell, Command Prompt, Git Bash or WSL.

To run the agent in WSL2, switch it in Settings and restart the app. WSL1 was supported through Codex 0.114. From Codex 0.115, the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported.

The Windows app uses %USERPROFILE%\.codex. To share settings, sign-in and sessions with the CLI in WSL, point CODEX_HOME at that folder:

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

Git may not be detected in projects opened from \\wsl$. Store the project on a Windows drive and open it in WSL through /mnt/<drive>/.... See Install Codex CLI on Windows: PowerShell, npm, sandbox and WSL.

Sign in with ChatGPT or an OpenAI API key

The app, the CLI and the IDE extension accept two sign-in methods. Sign in with ChatGPT for subscription access on Plus, Pro, Business, Edu and Enterprise plans. Or use an API key for usage-based access. Codex Cloud requires signing in with ChatGPT. If you log in with an email and password, you must set up multi-factor authentication before you use Codex Cloud.

Run codex login, or pipe in an API key or an access token:

printenv OPENAI_API_KEY | codex login --with-api-key
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token
  • Run codex login status to see the active method, or codex logout to clear credentials.
  • The cli_auth_credentials_store setting accepts "file", "keyring", "auto" or "ephemeral".
  • With file, credentials go in auth.json under CODEX_HOME, which defaults to ~/.codex.
  • On a headless or remote machine, OpenAI suggests codex login --device-auth.
  • You can also copy ~/.codex/auth.json to that machine, and treat it like a password.
  • If you can forward ports, run ssh -L 1455:localhost:1455 user@remote, then codex login in that session.

Sandboxing, approval policies and network controls

The sandbox mode sets what Codex can do. The approval policy sets when it must ask you first. By default, local sessions run with network access off, and writes are usually limited to the current workspace. OpenAI recommends Auto in version-controlled folders and read-only elsewhere. Use /permissions to switch modes and /status to see which folders are in the workspace.

PresetCLI flagsBehaviour
AutoNo flags, or --sandbox workspace-write --ask-for-approval on-requestWorks in the workspace and asks before editing outside it or using the network
Safe read-only browsing--sandbox read-only --ask-for-approval on-requestRead-only sandbox that asks before other actions
Read-only non-interactive (CI)--sandbox read-only --ask-for-approval neverRead-only sandbox with no prompts
Auto-review--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_reviewAuto settings with the auto_review approvals reviewer
Full access (not recommended)--dangerously-bypass-approvals-and-sandbox, alias --yoloNo sandbox and no approvals

Codex no longer supports approval_policy = "untrusted", and it can stop Codex from starting. To keep stricter command approvals, leave out the approval policy. Then set trust_level = "untrusted" for the project in your user config. This also turns off project-local configuration.

[projects."/path/to/project"]
trust_level = "untrusted"

Inside writable folders, .git, .agents, .codex and .aws stay read-only, including everything under them.

OS-level sandboxes and network proxy rules

  • macOS uses Seatbelt through sandbox-exec.
  • Linux uses bwrap with seccomp.
  • Windows supports MXC, with elevated and unelevated as legacy fallbacks.
  • To prefer MXC on Windows, set prefer_mxc = true under [features].

Test a sandbox with codex sandbox macos, codex sandbox linux or codex sandbox windows. To give commands network access and add domain rules, edit ~/.codex/config.toml:

[sandbox_workspace_write]
network_access = true

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow" }

The proxy does not grant network access by itself. Its rules are allowlist-first, and "deny" wins over "allow".

Web search defaults to web_search = "cached". The other values are "live", "indexed" and "disabled", and --search equals "live". OpenTelemetry is off by default. Under [otel], exporter can be "none", "otlp-http" or "otlp-grpc". OpenAI advises keeping log_user_prompt = false unless your policy allows storing prompts.

Project instructions with AGENTS.md and parallel Git worktrees

Layer instructions with AGENTS.md

When a run starts, Codex first checks your Codex home folder. There, it reads AGENTS.override.md if it exists, and otherwise AGENTS.md. It then walks from the project root, usually the Git root, down to your current folder. It takes at most one file per folder.

Files closer to your current folder override earlier guidance, because they appear later in the combined prompt. To use other file names, add them to project_doc_fallback_filenames in your config. The combined size is capped by project_doc_max_bytes, which is 32 KiB by default.

For GitHub pull request reviews, add a ## Code Review Rules heading to the AGENTS.md nearest the code it covers. See Share context between Claude Code and Codex.

Isolate parallel tasks in Git worktrees

In the desktop app, select Worktree under the composer and choose the branch to base it on. Codex then works without touching your checkout.

  • Codex creates managed worktrees in $CODEX_HOME/worktrees, in a detached HEAD state.
  • If the branch has uncommitted changes, Codex applies them to the worktree as well.
  • Use Create branch here in the chat header to turn the worktree into a named branch.
  • Use Hand off to move a chat between Local and a worktree.
  • List ignored files such as .env in a .worktreeinclude file at the repository root to copy them across.
  • Codex copies an ignored AGENTS.override.md into managed worktrees automatically.
  • By default, Codex keeps your 15 most recent managed worktrees and saves a snapshot before deleting one.

See Git worktrees for parallel coding agents: Claude Code and Codex.

Model Context Protocol (MCP) servers, Codex Cloud and codex exec

Connect external tools with MCP servers

The ChatGPT desktop app, the Codex CLI and the IDE extension share one MCP configuration. Codex supports STDIO servers, which run as a local process, and Streamable HTTP servers, which you reach at an address. Servers go in ~/.codex/config.toml, or in .codex/config.toml for trusted projects only.

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
codex mcp login <server-name>

Each server has its own settings block:

  • startup_timeout_sec defaults to 10 seconds.
  • tool_timeout_sec defaults to 60 seconds.
  • enabled_tools is an allow list, and disabled_tools is a deny list applied after it.
  • default_tools_approval_mode accepts auto, prompt, writes or approve.

Type /mcp to see your active servers. See Codex MCP servers: setup, CLI, config.toml and OAuth.

Run cloud tasks in Codex Cloud

Start from Work in > Cloud, then select Create environment. Connect GitHub, or pick a GitLab.com repository. Codex sets up dependencies and tools. You review the setup report and select Publish. The install script prepares dependencies, and the Start skill starts services and checks they are ready.

  • Environment variables are passed directly to programs in the environment.
  • Network secrets are sent only to a specific HTTPS service on port 443, and programs see a placeholder.
  • Your own values live in the Personal vault, and each person supplies their own.

For networking, the Package managers preset covers registries such as npm, PyPI, Go and Maven. Add other hosts under Additional allowed domains. Tailscale is the current VPN provider, through the proxy at proxy:8088. Tasks can also get short-lived credentials for AWS, Google Cloud and Azure through OIDC.

Plus plans get 2 vCPUs, 8 GiB memory and 8 GiB disk. Pro, Business and Enterprise plans get 4 vCPUs, 16 GiB memory and 32 GiB disk. By default, saved VM state is recoverable for up to seven days after your last turn.

Automate scripts and CI pipelines with codex exec

codex exec runs without prompts in a read-only sandbox by default. It streams progress to stderr and prints only the final agent message to stdout:

codex exec "generate release notes for the last 10 commits" | tee release-notes.md
codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
  • --json turns stdout into a JSON Lines stream of every event.
  • --ephemeral skips saving session rollout files to disk.
  • codex exec resume --last continues the most recent session.
  • In GitHub Actions, OpenAI recommends the openai/codex-action@v1 action.

See Codex exec non-interactive mode: flags, JSONL and CI setup.

Watch and answer OpenAI Codex sessions on a keypad or phone with Orbtile

With Logi Options+ 2.07 or later, Logitech's MX Keypad gives you one-tap prompt macros and other controls in tools such as OpenAI Codex, Claude Code and GitHub Copilot. Options+ runs on Windows 10 and later and macOS 13 and later. Windows computers with ARM64 processors are not supported.

Orbtile shows the live state of every Codex session. It drives the Logitech MX Creative Keypad's nine LCD keys over USB, without Logi Options+. Orbtile Mobile shows the same sessions on an iPhone (iOS 17 or later) or an Android phone (Android 8.0 or later). Orbtile runs on a computer with macOS 14.0 Sonoma or later on Apple silicon, or Windows 11 (x64).

  • Nothing needs installing in Codex, because Orbtile reads Codex thread files and Codex's own signals.
  • Desktop chats, terminal codex sessions and codex exec runs each show as Codex sessions.
  • Working sessions glow cool blue, and waiting sessions glow magenta-violet and move to the front.
  • Tap key 9, in the bottom-right corner, to focus the first waiting session, including sessions on other pages.
  • Hold a session key for 0.6 seconds to open Focus mode.
  • For compatible desktop command approvals, press Deny on key 7 or hold Allow on key 9 for 0.6 seconds.
  • For supported desktop multiple-choice questions, pick options on keys 1, 2, 3 and 7, then hold Send on key 9.
  • Terminal command approvals offer Allow only, so you decline them in the terminal.
  • codex exec never asks for command approval in Codex 0.159.0.
  • Other terminal waits and unsupported requests show Answer on computer.
  • Optional Codex hooks, installed in Settings > Agents > Codex, add a compacting state and slightly earlier updates.
  • Through Remote Hosts, Orbtile can also show Codex sessions running on SSH hosts.

See Codex keypad: Codex Micro, MX Keypad and Orbtile setup and Approve agent tool calls without switching windows.

FAQ

Where can I run OpenAI Codex?

You can run OpenAI Codex in your terminal with the Codex CLI, in the ChatGPT desktop app, or in the IDE extension for VS Code, Cursor and Windsurf. Xcode and JetBrains IDEs have their own integrations. Codex Cloud runs tasks in cloud environments, which you can use on the web, on mobile or in the desktop app.

Can I sign in to OpenAI Codex with a ChatGPT account or an API key?

Yes. The ChatGPT desktop app, the Codex CLI and the IDE extension accept either a ChatGPT account or an OpenAI API key. Codex Cloud requires signing in with ChatGPT.

How does the Auto sandbox preset work in OpenAI Codex?

Auto pairs the workspace-write sandbox with on-request approvals. Codex can read files, edit files and run commands in your workspace. It asks before editing files outside the workspace or using the network. The .git, .agents, .codex and .aws folders stay read-only.

How does Orbtile work with OpenAI Codex sessions?

Orbtile reads Codex thread files, so nothing needs installing in Codex. It shows desktop chats, terminal codex sessions and codex exec runs on a Logitech MX Creative Keypad, an iPhone or an Android phone. Waiting sessions move to the front. Compatible desktop approvals and supported questions can be answered on the keys. Terminal command approvals offer Allow only.