OpenAI Codex CLI guide: install, approvals, AGENTS.md and cloud tasks

Codex CLI is OpenAI's open-source coding agent for the terminal: it reads your repository, edits files and runs commands inside a sandbox you control. This guide covers installation, sign-in, sandbox and approval settings, AGENTS.md, scripting with codex exec and when to send a task to Codex cloud instead.

What is the OpenAI Codex CLI?

The OpenAI Codex CLI is a coding agent that runs in your terminal. You describe a task in plain language, and Codex inspects your repository, edits files and runs commands (tests, linters, build scripts) until the task is done, asking for approval when it needs more access than you granted.

A few facts to anchor the rest of this guide:

• It is open source. The openai/codex repository is licensed under Apache-2.0.
• It runs locally. Codex works on your checkout with your installed tools. Model calls go to OpenAI.
• It is sandboxed by default. File writes and network access are restricted until you loosen them.
• It is one surface of several. The same Codex agent also runs in an IDE extension, a desktop app and in the cloud. This guide focuses on the CLI and touches on cloud handoff.

If you are choosing between terminal agents, our comparison of the best AI coding assistants puts Codex next to Claude Code, Gemini CLI and the editor-based tools.

How do you install Codex CLI?

Install Codex with the official script, npm or Homebrew, then run codex inside a project folder. Pick one install method per machine; mixing them can leave several codex binaries on your PATH.

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

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

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

The Homebrew package is a cask, so brew install codex without --cask will not find it. To update a script install, run the same install command again.

Check the install and start your first session:

codex --versioncd ~/code/my-projectcodex

On Windows, the Codex CLI page also links to setup guides for WSL and for the native Windows sandbox, which works differently from the macOS and Linux sandboxes.

How do you sign in: ChatGPT account or API key?

Sign in with your ChatGPT account unless you have a reason to use an API key. A ChatGPT sign-in uses your plan's included Codex allowance and is required for cloud features; an API key bills per token at API rates.

The first time you run codex, it offers "Sign in with ChatGPT" and opens a browser. The authentication docs list the other options:

Credentials live in ~/.codex/auth.json or your OS keychain, controlled by the cli_auth_credentials_store setting. Treat auth.json like a password.

On a remote server over SSH, try --device-auth first. If that fails, the docs describe two fallbacks: copy ~/.codex/auth.json from a machine where you signed in, or forward the login callback port with ssh -L 1455:localhost:1455 user@remote and run codex login in that session.

As of October 2026, OpenAI's Codex pricing page lists Codex as included in ChatGPT Free, Go ($8 a month), Plus ($20), Pro (from $100), Business, Edu and Enterprise. Usage limits are given as estimated messages per five-hour window and vary by plan and model, so check the usage dashboard rather than planning around a fixed number.

How do Codex sandbox and approval modes work?

Codex controls risk with two separate settings: the sandbox decides what commands can technically touch, and the approval policy decides when Codex must stop and ask you. Together they replace the old "suggest / auto-edit / full-auto" modes some older tutorials still describe.

The three sandbox modes, from the approvals and security docs:

Approval policies decide when Codex pauses. on-request lets the model ask when it needs to step outside the sandbox; never means it never asks (anything the sandbox blocks fails instead). The older untrusted approval policy has been retired.

The defaults depend on the folder:

• In a Git repository: the Auto preset, which is workspace-write plus on-request approvals.
• Outside version control: read-only.
• Network access: off by default in both cases.

Codex may also start read-only until you mark a directory as trusted. You can switch modes mid-session with /permissions, or set them per run:

codex --sandbox read-only

codex --sandbox workspace-write --ask-for-approval never

To allow network access inside workspace-write (for example, so npm install works), set it in ~/.codex/config.toml:

sandbox_mode = "workspace-write"approval_policy = "on-request"[sandbox_workspace_write]network_access = true

How do you write a good AGENTS.md for Codex?

AGENTS.md is a Markdown file of standing instructions that Codex reads at the start of every session: how to build, how to test, coding conventions and things to avoid. Run /init in a session to generate a first draft, then edit it down to what Codex cannot work out from the code.

Codex looks for instructions in two places, per the AGENTS.md docs:

1. Global: ~/.codex/AGENTS.md (or AGENTS.override.md if present) for your personal defaults.
2. Project: every directory from the Git root down to your current folder. In each directory it uses AGENTS.override.md, else AGENTS.md, else any name listed in project_doc_fallback_filenames.

Files are concatenated from the root downward, so instructions in a subfolder appear later and win over the root file. Codex stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Long files get cut off, so keep them tight.

## Commands- Install: `pnpm install`- Test one file: `pnpm vitest run path/to/file.test.ts`- Typecheck: `pnpm typecheck` (run after every change)- Lint and format: `pnpm lint --fix`## Conventions- TypeScript strict mode. No `any`; use `unknown` and narrow.- API handlers live in `src/server/routes/`, one file per resource.- Database changes go through a new migration in `db/migrations/`, never edit old ones.## Do not- Do not run the full test suite; it takes 20 minutes. Run the files you touched.- Do not commit `.env*` files or touch `infra/`.

If your team also uses Claude Code, you can keep one instruction file and add CLAUDE.md to project_doc_fallback_filenames, or the reverse. Our post on CLAUDE.md best practices covers what belongs in these files and what to leave out; the advice applies equally to AGENTS.md.

Which Codex CLI commands should you know?

Inside a session you work in plain language, and slash commands handle the controls. The ones you will use most:

Useful command-line options include --image to attach a screenshot, --search to enable live web search and --profile <name> to load a named settings file. codex mcp manages MCP servers so Codex can reach tools such as a database or issue tracker.

A good first session looks like this:

Read the repo and explain how a request flows from the HTTP router to thedatabase. Don't change anything yet. Then propose a plan to add rate limitingto the /api/login route, including which files you'd touch and how you'dtest it.

Review the plan, push back where it is wrong, then ask Codex to implement it. The Codex docs recommend creating a Git checkpoint before and after each task so you can revert cleanly.

How do you run Codex non-interactively with codex exec?

codex exec runs one task without the interactive interface, which makes it the tool for scripts, cron jobs and CI. Progress streams to stderr and only the final message goes to stdout, so you can pipe the result.

Key behavior from the non-interactive mode docs:

• The default sandbox is read-only. Add --sandbox workspace-write to allow edits.
• --full-auto is no longer supported. Older scripts that use it need --sandbox workspace-write instead.
• --json turns stdout into a JSON Lines event stream.
• -o <file> writes the final message to a file; --output-schema schema.json asks for a final answer matching a JSON Schema.
• codex exec resume --last "follow-up" continues the previous run.

codex exec "summarize the repository structure and list the top 5 risky areas" > report.md

codex exec --sandbox workspace-write -o result.txt \  "fix the failing tests in src/billing and explain the root cause"

For CI, use an API key scoped to that one command, for example CODEX_API_KEY=... codex exec --json "triage open bug reports". The docs warn against setting the key as a job-wide environment variable in workflows that run repository code, and recommend the openai/codex-action GitHub Action, which keeps the key behind a proxy.

When should you use Codex cloud instead of the CLI?

Use Codex cloud when a task is well specified, can run without you and should keep going after you close your laptop. Use the CLI when you want to steer closely, need local tools or secrets, or are exploring.

From the CLI, codex cloud starts a cloud task or lists recent ones, and /cloud moves the current chat to the cloud when available. Cloud tasks start from a saved environment that can cache dependencies, and each runs in its own workspace.

Running several local Codex sessions at once also works if each gets its own checkout; git worktrees for parallel agents shows how to set that up without branches colliding. If you want local-style sessions (your own repos, your own tools) that keep running overnight, an always-on server is the other option. Orkio rents an isolated cloud box where agents such as Codex and Claude Code keep working after you close your laptop, and you check on them from your phone.

Codex CLI setup checklist

Work through this list once and most first-week problems disappear:

1. Install with one method and confirm with codex --version.
2. Sign in with ChatGPT (codex login), or store an API key if you bill through the API.
3. Run codex in a Git repository so you get the Auto defaults, and commit before each task.
4. Run /init, then trim AGENTS.md to commands, conventions and hard rules.
5. Decide on network access and set it in ~/.codex/config.toml instead of reaching for --yolo.
6. Start each task by asking for a plan, then approve the implementation.
7. Use /review on the diff before you commit, and read the diff yourself.
8. Move repeatable jobs to codex exec with a read-only or workspace-write sandbox and a scoped API key.

If you also use Anthropic's agent, the Claude Code tutorial follows the same steps for Claude Code, so you can compare the two on the same repository.

Frequently asked questions