Install with brew install --cask codex, the standalone installer from chatgpt.com/codex/install.sh, or npm install -g @openai/codex. Codex is a Rust binary, so only the npm route needs Node. On macOS the sandbox is enforced by Seatbelt. Keep repositories out of Desktop, Documents and Downloads. Checked against OpenAI and Homebrew sources in August 2026.
- Homebrew ships Codex as a cask:
brew install --cask codex. - The standalone installer is the route OpenAI documents first and it self-updates.
- Only the npm route needs Node. Codex itself is a Rust binary.
- The sandbox is Seatbelt, so
read-onlygenuinely cannot write. - Keep repos out of Desktop, Documents and Downloads.
- Credentials go to
~/.codex/auth.jsonor the macOS Keychain, your choice.
Three routes, and what each one leaves behind
# 1. Standalone installer (documented first by OpenAI)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 2. Homebrew. It is a CASK, not a formula.
brew install --cask codex
# 3. npm, if you already manage global CLIs there
npm install -g @openai/codex
codex --versionChecked against the OpenAI docs and the Homebrew cask API in August 2026.
| Route | Needs Node? | Update with | Lands in | Breaks when |
|---|---|---|---|---|
| Standalone installer | No | codex update, or re-run the script | ~/.local/bin by default | Rarely. ~/.local/bin is not on every PATH |
| Homebrew cask | No | brew upgrade --cask codex | $HOMEBREW_PREFIX/bin/codex | Rarely |
| npm global | Yes | npm install -g @openai/codex | Your npm global prefix | You change Node version |
echo $PATH | tr ':' '\n' | grep -c "$HOME/.local/bin"
# add it once
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zshFirst run
Start it in the repository root
cd ~/code/your-project
codexThe directory you launch from becomes the workspace, and the workspace is what the sandbox is drawn around. Launching from a parent directory quietly widens the boundary.
Sign in with ChatGPT
The first run offers a sign-in choice. Sign in with ChatGPT uses the plan you already pay for. An API key bills per token at standard API rates instead, and loses the cloud features.
codex login
codex login statusDecide where the credential lives
# file | keyring | auto
cli_auth_credentials_store = "keyring"On a Mac, keyring puts the token in the macOS credential store instead of a plaintext file. auto uses the credential store when it is available and falls back to auth.json.
Set the two settings that matter
model_reasoning_effort = "medium" # minimal | low | medium | high | xhigh
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# Network is OFF inside workspace-write until you say otherwise.
[sandbox_workspace_write]
network_access = falseWhat Seatbelt actually enforces
On macOS, Codex confines each spawned command with Seatbelt, the kernel-level sandboxing facility macOS uses for its own applications. That makes sandbox_mode a real boundary rather than an agreement with the model.
| Mode | Reads | Writes | Network |
|---|---|---|---|
read-only | Files in scope | Nothing | No |
workspace-write | Files in scope | The workspace, plus any writable_roots | Off by default |
danger-full-access | Everything | Everything | Yes |
[sandbox_workspace_write]
# a sibling checkout the build genuinely needs to write
writable_roots = ["/Users/you/code/shared-protos"]
network_access = falsePrefer --add-dir or a writable_roots entry over turning the sandbox off. Both keep the boundary and move it; danger-full-access deletes it.
The macOS trap: Desktop, Documents, Downloads
macOS guards ~/Desktop, ~/Documents and ~/Downloads with its privacy consent system. A confined child process working there hits permission machinery that has no way to prompt you, and the failure surfaces as an agent that reads fine and writes nothing.
How the symptom presents.
| What you see | What it actually is |
|---|---|
| Intermittent permission errors that vary run to run | Project sits in a protected folder |
| Reads succeed, writes fail with no useful error | Same cause |
| Works in one repo, fails in another on the same Mac | One of them is under ~/Documents |
| A prompt appears the first time, then never again | Consent was recorded for the terminal, not for Codex |
mkdir -p ~/code
cd ~/code
git clone <repo>
cd <repo>
codexThe other Codex surfaces on a Mac
The CLI is not the only way Codex runs on macOS, and two of the alternatives are one command away from the terminal you are already in.
| Surface | How you get it | What it adds |
|---|---|---|
| ChatGPT desktop app | codex app | Local chats with parallel worktrees, file previews and scheduled tasks |
| VS Code, Cursor, Windsurf | The Codex extension from the marketplace | Open files and selection as context; diffs in the editor |
| Xcode | The built-in coding assistant, with Codex selected as the agent | Codex inside Apple's own toolchain |
| JetBrains IDEs | AI Chat, with Codex selected | Same agent, JetBrains context |
# open (or install) the desktop app
codex app
# shell completions. The Homebrew cask does this for you;
# the installer and npm routes do not.
codex completion zsh > "${fpath[1]}/_codex"The CLI and the IDE extension share one cached login, so signing in once covers both. Signing out of either one signs out the other, which surprises people exactly once.
The rest of the macOS surface
Everything Codex keeps on a Mac lives under one directory.
| Path | Holds |
|---|---|
~/.codex/config.toml | Settings, profiles, MCP servers |
~/.codex/auth.json | Cached credentials, unless you chose keyring |
~/.codex/sessions/ | JSONL transcripts of every run |
~/.codex/rules/ | Execpolicy rules for commands outside the sandbox |
CODEX_HOME | Moves all of the above. The directory must already exist. |
Mac-specific failures.
| Symptom | Cause | Fix |
|---|---|---|
codex: command not found | PATH not reloaded, or ~/.local/bin missing from it | New shell, then add the directory to PATH |
| Vanished after a Node upgrade | npm global prefix moved with Node | Reinstall, or switch to the cask |
npm install fails with a network error | Network off in workspace-write, by design | Enable network_access deliberately, then turn it back off |
| Asked to sign in every launch | ~/.codex not writable by your user | ls -ld ~/.codex and fix ownership |
| Config edits appear to do nothing | A profile or managed layer is overriding them | /debug-config prints the layer order |
codex doctorQuestions people ask
Use brew install --cask codex. Codex ships as a Homebrew cask, not a formula, and the cask contains Apple Silicon and Intel macOS builds. Update it with brew upgrade --cask codex.
Run curl -fsSL https://chatgpt.com/codex/install.sh | sh, or brew install --cask codex, or npm install -g @openai/codex. Then run codex in a project directory and sign in with ChatGPT.
Only for the npm route. Codex is a Rust binary, so the standalone installer and the Homebrew cask are self-contained and survive Node upgrades.
Yes. It uses Seatbelt, the same kernel-level facility macOS uses to confine its own applications, and it applies to spawned commands as well as the agent edits. A read-only session genuinely cannot write.
Most often because the project lives under Desktop, Documents or Downloads, which macOS protects with its privacy consent system. Move it to somewhere ordinary such as ~/code.
In ~/.codex/auth.json by default. Set cli_auth_credentials_store = "keyring" in config.toml to use the macOS credential store instead, or "auto" to prefer it with a file fallback.
Yes, natively. The releases and the Homebrew cask both carry aarch64 and x86_64 Darwin builds. macOS 12 or newer is the documented baseline.
Add the path to sandbox_workspace_write.writable_roots in config.toml, or pass --add-dir for one run. Both keep the sandbox and move its edge, which is safer than danger-full-access.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.