Comprehensive Guide to Installing Codex CLI on Linux

---

Introduction

OpenAI’s Codex CLI is a powerful, terminal-based AI coding assistant that brings AI-powered development capabilities directly to your command line. Launched in 2025, this lightweight tool allows developers to generate code, debug issues, refactor projects, and automate workflows using natural language commands—all while keeping your code securely on your local machine.

This comprehensive guide walks you through the complete installation process for Codex CLI on Ubuntu Linux systems, from prerequisites to advanced configuration.

---

What is Codex CLI?

Codex CLI is an open-source command-line interface powered by OpenAI’s advanced language models (including GPT-5 and GPT-5-Codex). Unlike traditional IDE plugins, it operates directly in your terminal, offering:

• Natural Language Coding: Generate code using plain English prompts
• Local Execution: All operations occur on your machine—sensitive code never leaves your environment
• Agent Internet Access: Optional internet connectivity for installing dependencies or fetching resources (with granular controls)
• Rust-Based Performance: Rewritten in Rust for zero-dependency installation, improved performance, and enhanced security
• Version Control Integration: Works seamlessly with Git for tracking changes

Codex CLI is ideal for quick prototyping, automating repetitive tasks, generating boilerplate code, and enhancing productivity without leaving your terminal.

---

Prerequisites

Before installing Codex CLI, ensure your Ubuntu system meets these requirements:

System Requirements

• Operating System: Ubuntu 20.04 LTS or newer (Ubuntu 22.04 LTS or 24.04 LTS recommended for enterprise deployments)
• RAM: Minimum 2GB, 4GB recommended for development environments
• Storage: At least 500MB free space
• Internet Connection: Required for API communication with OpenAI’s servers

Required Software

1. Node.js (v18 or higher)
2. npm (comes with Node.js)
3. Git (recommended for version control)

OpenAI Account

You’ll need one of the following:

• A ChatGPT account with Codex access
• An OpenAI API key with appropriate permissions

---

Installation Methods

Method 1: Using npm (Recommended)

This is the most straightforward method for Ubuntu users, providing automatic dependency management and easy updates.

Step 1: Install Node.js and npm

First, check if Node.js is already installed:

node --version
npm --version

If not installed or the version is below v18, install the latest LTS version:

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# Install Node.js and npm
sudo apt install -y nodejs

# Verify installation
node --version
npm --version

Alternative: Using NVM (Node Version Manager)

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install Node.js LTS
nvm install --lts

# Verify installation
node --version
npm --version

Step 2: Install Git (if not already installed)

# Install Git
sudo apt install -y git

# Verify installation
git --version

Step 3: Install Codex CLI

Install Codex CLI globally using npm:

npm install -g @openai/codex

Step 4: Verify Installation

Check that Codex is installed correctly:

codex --version

You should see output similar to: codex-cli 0.2.0

---

Method 2: Using Homebrew

If you have Homebrew installed on your Linux system, you can use it to install Codex:

Step 1: Install Homebrew (if not installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Follow the on-screen instructions to add Homebrew to your PATH

Step 2: Install Codex

brew install codex

Step 3: Verify Installation

codex --version

---

Method 3: Direct Binary Download

For a zero-dependency installation, you can download pre-compiled Rust binaries directly from GitHub.

Step 1: Download the Latest Release

Visit the Codex GitHub Releases page or download directly:

# Download the latest Linux binary
wget https://github.com/openai/codex/releases/latest/download/codex-linux -O codex

# Make it executable
chmod +x codex

# Move to system path
sudo mv codex /usr/local/bin/codex

Step 2: Verify Installation

codex --version

---

Authentication Setup

After installation, you need to authenticate Codex with your OpenAI account.

Option 1: ChatGPT Account Authentication

Run Codex for the first time:

codex

You’ll be prompted to sign in with your ChatGPT account. Follow the on-screen instructions to authenticate via your browser.

Option 2: API Key Authentication

If you prefer to use an API key:

Step 1: Set Environment Variable

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

Step 2: Make It Persistent

Add the environment variable to your shell configuration file:

# For Bash users
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# For Zsh users
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Step 3: Run Codex

codex

The CLI will automatically use your API key for authentication.

---

Configuration

Codex CLI stores its configuration in ~/.codex/config.toml. You can customize various settings including model providers, internet access, and security controls.

Basic Configuration

Create or edit the configuration file:

mkdir -p ~/.codex
nano ~/.codex/config.toml

Example Configuration

# Model settings
model = "gpt-5-codex"

# Internet access settings (disabled by default)

[internet]

enabled = false allowed_domains = [“pypi.org”, “npmjs.com”] allowed_methods = [“GET”] # Security settings

[security]

confirm_before_execution = true sandbox_enabled = true

Using Local LLM (Optional)

If you want to use a local model via Ollama:

# Use Ollama as model provider
model = "gpt-oss:20b"
model_provider = "ollama"

[model_providers.ollama]

name = “Ollama (local)” base_url = “http://127.0.0.1:11434/v1” wire_api = “chat”

---

Getting Started with Codex

Running Codex

Navigate to your project directory and start Codex:

cd /path/to/your/project
codex

Basic Commands

Once inside the Codex CLI:

• Switch models: /model – Choose between GPT-5-Codex and GPT-5
• Check status: /status – View workspace, active model, and token usage
• View transcript: Press Esc twice or Ctrl+T to see behind-the-scenes reasoning
• Exit: Type exit or press Ctrl+D

Example Prompts

Try these natural language commands:

"Create a simple React todo app with localStorage persistence"

"Add error handling to the authentication module"

"Refactor this code to use async/await instead of callbacks"

"Write unit tests for the user service"

"Optimize this SQL query for better performance"

---

Key Features

1. Interactive Terminal UI (TUI)

Codex provides a rich terminal interface for conversational coding sessions.

2. Agent Mode

Codex can autonomously:

• Read files in your repository
• Modify and create files
• Execute commands
• Install dependencies

3. Code Review

Get your code reviewed by a separate Codex agent before committing:

codex review

4. Reasoning Transparency

View the AI’s thought process and tool usage:

• Press Esc twice to open the transcript window
• Press q to return to the main interface

5. Attach Files and Screenshots

Include design specs or screenshots in your prompts for context-aware code generation.

6. YOLO Mode

For hands-off execution, enable YOLO mode to let Codex work autonomously without confirmations.

---

Updating Codex

New versions are released regularly. To upgrade:

If Installed via npm

npm update -g @openai/codex

If Installed via Homebrew

brew upgrade codex

Using Built-in Upgrade Command

codex --upgrade

Check Changelog

View release notes at Codex CLI Changelog

---

Security Best Practices

1. Use Version Control

Always create Git checkpoints before running Codex:

git add .
git commit -m "Before Codex changes"

After Codex completes its task, review changes:

git diff

2. Internet Access Controls

Keep internet access disabled by default. Enable only for specific tasks:

# In your config file, specify allowed domains

[internet]

enabled = true allowed_domains = [“pypi.org”, “npmjs.com”, “github.com”] allowed_methods = [“GET”]

3. Review Changes Before Accepting

Use the transcript view to understand what Codex is doing before accepting file modifications.

4. Sandbox Mode

Ensure sandbox mode is enabled in your configuration to prevent unauthorized filesystem access:

[security]
sandbox_enabled = true
confirm_before_execution = true

5. Protect Sensitive Data

Never commit API keys or sensitive configuration to version control:

# Add to .gitignore
echo ".codex/credentials" >> .gitignore
echo ".env" >> .gitignore

---

Troubleshooting

Issue 1: Command Not Found

Problem: codex: command not found after installation

Solution:

# Check if npm global bin is in PATH
echo $PATH

# If not, add it to your shell configuration
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Issue 2: Node.js Version Too Old

Problem: Codex requires Node.js v18 or higher

Solution:

# Update Node.js using nvm
nvm install --lts
nvm use --lts

# Or reinstall via NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

Issue 3: Permission Denied

Problem: Permission errors during npm installation

Solution:

# Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Reinstall Codex
npm install -g @openai/codex

Issue 4: Authentication Fails

Problem: Unable to authenticate with OpenAI

Solution:

1. Verify your OpenAI subscription includes Codex access
2. Check if your API key is valid: echo $OPENAI_API_KEY
3. Try removing existing credentials: rm -rf ~/.codex/credentialscodex

Issue 5: Network Connectivity Issues

Problem: Codex can’t connect to OpenAI API

Solution:

# Test connectivity
curl -I https://api.openai.com

# Check if proxy settings are needed
export HTTP_PROXY="http://your-proxy:port"
export HTTPS_PROXY="http://your-proxy:port"

Issue 6: Slow Performance

Problem: Codex runs slowly

Solution:

1. Check system resources: htop
2. Ensure you have adequate RAM (4GB+ recommended)
3. Switch to a faster model if using a local LLM
4. Close unnecessary applications

---

Conclusion

Codex CLI is a transformative tool that brings AI-powered coding assistance directly to your terminal. With its local execution model, security controls, and powerful natural language interface, it enables developers to work faster and more efficiently.

By following this guide, you should now have Codex CLI installed and configured on your Ubuntu Linux system. Remember to:

• Keep your installation updated
• Use version control for all Codex changes
• Review and understand the code Codex generates
• Follow security best practices

For more information, visit:

• Official Codex CLI Documentation
• GitHub Repository
• OpenAI Documentation

Happy coding with Codex CLI!