The official route is curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS and Linux, or the PowerShell one-liner on Windows. npm install -g @openai/codex and brew install --cask codex both work too. Run codex in a repository, sign in with your ChatGPT account to bill against your subscription, then run codex doctor to confirm the install, config, auth, and sandbox are all healthy.
- One command:
curl -fsSL https://chatgpt.com/codex/install.sh | sh. No Node needed. npm i -g @openai/codexandbrew install --cask codexare the alternatives.- Sign in with ChatGPT to use your subscription. An
OPENAI_API_KEYsilently overrides it. codex doctorchecks install, config, auth, and runtime in one shot. Run it first when anything is wrong.- Launch from the repository root: the working directory is the sandbox scope.
- Defaults as of August 2026: model
gpt-5.6-sol, effortlow, sandboxworkspace-write.
Pick an install route
There are three, and they differ mainly in what breaks them later.
# official installer, self-contained, no Node
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# or Homebrew
brew install --cask codex
# or npm, if you already manage global CLIs that way
npm install -g @openai/codex
codex --versionpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --versionWhat each route costs you later.
| Route | Needs Node? | Update with | Breaks when |
|---|---|---|---|
| Official installer | No | codex update | Rarely |
| Homebrew cask | No | brew upgrade --cask codex | Rarely |
| npm global | Yes, 16+ | npm update -g @openai/codex | You change Node version |
If npm fails with EACCES
Never fix this with sudo. Installing globally as root leaves root-owned files under your npm prefix, and every later install for your user fails in a way that is much harder to diagnose than the original error.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex
codex --versionIf you have already run a sudo install, remove the root-owned tree before retrying, or the reinstall inherits the same problem.
First run and signing in
Start it in the repository root
cd ~/code/your-project
codexThe directory you launch from becomes the workspace root, and the sandbox is scoped to it. This is not a convention, it is the boundary. Outside a git repository Codex refuses to start unless you pass --skip-git-repo-check, which is a deliberate guard rather than a bug.
Choose ChatGPT, not an API key
The first run offers both. Signing in with ChatGPT uses the subscription you already pay for and costs nothing extra. Choosing an API key bills per token from the very first message.
codex login # opens a browser
codex login status # what am I actually signed in as?Check nothing is overriding it
echo $OPENAI_API_KEY # should be empty for subscription billingA key exported months ago for an unrelated script takes precedence over the subscription login. That is the single most expensive mistake on this page: you pay the subscription and the metered bill at the same time, and nothing warns you.
Verify the whole install in one command
codex doctorIt diagnoses the local installation, the config file, authentication, and runtime health together. When something is wrong later, this is the first thing to run and the first thing to paste into a bug report.
What to set on day one
Codex works out of the box. These are the four settings worth a deliberate decision before you build habits around the defaults.
# Sensible defaults for interactive work.
model = "gpt-5.6-sol" # sol | terra | luna
model_reasoning_effort = "low" # sol is strong at low; escalate on evidence
# Can edit inside the workspace, asks before anything outside it.
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# Network is OFF in workspace-write unless you say otherwise.
[sandbox_workspace_write]
network_access = falseTwo orthogonal settings that almost everyone conflates.
| Setting | Controls | Enforced by |
|---|---|---|
sandbox_mode | What Codex is capable of touching | The operating system |
approval_policy | When it asks you first | The agent loop |
What lives in ~/.codex after a first run.
| Path | Holds |
|---|---|
config.toml | Every setting |
auth.json | Credentials. Never commit this. |
sessions/ | JSONL transcript of every run |
history.jsonl | Prompt history for recall |
log/ | Diagnostics codex doctor reads |
<name>.config.toml | A named profile, loaded with -p <name> |
Confirming which Codex you are actually running
It is easy to end up with two or three installs: the official installer in one place, an npm global from six months ago in another, and a Homebrew cask on top. They do not conflict loudly. They just mean the version you upgraded is not the one your shell runs, and every symptom after that is confusing.
which -a codex # every codex on PATH, in the order the shell picks them
codex --version # the one that actually winsWhat a duplicate install looks like.
| Symptom | What is happening |
|---|---|
| Upgraded, version unchanged | A second install earlier on PATH |
| A flag from the changelog is unrecognised | You are on an older binary than you think |
| Works in one terminal, not another | Different PATH, usually a login shell versus a tool shell |
When it will not run
Ranked by how often it is actually the cause.
| Symptom | Cause | Fix |
|---|---|---|
codex: command not found | PATH not reloaded | Open a new shell |
| Vanished after a Node upgrade | npm global prefix moved | Reinstall, or switch to the installer |
| Billed per token unexpectedly | OPENAI_API_KEY is set | unset OPENAI_API_KEY, then codex login |
| Login never completes | No browser, or a proxy | Copy the URL manually, or use --with-api-key |
| Refuses to start in a folder | Not a git repository | git init, or --skip-git-repo-check |
| Cannot write files | Sandbox is read-only | codex -s workspace-write |
npm install fails inside a session | Sandbox blocks network by design | Enable network_access deliberately |
| Anything else | Unknown | codex doctor before anything else |
Questions people ask
Run curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS or Linux, or the PowerShell one-liner from chatgpt.com/codex/install.ps1 on Windows. brew install --cask codex and npm install -g @openai/codex also work. Then run codex in a project directory and sign in with ChatGPT.
Only for the npm route, which declares node 16 or newer. The official installer and the Homebrew cask ship a self-contained platform binary and need no Node at all.
No. Signing in with a paid ChatGPT account uses your subscription. A key is for CI, servers, and metered billing with no usage windows.
Because OPENAI_API_KEY is set in your environment and takes precedence over the subscription login. Unset it and run codex login again, then confirm with codex login status.
In ~/.codex/: config.toml for settings, auth.json for credentials, sessions/ for the JSONL transcript of every run, and one file per named profile, such as build.config.toml.
The sandbox is probably read-only. Pass -s workspace-write for one run, or set sandbox_mode = "workspace-write" in config.toml.
Yes, with --skip-git-repo-check. The check exists because git is the undo button for an agent that edits files, so removing it is a deliberate choice rather than a convenience.
codex doctor. It diagnoses the installation, config, auth, and runtime together, which is faster than guessing and is what a maintainer will ask for anyway.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.