Codex CLI install in fifteen minutes, and what to skip

On this page#

• Before you install anything
• The steps
• A working configuration
• What to skip
• First real task
• FAQ

Before you install anything#

Install Codex CLI globally with npm, authenticate, apply a conservative workspace configuration, and test it inside a clean checkout before giving it a real task. Do not begin by enabling broad filesystem access or automatic approvals. The installation takes minutes; proving that the agent respects your repository’s invariants is the important part.

Order matters because installation, access, and repository guidance solve different problems:

1. Installation makes the executable available.
2. Authentication lets the CLI reach the model.
3. Sandboxing limits what the process may change.
4. Repository instructions tell the agent what “correct” means locally.
5. A controlled first task exposes missing constraints without risking a large diff.

Codex CLI is OpenAI’s terminal coding agent: it reads repository context, proposes or performs changes, and runs commands subject to its configured permissions. The official Codex CLI documentation is the authority for supported installation and authentication behavior.

Do the first setup from the repository you actually maintain, but start with a clean working tree. That is not ceremony. A dirty tree makes it harder to distinguish your edits from the agent’s, complicates rollback, and weakens review.

Before continuing, confirm three things:

• The repository’s normal tests pass.
• You know which files and generated artifacts should never be edited manually.
• Your current work is committed or otherwise recoverable.

If those conditions are not true, fix them first. Installing an agent into an ambiguous workspace only makes the ambiguity faster.

Photo by Boris K. on Pexels.

The steps#

The shortest reliable codex cli install path is: verify the existing npm toolchain, install the official package globally, launch Codex, authenticate through the prompted flow, add restrictive defaults, and run a read-first task. Each step below prevents a specific class of setup failure rather than adding optional polish.

1. Confirm that node and npm already work in your shell; this prevents treating a broken runtime or PATH as a Codex failure.

   node --version
   npm --version

   Do not replace a team-managed Node installation merely to install Codex. If npm is already part of the repository toolchain, use that installation and its established ownership model.

2. Install the Codex package globally; this prevents the executable from being coupled to one repository’s application dependencies.

   npm install -g @openai/codex

   The -g flag selects npm’s global installation mode. See the official npm install documentation for how npm interprets global and local installs.

3. Ask the shell which executable it will run; this prevents debugging the wrong Codex binary when multiple package locations exist.

   command -v codex
   codex --version

   The version value itself is less important than consistency: the resolved path should belong to the npm environment you intended to use.

4. Launch Codex and complete its authentication prompt; this prevents configuration debugging before the CLI has usable credentials.

   codex

   Follow the supported sign-in path shown by the CLI. Do not paste credentials into repository files, shell history, AGENTS.md, or the Codex configuration.

5. Exit before accepting a substantial task and create the configuration below; this prevents the first session from inheriting unnecessarily broad authority.

6. Reopen Codex at the repository root; this prevents it from starting with the wrong working directory and incomplete project context.

   cd /absolute/path/to/repository
   codex

These are the essential steps for anyone asking how to install Codex CLI. Package-manager customization, elaborate aliases, and team-wide rollout come later—after one controlled repository has demonstrated a safe operating boundary. The Codex CLI documentation should remain your reference when supported commands or authentication behavior change.

A working configuration#

Start with approval required on request, writes limited to the current workspace, and network access disabled inside the writable sandbox. This configuration is intentionally conservative: it permits normal repository work while keeping external access and out-of-workspace changes from silently becoming part of the task.

Create ~/.codex/config.toml with the following contents:

# Let Codex request approval when an action crosses the normal safety boundary.
approval_policy = "on-request"

# Permit writes inside the active workspace, not across the machine.
sandbox_mode = "workspace-write"

# Configure the behavior of the workspace-write sandbox.
[sandbox_workspace_write]

# Prevent commands in the writable sandbox from making network requests.
network_access = false

Line by line, the configuration makes three decisions:

• approval_policy = "on-request" keeps escalation visible. Automatic approval is a poor default for a repository with deployment scripts, migrations, credentials, or destructive maintenance commands.
• sandbox_mode = "workspace-write" allows Codex to edit the checked-out project while restricting broader filesystem access.
• [sandbox_workspace_write] opens the settings table for that sandbox mode.
• network_access = false stops repository commands from reaching external services by default.

This file controls capability, not engineering judgment. It does not tell Codex which test command is authoritative, which directory contains generated code, or whether a schema change requires a migration.

Put those repository-specific invariants in the repository’s agent instructions. Keep them short and executable:

# Repository instructions

- Run the existing formatter before reporting completion.
- Run the narrowest relevant test first, then the standard test suite.
- Do not edit generated files directly.
- Do not change public interfaces unless the task explicitly requires it.
- Do not run deployment, publishing, migration, or destructive database commands.
- Report any required command that the sandbox prevented.

Replace generic statements with the repository’s real commands and paths. An instruction such as “follow best practices” is useless; “do not edit generated files directly” establishes a reviewable invariant.

For a fuller operating model—task framing, repository constraints, review, and handoff—the PairFoundry Agent Operating Kit is the relevant next layer. Installation gives you a binary; it does not give your team a shared way to operate it.

Photo by ThisIsEngineering on Pexels.

What to skip#

Skip anything that increases convenience before you have established containment, repeatability, and rollback. Most installation tutorials over-invest in shell decoration and under-invest in repository state. That priority is wrong for production code: a shorter command does not compensate for unclear permissions or an unreviewable first task.

| Common tutorial step | Why to skip it | |---|---| | Enabling unrestricted approvals immediately | It removes the checkpoint that reveals unexpected commands and scope expansion. | | Granting machine-wide write access | Normal coding work should fit inside the repository workspace. | | Turning on network access “just in case” | It expands both data-exposure risk and task nondeterminism without a demonstrated need. | | Installing Codex as a project dependency | A terminal agent is operator tooling, not an application runtime dependency. | | Adding aliases before verifying the binary path | An alias can hide which installation is actually running. | | Starting with a repository-wide refactor | A large diff conceals instruction, permission, and test-discovery failures. | | Copying somebody else’s AGENTS.md unchanged | Their commands and invariants are not your repository’s contract. | | Suppressing approval prompts because they feel repetitive | Repetition is evidence to refine scope, not a reason to remove the boundary. |

Also skip reinstalling npm whenever codex is not found. First inspect the executable path and npm’s global setup. The npm installation documentation distinguishes global installation from adding a dependency to the current package.

If you are still defining repository invariants, use the free PairFoundry foundations track before standardizing a team configuration. The broader PairFoundry packs overview separates setup help from more complete operating systems, while the agent setup hub collects related setup guidance.

First real task#

Your first task should be a small, bounded defect with an existing failing test—or a behavior that can be captured by one. Require Codex to inspect first, state its plan, make the minimum change, and run the relevant checks. This reveals whether repository instructions and permissions work without hiding mistakes inside a broad rewrite.

Use a prompt shaped like this:

Inspect the repository instructions and the relevant code before editing.

Fix the smallest scoped defect described below:
[describe the observable failure]

Constraints:
- Preserve existing public interfaces.
- Do not edit generated files.
- Do not add dependencies.
- Run the narrowest relevant test first.
- Run the repository’s standard validation afterward.
- Stop and explain if a required action needs broader permissions.

Before changing files, summarize the likely cause and name the files you expect to touch.
Afterward, report the changed files, commands run, results, and remaining uncertainty.

The task should exercise reading, editing, testing, and reporting. It should not require deployment credentials, production data, network access, a migration, or architectural invention.

Review the resulting diff exactly as you would review a teammate’s change. Passing tests are necessary, but they do not prove the agent preserved unstated invariants. If the agent touched unrelated files, guessed a command, or requested unnecessary access, improve the instructions before assigning a second task.

Photo by Al Nahian on Pexels.

Related reading#

• Npm install anthropic-AI/Claude Code — the setup that survives a real repo
• Getting started with Claude Code — the setup that survives a real repo

FAQ#

These are the questions that matter after the command succeeds: where Codex should operate, how this setup differs from the official minimum, what a team must standardize, and how to recover cleanly. The answers favor narrow authority and explicit repository contracts because those properties make agent work reviewable.

When should I not use Codex CLI in a repository?#

Do not use it where you cannot isolate a workspace, review a diff, or recover the prior state. Avoid first tasks that require production credentials, live migrations, deployment authority, or access to sensitive data. Resolve the operational boundary before asking an agent to change code.

How does this differ from the official installation flow?#

The official flow explains how to install, authenticate, and use the supported CLI. This guide adds an opinionated operating sequence: clean state first, conservative permissions, repository invariants, and a bounded validation task. Those additions are workflow safeguards, not replacements for the official Codex CLI documentation.

What usually breaks when a team standardizes Codex CLI?#

Teams often standardize the install command but leave test commands, generated-file rules, approval expectations, and forbidden operations implicit. The result is inconsistent behavior across repositories. Share repository-owned instructions, but let authentication and machine-specific package paths remain local.

How do I roll back a bad installation or first change?#

For code changes, inspect the diff and restore only the affected files using your normal version-control workflow; never discard unrelated work. To remove the global package, use:

npm uninstall -g @openai/codex

Then verify that command -v codex no longer resolves to that installation.