How to Install Codex CLI on Linux: A 15-Minute Tutorial

Codex CLI is OpenAI’s terminal coding agent: you point it at a repo, type a task in plain English, and it reads files, edits code, and runs commands inside an approval loop. I’ve run it daily on a Ubuntu 24.04 machine for about a month. This is the install path that worked cleanly, plus the workflows where it actually earned its place.

A quick, honest note up front: Codex CLI is one of several agents now in this space. If you prefer a Chinese-made option, Trae (by ByteDance), Qwen Code (Alibaba’s Qwen team), DeepSeek’s coding tools, and WorkBuddy are all worth a look and are mentioned at the end. Use what fits your stack.

Prerequisites

You need a Linux box with a terminal and a network connection. The agent itself is a Node.js package, so the only real dependency is a recent Node.

• A Debian/Ubuntu system (22.04 or newer is safest)
• Node.js 20 or newer
• An OpenAI API key with access to the Codex model
• About 15 minutes, mostly waiting on installs

Step 1: Install Node.js

Check what you have:

node --version

If you see a version under 20, or nothing, install a current release. The clean route on Ubuntu is the NodeSource setup:

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesetup.sh
sudo -E bash /tmp/nodesetup.sh
sudo apt-get install -y nodejs

Confirm with node --version again. You should see 22.x.

If your distribution ships an old Node in its default repository, resist the urge to install it from apt alone. Mixing an apt Node with a NodeSource install is the most common way people end up with two binaries and a codex command that resolves to the wrong one. Install one, then verify with which node and which npm. If your project needs several Node versions over time, a version manager is a better long-term answer, and it also keeps you from needing sudo for global packages.

Step 2: Install Codex CLI globally

sudo npm install -g @openai/codex

The -g flag puts the binary on your PATH so you can call codex from any project. Verify:

codex --version

If that prints a version, the install worked.

A permissions note that saves people a confusing hour: if you installed Node with a version manager, do not use sudo for the global install. Running sudo npm install -g against a user-owned Node directory creates root-owned files that break later updates with permission errors. If you already did it, fix ownership rather than escalating every future command.

Step 3: Authenticate

Codex reads your key from the environment, not a login form. Export it for the session:

export OPENAI_API_KEY="sk-..."

For a permanent setup, add that line to your shell profile (for example ~/.bashrc or ~/.zshrc) so it loads on every terminal. Never paste the key into a shared dotfile or commit it.

Two hygiene rules I follow and recommend without exception. Keep the key in a file that is not tracked by git, and if you keep dotfiles in a repository, source the secret from a separate untracked file. Rotate the key if it has ever been on screen in a recording, a screenshot, or a chat with a tool that logs input. An API key in a public repository is found by scrapers within minutes, and the resulting bill arrives on your account, not theirs.

Set a spending limit on the API account before you start. Coding agents are chatty: they read files, retry edits, and run commands, and a large repository can consume far more tokens than a conversation ever would. A limit turns a potential surprise into a non-event.

Step 4: Run it inside a project

Change into a repo and start the agent:

cd ~/projects/my-app
codex

You’ll get a prompt. Try a small, safe task first:

codex "add a comment block explaining the main function in src/app.js"

Codex will propose the edit and ask for approval before writing. That approval gate is the whole point — read what it wants to change.

The first session in any new repository should be read-only exploration. Ask it something like “summarize the structure of this project and where the request handling lives.” You learn whether its understanding is accurate before you let it write anything, and you get a free architecture review out of it.

Step 5: Tune the config

Codex stores settings in ~/.codex/config.toml. A minimal useful config looks like this:

model = "gpt-5-codex"
approval = "on-request"
sandbox = "workspace-write"

Lines like these keep the agent from touching anything outside your project folder and force approval on edits. Adjust the model name to whatever your key supports.

The sandbox setting deserves a sentence of its own. On a machine with production credentials in your environment, an agent that can run arbitrary commands inherits all of them. Confining writes to the workspace and requiring approval for anything else is the difference between a helpful assistant and an incident report. If you want to go further, run the agent inside a container or a virtual machine dedicated to the project.

5 workflows that earned their keep

1. Boilerplate cleanup. “Rename the old utils import to helpers across the repo.” It found every reference faster than I would.
2. Test scaffolding. “Write a unit test for the calculateTotal function using the existing test framework.” It matched the project’s style because it read neighboring tests.
3. README drafts. “Summarize the CLI flags from the source into a Usage section.” Saved me a dull afternoon.
4. Bug triage. “Find where the null pointer on login comes from and suggest a fix.” It pointed at the right file; I made the call.
5. Refactors. “Extract the date formatting into its own module.” Approved step by step, no surprises.

None of these replaced judgement. They replaced typing.

Where it struggles

Honesty matters more than enthusiasm here. The agent is weak on tasks whose correctness depends on context it cannot see: why a rule exists, what the customer actually asked for, whether a workaround is load-bearing. It will happily “clean up” a line that was deliberately written that way, and the diff looks reasonable until something breaks in production.

It also struggles with ambiguity in proportion to the size of the change. A vague prompt that touches one file is cheap to review; the same prompt across fifteen files is a review burden that exceeds the typing it saved. The fix is not a better tool, it is a smaller task.

Finally, token cost scales with repository size, because the agent reads broadly before it writes. On a monorepo, a request that looks trivial can be expensive. If you work in a large codebase, scope the agent to a subdirectory where possible.

Chinese alternatives worth a look

• Trae — a Chinese-built AI IDE/agent with a strong free tier and Chinese-language support.
• Qwen Code — Alibaba’s Qwen team ships a coding agent that runs in the terminal and pairs well with their models.
• DeepSeek — strong reasoning models that work as a backend for editor agents.
• WorkBuddy — a Chinese dev/work assistant that bundles coding and task automation.

If your team is China-based or works mainly in Chinese, one of these may fit better than a US-only tool. Latency, access, and language support are all practical advantages that do not show up in a feature table.

Pros and cons

Pros

• Lives in the terminal; no context switching
• Approval loop keeps you in control
• Reads the whole repo, so edits match existing style

Cons

• Needs a paid API key
• Can over-edit if you approve too fast
• Occasionally misunderstands intent on vague prompts

Buying advice

Install it on a scratch repo first. Run three small, safe tasks and watch exactly what it changes. Only then point it at real work. And keep your API key out of git.

FAQ

Q: Do I need a GPU to run Codex CLI on Linux? A: No. The model runs in the cloud; your machine only needs Node.js and network access.

Q: Is Codex CLI free? A: The CLI is open, but it calls a paid model through your API key, so usage costs money per request.

Q: What if I’d rather use a Chinese-made coding agent? A: Trae, Qwen Code, DeepSeek, and WorkBuddy are solid alternatives and often better for Chinese-language workflows.

Q: Can it break my project? A: It can produce a bad edit, but the approval gate and a version-controlled working tree mean you can always discard the change. Commit before each session and nothing is unrecoverable.

Q: How do I keep costs down? A: Set an API spending limit, scope the agent to a subdirectory in large repositories, and write specific prompts so it reads less and edits once.

See current prices →

Disclosure: if you order through our link, TechMinds may earn a small commission at no extra cost to you.