OpenAI Codex: What It Is and How to Get Started
October 5, 2026
You hear "OpenAI Codex" and picture one product. It is four: a terminal tool, an editor extension, a desktop app, and a cloud service. They share much of their configuration and a project instructions file, which is why they feel like one thing.
Codex is OpenAI's coding agent. The README describes the CLI as a coding agent that runs locally on your computer. You describe a task, it reads your repository, edits files, and runs commands, pausing to ask when it reaches the edge of what you allowed.
This guide covers what each surface is, how to sign in, what the approval and sandbox settings are called and do, how AGENTS.md works, and how work moves between your machine and the cloud. It is an overview, not a head-to-head. For that, see Claude Code vs Codex.
A note on sources: everything below comes from OpenAI's Codex documentation and the GitHub repository, read in October 2026. The docs have moved. As of October 2026, developers.openai.com/codex redirects to learn.chatgpt.com/docs, so the links here point at the new home.
The four OpenAI Codex surfaces
| Surface | Where it runs | How you start |
|---|---|---|
| CLI | Your computer, in a terminal | Install it, run codex in a project folder |
| IDE extension | Your computer, beside your code | Install the extension, open the Codex sidebar |
| Desktop app | Local, a Git worktree, or the cloud | Open the ChatGPT desktop app and select Codex |
| Cloud | In the cloud, one workspace per task | Open ChatGPT, choose Work in > Cloud, pick an environment |
The CLI. The Codex CLI is the terminal surface. The docs list four install routes: a standalone installer for macOS and Linux, one for Windows, npm, and Homebrew.
npm install -g @openai/codex
# or
brew install --cask codex
Then open a project folder and run codex. The docs suggest starting with a harmless prompt, Tell me about this project, and creating Git checkpoints before and after each task so you can revert. The CLI can also run non-interactively with codex exec, which is what you use in scripts and CI.
The IDE extension. The Codex IDE extension works in VS Code, Cursor, and Windsurf. The docs say Xcode and JetBrains IDEs "provide their own integrations" instead. Its pitch is context: you reference open files and selections from the composer, so you spend less time re-explaining the problem, and you review the diff beside the source.
The desktop app. There is no separate "Codex app" download in the docs. Codex lives inside the ChatGPT desktop app: open the ChatGPT dropdown and select Codex. When you start a Codex chat there, you choose where it runs: Local (your project directory), Worktree (changes isolated in a Git worktree), or Cloud. From the terminal, codex app launches the desktop app.
Cloud. Codex Cloud runs tasks away from your computer. Each task has its own workspace, and the docs say tasks can keep working while your computer is asleep. You set up a reusable environment once (repositories, dependencies, tools, access), publish it, then start tasks from it. You review the changes and test results, then commit or open a pull request.
One date-sensitive detail: the docs also describe "Codex Cloud (Legacy)," which still supports Code Review and the Linear and GitHub integrations, and say OpenAI plans to deprecate that experience. If you meet two cloud setups in the docs, that is why.
How to sign in to Codex
The authentication docs list two methods:
- Sign in with ChatGPT for subscription access.
- Sign in with an API key for usage-based access.
The desktop app, CLI, and IDE extension support both for local work. Codex cloud requires signing in with ChatGPT.
| Surface | ChatGPT sign-in | API key |
|---|---|---|
| CLI | codex login, then finish in the browser | printenv OPENAI_API_KEY | codex login --with-api-key |
| IDE extension | Select Sign in with ChatGPT | Select Use API Key |
| Desktop app | Select Continue to sign in | Select Sign in another way |
If an API key is a new idea, it is a secret string that identifies your account to a service, and anyone holding it can spend against it. The docs add that API-key usage is billed through your OpenAI Platform account, and they warn against exposing Codex execution in untrusted or public environments.
Two practical details from the same page. First, the CLI and the extension share one cached login, so after you log out of either, you sign in again before using the other. Second, Codex caches the login locally, in a plaintext file at ~/.codex/auth.json or in your OS-specific credential store, and a cli_auth_credentials_store setting controls which. If that bothers you, set it to the keyring option.
Check what you are signed in as with codex login status.
Approval modes and sandbox modes
Codex separates two questions. The approvals and security docs name them:
- Sandbox mode: what Codex can do technically, such as where it can write and whether it can reach the network.
- Approval policy: when Codex must stop and ask you first.
Locally, the sandbox is enforced by the operating system. Per the docs, by default the agent runs with network access turned off, and write access is limited to the active workspace.
| Setting | Values the docs list | What it controls |
|---|---|---|
sandbox_mode | read-only, workspace-write, danger-full-access | Filesystem and network reach |
approval_policy | on-request and never in the docs' examples, plus a granular form | When it asks |
The combinations the docs name are short:
| Intent | Flags | Effect |
|---|---|---|
| Auto (the preset) | --sandbox workspace-write --ask-for-approval on-request | Reads, edits, and runs commands in the workspace; asks before editing outside it or using the network |
| Safe read-only browsing | --sandbox read-only --ask-for-approval on-request | Reads files and runs commands inside the read-only sandbox |
| Read-only non-interactive (CI) | --sandbox read-only --ask-for-approval never | Never asks |
| Dangerous full access | --dangerously-bypass-approvals-and-sandbox (alias --yolo) | No sandbox and no approvals; the docs mark it not recommended |
Codex also picks a starting point for you. On launch it detects whether the folder is version-controlled: Auto for a version-controlled folder, read-only otherwise. Inside workspace-write, the .git, .agents, and .codex directories stay read-only.
In the CLI, type /permissions to change the active profile. In the desktop app and IDE extension, the control under the composer can show Ask for approval, Approve for me, and Full access, depending on your configuration. The docs also mention a retired untrusted approval policy that can stop a client from starting if it is still in an old config file, so remove it if you inherit one.
AGENTS.md: project instructions Codex reads first
Your test command, naming conventions, and the folders it should leave alone are the things you re-type every session. AGENTS.md is where they live instead. The docs say Codex reads AGENTS.md files before doing any work.
Discovery follows a fixed order:
- Global: in your Codex home (
~/.codexby default),AGENTS.override.mdif it exists, otherwiseAGENTS.md. - Project: from the project root down to your current directory, it checks
AGENTS.override.md, thenAGENTS.md, then any fallback names you configured. At most one file per directory. - Merge: files are concatenated root-down, so the ones closest to your working directory come last and win.
A starter file can be this small:
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
Run /init in the CLI and Codex generates a scaffold for you to edit and commit. To check it loaded, the docs suggest codex --ask-for-approval never "Summarize the current instructions."
There is a size cap. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. It is a good reason to stay brief: everything Codex reads sits in the model's context window, the working memory it has for one session, so a long instructions file leaves less room for your actual task. Keep it to rules you would otherwise repeat.
Extending it with MCP and skills
Two other extension points are shared across surfaces. The desktop app, CLI, and IDE extension support MCP servers and share one MCP configuration, so a tool you add in one shows up in the others. And skills package instructions, resources, and optional scripts into a workflow. The docs note that Codex starts with each skill's name and description, loads the full SKILL.md when it decides to use one, and caps that initial list at 2% of the model's context window (or 8,000 characters when the window size is unknown).
How work moves between local and cloud
This is where people get confused, so here are the directions exactly as the docs state them.
| Direction | How, per the docs |
|---|---|
| Start in the cloud | In the desktop app or on the web, choose Work in > Cloud and select a published environment. On mobile, open Codex. |
| IDE extension to cloud | Click the cloud icon beneath the composer and pick an environment. The next prompt creates a new chat in the cloud that carries over the existing chat context, including the plan and any local source changes. |
| CLI to cloud | codex cloud opens a picker of cloud chats; codex cloud exec submits a task directly; codex cloud list shows recent ones. |
| Cloud result to local | codex apply applies the most recent diff from a Codex cloud chat to your local repository. The cloud docs also say you can open a pull request directly. |
| CLI session to desktop app | /app opens the current session in the ChatGPT desktop app, on macOS and Windows. |
| Across devices | Reopen the same cloud task on web, mobile, or desktop to continue it. A new task starts separate work. |
Two limits are worth knowing before you delegate. The docs say your computer's local files, running processes, browser sign-ins, and VPN access are not automatically transferred to a cloud task, and personal skills on your machine are not synced to cloud environments, although skills stored in your repository are available. Cloud tasks work from the environment you published, not from whatever is open on your laptop.
Who Codex is for
Codex fits you if:
- You work in a Git repository and are comfortable reading a diff. The docs themselves tell you to create Git checkpoints before and after tasks.
- You already live in a terminal or VS Code-style editor, which is where the CLI and extension run.
- You want tasks with a checkable result, like a failing test or a mechanical refactor, that you can hand off and review later.
- You want to read or contribute to the tool itself. The open source docs list the CLI as open source at
openai/codex, and say the IDE extension and Codex cloud are not.
It is a poor fit if you are not a developer and just want to use an AI setup someone else already built. Codex gives you a coding agent and a way to constrain it. It does not give you a configured workflow you can run today, and you will spend your first sessions on AGENTS.md, permissions, and environment setup. That is a fair trade for a daily coding tool and an unfair one for a one-off.
If you are weighing it against another agent, the comparison linked in the intro covers that choice. Here, the point is narrower: know the four surfaces, the two safety layers, and the one instructions file.
Where Taku fits
Codex is for writing and changing code in a repository you own. Taku is a different shape: an AI-native desktop workspace where you mirror an AI setup (an app, a skill, a workflow) that someone already got working, run it, remix it, and keep it. If your goal is to use a working setup rather than build one from a blank repo, the free app library shows what is available to mirror. Taku is in Beta, and the Mac app is available now.
FAQ
What is OpenAI Codex?
OpenAI's coding agent. It reads a repository, edits files, and runs commands, and it is available as a CLI, an IDE extension, a mode in the ChatGPT desktop app, and a cloud service.
Is there a separate Codex app?
Not in the docs. The Codex "app" is the ChatGPT desktop app with Codex selected. codex app in a terminal launches it.
How do I use the Codex CLI?
Install it with npm, Homebrew, or the standalone installer, run codex in a project folder, and choose Sign in with ChatGPT or another available method on first run. Then describe a task.
Do I need an API key?
No. The docs list signing in with ChatGPT as one option and an API key as the other for local work. Codex cloud requires ChatGPT sign-in.
How do I stop Codex from changing my files?
Use the read-only sandbox mode, for example codex --sandbox read-only --ask-for-approval on-request, or switch with /permissions mid-session.
Is Codex open source?
The CLI is. The docs list it at openai/codex, and the README states the repository is licensed under Apache-2.0. The IDE extension and Codex cloud are listed as not open source.
Key points
- Codex is one agent on four surfaces: CLI, IDE extension, ChatGPT desktop app, and cloud.
- Sign in with ChatGPT or an API key for local work; cloud needs ChatGPT.
- Two layers keep it contained: sandbox mode (
read-only,workspace-write,danger-full-access) and approval policy (on-request,never). AGENTS.mdis read before any work, layered from global to nearest directory, and capped at 32 KiB by default.- Local-to-cloud and cloud-to-local handoffs are separate, named paths; do not assume they are symmetric.