OpenAI Codex CLI: install and run your first cloud agent

What Codex CLI does

Codex CLI is a terminal application that connects to OpenAI's models to perform coding tasks against your local codebase. You describe what you want in natural language, and the agent reads your files, plans an approach, and generates code changes. Unlike inline copilot tools, Codex CLI operates at the project level and handles multi-file changes in a single pass.

The distinguishing feature is cloud-sandboxed execution. When Codex CLI needs to run code (tests, build commands, scripts), it executes in a remote sandbox rather than on your local machine. Changes come back as diffs you review and approve before they touch your files.

Install Codex CLI

Install globally via npm:

npm install -g @openai/codex

Verify the installation:

codex --version

Codex CLI requires Node.js 18 or newer. If you are managing multiple Node.js versions, use mise or nvm to switch.

Configure authentication

Codex CLI supports two authentication methods:

Option A: API key (pay-per-token)

Set your OpenAI API key as an environment variable:

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

Add this to your shell profile (~/.zshrc or ~/.bashrc) so it persists across sessions. With API key auth, you pay per token at OpenAI's published rates.

Option B: ChatGPT subscription

If you have ChatGPT Plus or Pro, authenticate with your account:

codex login

This opens a browser window for OAuth authentication. After login, Codex CLI uses your subscription quota. This is often cheaper for moderate daily use compared to API pay-per-token.

Run your first task

Navigate to a project directory and start Codex CLI:

cd ~/projects/my-app
codex

Type a task:

Add input validation to the user registration endpoint. Email must be valid, password must be at least 8 characters with one number.

Codex reads your project structure, identifies the relevant files, and generates changes. It shows you a diff of proposed changes and waits for your approval before writing to disk. Type y to accept, n to reject, or e to edit the changes before applying.

Running in full-auto mode

For trusted tasks, you can skip the approval step:

codex --full-auto "Write unit tests for src/utils/validation.ts"

In full-auto mode, Codex applies changes immediately without prompting for review. Use this only for low-risk tasks like generating tests or documentation. For production code changes, the review-and-approve flow is safer.

Multi-agent runs

You can run multiple Codex sessions in parallel against the same or different projects. Open separate terminal tabs:

# Terminal 1
cd ~/projects/frontend && codex "Refactor the dashboard component to use React Query"

# Terminal 2
cd ~/projects/backend && codex "Add rate limiting middleware to all API routes"

Each session maintains independent context. Be careful with parallel sessions on the same project directory: concurrent file writes can conflict. For same-project parallelism, work on different file groups.

Pricing breakdown

Codex CLI pricing follows OpenAI's standard API token rates. The models available and their costs as of May 2026:

• o4-mini: $1.50 input / $6.00 output per million tokens. The default model. Good balance of speed and capability.
• o3: $2.00 input / $8.00 output per million tokens. Stronger reasoning, higher cost.
• GPT-4o: $2.50 input / $10.00 output per million tokens. Broad capabilities, highest per-token cost.

A typical one-hour coding session consumes 100K to 300K tokens total. At o4-mini rates, that is roughly $0.30 to $1.50 per hour. Heavy users running 6 to 8 hours per day can expect $5 to $15 per day in API costs.

If you have a ChatGPT Plus ($20/month) or Pro ($200/month) subscription, CLI usage counts against your subscription limits. This is usually cheaper than API rates for 2 or more hours of daily use.

Cloud sandbox explained

When Codex CLI needs to execute code, it ships the relevant files to an OpenAI-hosted sandbox, runs the commands there, and returns the output. This has two consequences:

• Safety: A runaway script cannot delete your local files or consume your machine's resources. The sandbox is disposable and isolated.
• Latency: Every execution round trip adds 2 to 5 seconds of network latency compared to local execution. For tasks with many iterative runs (debugging, test-driven development), this adds up.

The sandbox has access to common developer tools (Node.js, Python, Go, Rust toolchains) but does not have access to your local databases, environment variables, or private network services. If your task requires connecting to a local database, you will need to provide mock data or use a remote database the sandbox can reach.

Troubleshooting

• codex: command not found: Ensure the npm global bin directory is in your PATH. Run npm bin -g to find the directory and add it to your shell profile.
• Authentication errors: If using an API key, verify it starts with sk- and has not been revoked in your OpenAI dashboard. If using login, run codex logout then codex login again.
• Sandbox timeout: Long-running tasks (over 5 minutes of execution) may hit the sandbox timeout. Break large tasks into smaller steps.
• Stale diffs: If you modify files outside Codex while it is planning, the generated diffs may not apply cleanly. Restart the session after making external changes.

Next steps

With Codex CLI running, explore the AGENTS.md convention for project-specific instructions, set up a .codex/ config directory for per-project model selection, and try the --full-auto flag for batch operations. For a comparison with Claude Code and other terminal agents, see the agentic AI overview.

Frequently asked questions