Install OpenAI Codex CLI on Ubuntu Linux

OpenAI's Codex CLI has evolved from the lightweight terminal agent launched in April 2025 into the central hub of an entire coding platform — spanning terminal, IDE extension, cloud environment, and desktop app. Two things have changed enough to matter for anyone installing it today: OpenAI now ships an official standalone installer that removes the Node.js dependency entirely, and the model lineup has moved on to the GPT-5.6 family — Sol, Terra, and Luna.

Because most readers arrive here to install the thing and get moving, the install steps come first. Below you will find a 60-second quick start, then every supported installation method ranked in the order OpenAI itself recommends them, followed by community options and the deeper configuration material — models, sandbox and approval modes, MCP servers, agent skills, and enterprise security.

# 1. Install (official installer — macOS and Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 2. Verify
codex --version

# 3. Open a project and sign in
cd your-project-directory
codex

Installation Methods, Ranked

OpenAI documents four supported ways to install Codex CLI. They are listed below in the order OpenAI presents them in its own documentation and repository — official and recommended first, then community-maintained options that are not operated by OpenAI.

Official Method 1 — Standalone Installer (Recommended)

This is the path OpenAI leads with for macOS and Linux. It downloads a self-contained binary, so there is no Node.js or package manager dependency to maintain:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

To upgrade later, run exactly the same command — the installer replaces the existing binary in place.

Official Method 2 — npm

Best if your team already standardizes developer tooling through Node.js and npm, or you want to pin a specific version:

npm install -g @openai/codex

# Pin or upgrade to a specific release
npm install -g @openai/codex@latest

The published package declares a minimum of Node.js 16, but install it on a current LTS release (Node 20 or 22) for the smoothest experience. Ubuntu's default repositories often ship an older Node.js, so install from NodeSource if needed:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

Official Method 3 — Homebrew

Supported on Linux for teams already using Homebrew as their cross-platform package manager:

brew install --cask codex

# Upgrade
brew upgrade --cask codex

Official Method 4 — Direct Binary Download

Best for air-gapped environments, golden images, container builds, or any situation where you want a pinned, auditable artifact. Download the appropriate archive from the project's GitHub Releases page:

# x86_64 (most Ubuntu servers and desktops)
codex-x86_64-unknown-linux-musl.tar.gz

# ARM64 (Ampere, Graviton, Raspberry Pi 4/5, etc.)
codex-aarch64-unknown-linux-musl.tar.gz

# Extract, rename to "codex", make executable, put it on PATH
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl codex
chmod +x codex
sudo mv codex /usr/local/bin/

Each archive contains a single binary with the platform baked into the filename, so rename it to codex after extracting. Because these builds are statically linked against musl, they run across distributions without glibc version headaches.

Community and Unofficial Methods

These are not maintained or endorsed by OpenAI. They can be perfectly workable, but they lag official releases and carry supply-chain considerations that matter in a business environment:

• Community distro packages: User-maintained packages such as Arch's AUR entries and various third-party repositories. Convenient on those distributions, but update on the packager's schedule, not OpenAI's.
• Third-party install scripts and wrappers: Blog-published one-liners and convenience wrappers. Treat any curl | sh from a non-OpenAI domain as untrusted code execution and read it first.
• Building from source: Codex CLI is open-source and Rust-based, so you can clone the repository and build it yourself. This is the right path for contributors or teams that must compile everything in-house, at the cost of managing a Rust toolchain.
• Unofficial container images: Community Docker images bundling Codex CLI. Useful for CI experimentation; verify the provenance and pinned version before relying on one.

Verify the Installation

codex --version
which codex

If the shell reports command not found, the binary is installed but not on your PATH. For npm installs with a user-level prefix, confirm ~/.npm-global/bin is in your PATH; for direct binary installs, confirm the file landed in /usr/local/bin and is executable.

Authenticate

Launch Codex in a project directory to complete first-run authentication:

cd your-project-directory
codex

Sign in with ChatGPT (recommended): Select "Sign in with ChatGPT." Codex starts a temporary local OAuth server and opens your browser. After you complete the flow, return to the terminal — tokens are stored automatically. This is the simplest onboarding and gives you Codex model access through your existing Plus, Pro, Business, Edu, or Enterprise plan.

API key: For CI/CD pipelines, headless servers, and environments without a browser, use an API key instead:

# Current session
export OPENAI_API_KEY="sk-your-api-key-here"

# Persist across sessions
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Generate keys at platform.openai.com/api-keys. Model availability differs between subscription sign-in and API-key access, so confirm which models your key can reach before standardizing a headless workflow. Never commit API keys to version control or store them in plain text inside a repository — use your CI platform's secret store instead.

Prerequisites and Environment Notes

• Ubuntu 20.04+ (22.04 LTS or 24.04 LTS recommended for business deployments); the musl binaries also run on other mainstream distributions
• Node.js — only required for the npm method. The standalone installer, Homebrew, and direct binary paths have no Node dependency
• Git 2.23+ recommended for repository-aware operations
• Outbound HTTPS to OpenAI endpoints — all model inference runs in the cloud
• A ChatGPT plan (Plus, Pro, Business, Edu, or Enterprise) or an API key
• 2GB+ RAM — the CLI itself is lightweight because inference is remote

What Codex CLI Does in 2026

Codex CLI is an open-source, Rust-based coding agent that runs locally in your terminal and connects to OpenAI's cloud models for inference. Your code stays on your machine and executes locally; the reasoning that interprets prompts and generates solutions happens in OpenAI's cloud. This hybrid architecture lets Codex use models far more powerful than anything that would run on a development workstation, while leaving developers in control of what actually executes in their environment.

The product now spans four surfaces, all connected through your ChatGPT account so context moves between them:

• Codex CLI: The open-source terminal agent. Reads, edits, and runs code locally with configurable approval modes and sandbox isolation.
• Codex IDE Extension: A VS Code extension bringing the same agentic capabilities into the editor, sharing MCP and configuration with the CLI.
• Codex Cloud: An asynchronous web environment where tasks run in isolated containers with your codebase preloaded.
• Codex App: A dedicated desktop application with full model selection, skills, and MCP support.

Current capabilities include natural language code generation and editing across multiple files, codebase understanding, multimodal input (screenshots, wireframes, diagrams), Git-aware operations, MCP server integration, agent skills for repeatable workflows, mid-turn steering, built-in web search, automated code review, and thread resume across restarts [OpenAI].

The Model Lineup

The model lineup changed materially in mid-2026. Codex now runs on the GPT-5.6 family, which uses a tiered naming scheme: the number identifies the generation, while Sol, Terra, and Luna are durable capability tiers that advance on their own cadence. Switch models mid-session with the /model command.

Plan availability differs by tier: Free and Go users get GPT-5.6 Terra, while Plus, Pro, Business, and Enterprise users can choose among Sol, Terra, and Luna and set a reasoning-effort level for each [OpenAI]. Note that the GPT-5.3-Codex models are deprecated in Codex when you sign in with ChatGPT — if your notes, scripts, or team documentation still reference them, update those to a GPT-5.6 tier.

Understanding Approval Modes and Sandbox

Codex CLI provides granular control over what the AI agent can do on your system. These aren't just preferences — for enterprise environments, they're security controls that determine the agent's blast radius.

Switch modes dynamically with /approvals read-only, /approvals auto, or /approvals full-access. On Linux, Codex now uses bubblewrap for sandbox isolation — providing configurable read-only access policies, shell environment controls, and restrictions on what the agent can reach. Configure these in ~/.codex/config.toml:

# Control which env vars Codex forwards to spawned commands
[shell_environment_policy]
include_only = ["PATH", "HOME"]

# Web search configuration
web_search = "cached"   # "cached" (default), "live", or "disabled"

Essential Commands and Configuration

Codex also supports steer mode — press Enter while Codex is running to inject new instructions into the current turn, or press Tab to queue a follow-up prompt for the next turn. This enables real-time course correction without canceling and restarting. The @ key opens fuzzy file search in the composer, and prefixing a line with ! runs a local shell command directly.

Setting Up MCP Servers

The Model Context Protocol connects Codex to external tools, documentation, and services. MCP configuration lives in ~/.codex/config.toml and is shared between the CLI and IDE extension — configure once, use everywhere.

Adding Context7 for Real-Time Documentation

# Add Context7 for up-to-date library documentation
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Add Playwright for browser automation
codex mcp add playwright -- npx @playwright/mcp@latest

# View all configured MCP servers
codex mcp --help

Inside a Codex session, use /mcp to view active servers and their available tools. MCP servers can also be configured directly in config.toml for more control:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.openaiDeveloperDocs]
type = "streamable_http"
url = "https://developers.openai.com/mcp"

Codex also supports Streamable HTTP servers (remote MCP servers accessed via URL) and OAuth authentication for MCP servers that require it. If your OAuth provider requires a static callback URI, set mcp_oauth_callback_port in config.toml.

For organizations deploying AI development tools across teams, MCP server configurations can be scoped to projects via .codex/config.toml in the project root (trusted projects only), ensuring all team members access the same integrations.

Agent Skills: Repeatable Workflows

Skills package instructions, resources, and optional scripts so Codex can follow complex workflows reliably. They use progressive disclosure — Codex starts with each skill's metadata and loads full instructions only when needed.

A skill is a directory with a SKILL.md file containing a name, description, and instructions. Skills can be stored at the repository level (.agents/skills/), user level, or system level. Codex detects skill changes automatically.

# View available skills
/skills

# Invoke a skill explicitly with $
> $my-skill Fix the authentication flow

# Skills can also be implicitly invoked when your prompt matches the skill description

Skills can declare MCP server dependencies, so enabling a skill automatically ensures the required tools are available. For teams, sharing skills through version control creates consistent, auditable workflows that don't depend on individual developer configurations.

Enterprise Security Considerations

Deploying an AI coding agent that sends code context to cloud services for inference requires security planning that goes beyond traditional development tools. Codex CLI's architecture — local execution with cloud-based reasoning — creates specific requirements for organizations managing sensitive code.

• Network controls: Whitelist api.openai.com in firewall configurations. If web search is enabled, additional outbound access may be needed. Monitor outbound API traffic for anomalous patterns.
• Data privacy: Review OpenAI's data usage policies for your subscription tier. Business and Enterprise plans provide enhanced data privacy commitments. Restrict Codex to non-sensitive codebases initially and implement code classification policies for AI tool usage.
• API key management: Implement rotation policies (90-day maximum). Use separate keys for different environments. Store keys in environment variables or secrets management services — never in version control.
• Sandbox configuration: Use the Linux bubblewrap sandbox and shell_environment_policy to restrict what Codex can access. Configure read-only access for exploratory work. Use auto mode for routine development and reserve full-access for isolated test environments only.
• Code review requirements: Require human review for all AI-generated commits. Codex includes a built-in code review feature that can catch issues before shipping, but it should supplement rather than replace human review processes.
• Compliance evaluation: Assess Codex usage against organizational requirements including HIPAA, CMMC, and SOC 2 frameworks. Document AI tool usage in security policies and maintain audit logs of Codex operations.
• Enterprise admin controls: Organizations can use requirements.toml to restrict web search modes, define network constraints, and enforce approval policies across the team.

Troubleshooting Common Issues

npm config get prefix
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="~/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm i -g @openai/codex

Sources

• OpenAI. "Codex CLI." Developer Documentation, 2026. developers.openai.com/codex/cli
• OpenAI. "Model Context Protocol." Codex Documentation, 2026. developers.openai.com/codex/mcp
• OpenAI. "GPT-5.6: Frontier intelligence that scales with your ambition." OpenAI Blog, 2026. openai.com/index/gpt-5-6
• OpenAI. "A preview of GPT-5.6 Sol, Terra and Luna." OpenAI Help Center, 2026. help.openai.com
• OpenAI. "Introducing upgrades to Codex." OpenAI Blog, 2025. openai.com/index/introducing-upgrades-to-codex
• OpenAI. "Codex Changelog." Developer Documentation, 2026. developers.openai.com/codex/changelog
• OpenAI. "openai/codex." GitHub Repository, 2026. github.com/openai/codex