Your First Codex Session | Understanding Codex

Enough theory. Let us get Codex running on your machine, configure it properly, and complete your first interactive session. By the end of this lesson, you will have installed Codex, run a real task, and understood the approval flow that keeps you in control.

Installation

Codex requires Node.js 16 or newer (version 20 LTS is recommended). Check your version first:

Bash

node --version
# Should print v16.x.x or higher (v20+ recommended)

Install globally via npm or Homebrew:

Bash

# Option 1: npm (all platforms)
npm i -g @openai/codex

# Option 2: Homebrew (macOS/Linux)
brew install --cask codex

Verify the installation:

Bash

codex --version

Node.js Version Matters

Codex requires Node.js 16 or newer, with version 20 LTS recommended for the best experience. If you are on an older version, use nvm or fnm to upgrade: nvm install 20 && nvm use 20.

Configuration

Codex reads configuration from ~/.codex/config.yaml (or config.json). Create this file to set your defaults:

YAML

# ~/.codex/config.yaml

# Default model for interactive sessions
model: o4-mini

# Default approval mode
approvalMode: suggest

# Desktop notifications
notify: true

You also need an API key. Set the OPENAI_API_KEY environment variable:

Bash

export OPENAI_API_KEY="sk-your-key-here"

Add this to your shell profile (.zshrc, .bashrc) so it persists across sessions.

Your First Interactive Session

Navigate to any project directory and launch Codex:

Bash

cd ~/my-project
codex

You will see a terminal UI with a prompt. Type a natural language instruction:

> Find all functions in this project that don't have error handling and list them

Codex will:

Scan your project files
Identify functions without try/catch blocks or error returns
Present a list with file paths and line numbers

This is a read-only operation, so it runs immediately without asking for approval.

Now try something that modifies code:

> Add proper error handling to the fetchUserData function in src/api/users.ts

This time, Codex will propose changes and wait for your approval before applying them. You will see a diff showing exactly what will change. You can:

Accept the change (press Enter or type y)
Reject the change (type n)
Edit the proposed change before accepting
Ask for a different approach (describe what you want instead)

1You type a request

2Codex reads relevant files

3Codex forms a plan

4Read-only operation? Run immediately

5Write operation? Show diff and wait for approval

6You review and accept/reject/modify

7Codex applies approved changes

8Codex verifies (runs tests if applicable)

Understanding Approval Modes

Codex has three approval modes that control how much autonomy the agent has. This is the primary safety mechanism:

The most conservative mode. Codex can read files and run read-only commands, but every file edit and every shell command that could modify your system requires your explicit approval. This is the right mode when you are learning Codex, working on unfamiliar codebases, or doing anything where mistakes are costly. Think of it as pair programming where you approve every keystroke your partner makes.

Start with Suggest, Graduate to Auto-Edit

Most developers follow this progression: start with Suggest mode for a week to build trust and understand how Codex works. Move to Auto-Edit once you are comfortable reviewing diffs. Use Full Auto only for well-defined, isolated tasks where you have committed your current work to git first (so you can always revert).

Sandbox Enforcement

Codex enforces safety at the OS level -- not through prompt instructions that the model might ignore:

Approval Mode	File Writes	Shell Commands	Network
Suggest	Requires approval	Requires approval	Allowed (with approval)
Auto-edit	Auto-applied	Requires approval	Allowed (with approval)
Full-auto	Auto-applied (project dir only)	Auto-executed	Blocked

The sandbox is enforced at the OS level -- on macOS through Apple's Seatbelt framework (sandbox-exec), on Linux through Docker containers with iptables firewall rules. This is not a polite request to the agent. It is a hard enforcement boundary that the agent cannot bypass.

Your First Real Task

Here is a concrete exercise. Navigate to a project with tests and try this sequence:

Bash

codex
> Run the test suite and summarize any failures

Codex will run your test command, read the output, and give you a human-readable summary of what passed and what failed.

Then:

> Fix the first failing test

Watch the agent read the test file, read the source code under test, propose a fix, and -- after your approval -- verify the fix by re-running the test.

This is the core Codex loop: describe what you want, review the proposal, approve, verify. Every session you ever run will be some variation of this pattern.

beginner

Try this now:

Install Codex if you have not already
Navigate to any project with tests
Run codex and ask it to analyze your test coverage
Ask it to write a test for an untested function
Review the proposed test, accept it, and run the test suite

Notice how Codex handles the approval flow. Notice what it reads before proposing changes. Notice how it verifies its own work. These patterns will repeat in every lesson that follows.