Run Codex CLI Fully Local With Ollama, No API Key

Short answer: three commands put OpenAI's Codex CLI on a fully local model — npm install -g @openai/codex, ollama pull gpt-oss:20b (a 14GB download), then codex --oss. No API key, no sign-in, no per-token bill. Two things break most first runs: Codex requires Ollama 0.13.4 or newer (we hit this wall ourselves — older versions are refused outright), and it needs at least 32K tokens of context, which Ollama does not give you by default on machines under 24GB.

OpenAI shipped the --oss flag as a first-class part of Codex CLI, and Ollama announced the integration on its official blog on January 15, 2026. That makes this the most officially-supported local coding agent pairing that exists: the agent vendor built the flag, the runtime vendor documents it, and the default model — gpt-oss — was trained by the same company that built the agent. This guide is the verified version: every command checked against the current docs, the flags confirmed against codex-cli 0.146.0 on our own machine, and an honest section on where a 21B-parameter local model falls short of the cloud models Codex was designed around.

Why Run Codex Locally

Codex CLI with --oss gives you an autonomous terminal coding agent whose every token is generated on your own hardware — free after the 14GB download, and private by construction.

The case is the same one that made local coding agents a category:

• Zero marginal cost. A coding agent is the chattiest LLM workload there is — it reads files, plans, calls tools, reads results, and loops. Metered per token, that compounds into real money. Served from localhost, it compounds into nothing.
• Your code never leaves the machine. Codex sends file contents, diffs, and command output to the model. With --oss, "the model" is a process on your own box. For client work under NDA, that is the entire decision.
• No account, no key, no rate limits. codex --oss does not ask you to sign in. There is no quota to hit at 4pm.

The trade-off is capability, and we cover it honestly below — a 21B MoE model is not the frontier model Codex uses in the cloud, and you will feel the difference on hard multi-file work.

The 3-Command Setup

Install Codex CLI, pull gpt-oss:20b, run codex --oss. Before you start: check ollama --version — you need 0.13.4 or newer.

1. Install Codex CLI (commands per the official OpenAI Codex repo):

npm install -g @openai/codex
# or on macOS:
brew install --cask codex

2. Check your Ollama version, then pull the model. This is the step most guides skip, and it cost us our first run: codex-cli 0.146.0 refused our Ollama 0.12.3 install with the error "Ollama 0.12.3 is too old. Codex requires Ollama 0.13.4 or newer." Upgrade Ollama first if you are behind (new to Ollama? Start with our complete Ollama guide):

ollama --version        # must be 0.13.4+
ollama pull gpt-oss:20b # 14GB download

3. Launch Codex against the local model:

codex --oss

That single flag switches Codex from OpenAI's API to a local open-source provider and defaults to gpt-oss:20b on Ollama. Useful variations, all confirmed against the codex-cli 0.146.0 binary:

codex --oss --local-provider ollama   # pin the provider (ollama or lmstudio)
codex --oss -m gpt-oss:120b           # bigger model, if you have the memory
codex exec --oss "fix the failing test in utils.py"   # non-interactive, scriptable

There is also an escape hatch to Ollama's hosted models — codex --oss -m gpt-oss:120b-cloud — which gets you 120B-class quality without 120B-class hardware, but at the cost of the "fully local" property this page is about. It runs on Ollama's servers, not yours.

What gpt-oss Actually Needs

gpt-oss:20b is a 14GB download that OpenAI says runs "within 16GB of memory" — treat that as the floor, not the target. For Codex's agentic use, 24GB+ of RAM or VRAM is the realistic comfortable tier.

The numbers, with their sources — none of these are our measurements, so here is exactly who claims what:

Why we call 16GB a floor rather than a recommendation: the 16GB figure covers the quantized weights with minimal context. Codex needs at least 32K tokens of context (Ollama's own integration post), and the KV cache for that context plus your OS and browser all compete for the same memory as the ~13GB of weights. Telling detail from Ollama's own documentation: its context-length defaults are tiered by available VRAM (unified memory, on Macs) — machines under 24GB get 4K context by default, and only the 24-48GB tier defaults to the 32K Codex wants. Ollama's own docs recommend 64K+ for coding tools. Read those defaults as the vendor quietly telling you what each memory class comfortably handles.

Practical tiers, in plain terms:

• 16GB RAM/VRAM: it loads, with thin context and real memory pressure. Close everything else, keep context modest, expect slowdowns on long sessions.
• 24GB (RTX 3090/4090-class GPU, or 24-32GB Mac): the honest recommendation for daily Codex use at 32-64K context. See what else this tier runs in our best coding LLMs for 24GB VRAM picks.
• 16GB VRAM GPUs: gpt-oss:20b mostly fits but context spills to system RAM fast; our best coding LLMs for 16GB VRAM page covers the models that fit this tier with room to breathe.
• gpt-oss:120b: a different hardware class — 65GB of weights wants an 80GB datacenter GPU or a 96-128GB unified-memory machine. If that is not you, gpt-oss:20b locally or 120b-cloud hosted are the real options.

For the broader model-to-memory map beyond gpt-oss, our Ollama RAM/VRAM table covers every major model at every quant.

The 32K Context Trap

Codex requires at least 32K tokens of context, but Ollama defaults to 4K on machines with under 24GB of VRAM — so on exactly the hardware most people run gpt-oss:20b, the default context is 8x too small.

This mismatch is the second most common way a working install produces a broken-feeling agent: Codex plans, reads a few files, and then the conversation falls off the back of a 4K window and it loses the plot. The fix is one environment variable, straight from Ollama's context-length docs:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Ollama's docs recommend "at least 64000 tokens" for agents and coding tools specifically. If you run the Ollama desktop app instead of ollama serve, the same setting is a slider in the app's settings. Two caveats worth knowing:

• Context costs memory. The KV cache grows with the window. If 64K makes a 16GB machine swap, drop to 32K — Codex's stated minimum — before you shrink anything else.
• Verify placement with ollama ps after the first request. If the model shows partial CPU offload, per Ollama's own performance guidance you have overcommitted memory, and generation speed falls off a cliff. Reduce context until it is fully on GPU.

config.toml: Make It Stick

You do not need any config file — codex --oss works out of the box. Two lines in ~/.codex/config.toml make the local provider and model the default — and one popular snippet from older guides now breaks Codex outright.

The minimal config, verified to parse cleanly on codex-cli 0.146.0:

# ~/.codex/config.toml
oss_provider = "ollama"   # which runtime --oss uses: "ollama" or "lmstudio"
model = "gpt-oss:20b"     # default model for the session

oss_provider is the documented switch for which local runtime --oss targets — if it is unset, Codex prompts you to choose. With both lines in place, codex --oss starts straight into gpt-oss:20b, no menu.

Do not copy the [model_providers.ollama] block from older guides. Codex's early docs wired Ollama up as a custom provider table, and that pattern is all over 2026 tutorials. The current CLI refuses it — on 0.146.0 we got a hard error: "model_providers contains reserved built-in provider IDs: ollama. Built-in providers cannot be overridden." Ollama and LM Studio are built-in providers now; oss_provider is the entire configuration.

You can still override any config value per-invocation without editing the file — codex --oss -c model="gpt-oss:120b" — and codex exec accepts the same flags for CI and scripts. One honest note: Codex's config surface has been restructured more than once in 2026 (the docs moved domains, and profile syntax changed along the way), so when a key from an older third-party guide fails, trust the current official config reference — and your own binary's error message — over the guide.

Where gpt-oss:20b Falls Short

On OpenAI's own numbers, gpt-oss-20b scores 60.7 on SWE-bench Verified at high reasoning effort — genuinely strong for a model this size — but that score was produced on OpenAI's own eval harness at the slowest reasoning setting, and it drops to 53.2 at medium and 37.4 at low. Those three numbers, straight from the model card, are the honest performance envelope you live inside.

What that means in practice, from the published numbers and the model's architecture rather than marketing:

• Reasoning effort is the speed/quality dial, and local hardware makes it expensive. The SWE-bench spread above (60.7 → 53.2 → 37.4) is the cost of turning reasoning down. On a consumer machine, high reasoning means long thinking pauses before every action — the agentic loop magnifies this because every tool call pays the tax. Most people end up at medium, which means most people get the 53-point model, not the 60-point one.
• 3.6B active parameters is why it is fast — and why depth suffers. The MoE design activates a fraction of the 21B weights per token. Great for tokens per second; noticeably weaker than dense frontier models on sprawling, multi-file architectural changes where one edit must stay coherent with nine others.
• Long sessions hit the context ceiling. Cloud Codex models operate with much larger effective context budgets than the 32-64K you will realistically run locally. On big repos, expect the local agent to lose track of earlier decisions sooner, and to benefit from smaller, well-scoped tasks.
• Where it is genuinely good: focused single-file edits, writing tests, boilerplate, explaining unfamiliar code, and mechanical refactors. Scope your asks like tickets, not epics, and the local agent completes a surprising share of them.

One thing we will not do is quote tokens-per-second figures for hardware we have not measured — speed varies enormously with context length, reasoning effort, and memory placement. Run ollama ps to check placement, and judge speed on your own machine in the first ten minutes.

Freshness note: OpenAI has signaled continued investment in the open-weight line. When a successor to gpt-oss ships, revisit the model choice here — the --oss wiring stays the same, and -m takes whatever tag replaces it.

Alternatives

If Codex's agent style does not fit, the same local-first pattern exists in three other mature flavors.

• Claude Code offline with Ollama — Anthropic's agent pointed at local models via a proxy shim. More setup friction than --oss (the integration is community-built, not vendor-built), but the harness is excellent.
• Aider + Ollama — the git-native terminal pair programmer. Less autonomous than Codex, more surgical: every edit is a reviewable commit. The best fit when you want control over every change.
• A different model under Codex itself — codex --oss -m accepts any Ollama model. The main requirement is reliable tool calling, which most chat models fumble; Qwen3 Coder is the strongest local alternative trained specifically for agentic coding.

Verdict

codex --oss is the lowest-friction fully-local coding agent setup that currently exists — three commands, no account, no key — provided you respect three numbers: Ollama 0.13.4+, 32K minimum context, and 24GB of memory for comfort.

1. Setup is genuinely trivial — this is a vendor-built integration on both ends, not a community shim. Install, pull, codex --oss.
2. The two silent killers are version and context. Pre-0.13.4 Ollama is refused outright (we hit it), and sub-24GB machines default to a 4K context that makes the agent seem broken. Check both before blaming the model.
3. Be honest with yourself about the 16GB claim. It loads in 16GB; it works in 24GB. Between OpenAI's floor and Ollama's own context-tier defaults, the vendors are telling you the same thing quietly.
4. Scope tasks like tickets. At 53-60 SWE-bench points (OpenAI's own range across reasoning efforts), gpt-oss-20b is a strong junior agent, not a cloud frontier model. Feed it focused tasks and it earns its 14GB.

Free, private, official, and honest about its ceiling — that is a better deal than most of what shipped in local AI this year.

Sources

• Ollama blog: OpenAI Codex with Ollama (January 15, 2026) — the official integration announcement; source for the --oss default model and 32K context minimum
• OpenAI Codex repository — install commands and CLI documentation; config reference at the official Codex docs (source for oss_provider)
• Ollama library: gpt-oss — download sizes, context window, quantization
• OpenAI gpt-oss model card (Hugging Face) — parameter counts, memory claims, SWE-bench Verified scores by reasoning effort, license
• Ollama docs: context length — default context tiers by memory, OLLAMA_CONTEXT_LENGTH, the 64K recommendation for coding tools
• Our own verification (August 2026): flags, version gate, working config.toml, and the built-in-provider rejection all confirmed against codex-cli 0.146.0 with Ollama on macOS

FAQ