---
title: "Codex + Ollama: run OpenAI Codex CLI on a local model — Aventail™ Guides"
url: https://aventail.co.uk/guides/codex-ollama
description: "Run OpenAI Codex CLI on a local model with Ollama: ollama launch codex, the --oss flag, the config.toml provider block, context length, models and limits."
lang: en-GB
---

Skip to content

Aventail™ investigation into UK government AI dependence featured in Computer Weekly. Read the story: https://aventail.co.uk/newsroom/computer-weekly-uk-government-ai-dependency

All guides (https://aventail.co.uk/guides)

# Codex + Ollama: run OpenAI Codex CLI on a local model

16 November 2026 12 min read

Run OpenAI Codex CLI on a local model with Ollama: ollama launch codex, the --oss flag, the config.toml provider block, context length, models and limits.

OpenAI's Codex CLI can run against a model that Ollama serves on your own machine. `ollama launch codex` sets it up in one command, and Codex has its own switch for the same thing: `codex --oss`, which uses a built-in `ollama` provider at `http://localhost:11434/v1`.

You need Ollama 0.15 or later for the launch command, a context length of 64K tokens, and a model that supports tool calling. Codex's default local model is gpt-oss:20b, which runs on 16 GB of memory. This guide gives the one-command path, the `--oss` path, the manual `config.toml` provider, how to check that requests stay local, the known limits, and how to roll the same setup out to a team with Aventail ™ Connect.

## What you need

| | Minimum | Comfortable |
| --- | --- | --- |
| Ollama | 0.13.4 for `codex --oss`; Codex refuses older servers. 0.15 for `ollama launch` | Latest release: 0.40.16, published 9 November 2026 |
| Codex CLI | Any current version | Latest release: 0.169.0, published 13 November 2026 |
| Context length | 64K tokens. Ollama's Codex page says to use at least 64K | The model's full window, if it fits in memory |
| Memory (unified or VRAM) | 16 GB for gpt-oss:20b | An 80 GB GPU for gpt-oss:120b |
| Disk | 14 GB for gpt-oss:20b | 65 GB for gpt-oss:120b |

Two figures are in circulation for the context length. Ollama's blog post of 15 January 2026 recommended at least 32K. Ollama's current Codex page says at least 64K. Use 64K.

Ollama sets a default context length from your GPU memory: 4K below 24 GiB, 32K from 24 to 48 GiB, 256K at 48 GiB and above. With less than 24 GiB that is 4K, so you raise it by hand in step 1.

## Step 1: install Ollama and set the context length

macOS and Linux:

`curl -fsSL https://ollama.com/install.sh | sh`

Windows PowerShell:

`irm https://ollama.com/install.ps1 | iex`

Set the context length before you serve a model. The quickest way is the slider in the Ollama app settings. From a terminal:

`OLLAMA_CONTEXT_LENGTH=64000 ollama serve`

Check what is loaded, how much context it has, and whether it sits on the GPU or the CPU:

`ollama ps`

## Step 2: pull a model that supports tools

Codex edits files and runs commands through tool calls. Every model below carries the `tools` tag in the Ollama library on 15 November 2026.

| Model | Size on disk | Context window | Memory guidance from Ollama | Tags |
| --- | --- | --- | --- | --- |
| gpt-oss:20b | 14 GB | 128K | Runs on systems with as little as 16 GB | tools, thinking |
| gpt-oss:120b | 65 GB | 128K | Fits on a single 80 GB GPU | tools, thinking |
| qwen3-coder:30b | 19 GB | 256K | Not published for the 30B size | tools |
| glm-4.7-flash | 19 GB | 198K | About 23 GB of VRAM at 64K context | tools, thinking |
| devstral-small-2:24b | 15 GB | 384K | Not published | tools, vision |
| qwen3.5:27b | 17 to 20 GB | 256K | Not published | tools, thinking, vision |

gpt-oss is the model family Codex's local mode is built around: it is the default for `--oss`, and Ollama's examples use it. Where Ollama publishes no memory figure, use the file size as the floor, because the weights and the 64K context both have to fit in memory.

`ollama pull gpt-oss:20b`

## Step 3: install Codex CLI

macOS and Linux:

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

Windows, from a new PowerShell window:

`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`

Or with npm, which is the command Ollama's page uses:

`npm install -g @openai/codex`

## Step 4: launch Codex on Ollama with one command

`ollama launch codex`

Ollama refreshes the model catalogue and uses a dedicated Codex profile for that session. Inside Codex, type `/model` to switch between your installed, tool-capable Ollama models without restarting. Each model keeps its own context window, vision and thinking settings. Pull extra models with `ollama pull` before you launch so they appear in the picker.

To configure without launching:

`ollama launch codex --config`

To remove the Ollama launch profile and the generated model catalogue:

`ollama launch codex --restore`

## Step 5: or use Codex's own `--oss` flag

Use this when you want Codex to start from its own command.

`codex --oss`

With no `-m`, Codex uses gpt-oss:20b and pulls it if it is missing. To name a model:

`codex --oss -m gpt-oss:120b`

`--oss` supports two local providers, Ollama and LM Studio. Codex picks one in this order: the `--local-provider` flag, the `oss_provider` key in your config, then a prompt that asks you to choose. `codex exec` exits with an error if neither is set. To make Ollama the default, add this to `~/.codex/config.toml`:

`` # Default local provider used with `--oss` ``
`oss_provider = "ollama" # or "lmstudio"`

For one run:

`codex --oss --local-provider ollama -m gpt-oss:20b`

## Step 6: or define the provider in config.toml

Use this when you want a named, persistent setup, or when Ollama runs on another host.

Ollama documents a profile file. Create `~/.codex/ollama-launch.config.toml`:

`model = "gpt-oss:120b"`
`model_provider = "ollama-launch"`
`model_catalog_json = "/Users/you/.codex/model.json"`
`[model_providers.ollama-launch]`
`name = "Ollama"`
`base_url = "http://localhost:11434/v1/"`
`wire_api = "responses"`

Then run:

`codex --profile ollama-launch`

`--profile` layers `~/.codex/ollama-launch.config.toml` on top of your base config, so your normal Codex setup stays untouched. `model_catalog_json` points at a model catalogue file; `ollama launch codex` generates one. Replace `/Users/you` with your home directory.

To put the provider in your main `~/.codex/config.toml`, use the keys from the Codex configuration docs:

`model = "gpt-oss:20b"`
`model_provider = "local_ollama"`
`model_context_window = 64000`
`[model_providers.local_ollama]`
`name = "Ollama"`
`base_url = "http://localhost:11434/v1"`
`wire_api = "responses"`

Four things to know about these files:

- `**responses**` **is the only wire API.** Codex removed `wire_api = "chat"`. A guide that tells you to set it is out of date, and Codex returns an error that names the fix. The old `ollama-chat` provider ID is gone as well.
- **Pick your own provider ID.** Codex reserves `openai`, `ollama`, `lmstudio`, `amazon-bedrock`, `amazon-bedrock-runtime` and `gcp` for built-in providers, and you cannot override them.
- **Provider keys belong in the user config.** Codex ignores `model_provider`, `model_providers` and `profile` in a project's `.codex/config.toml` and prints a warning.
- **Tell Codex the real window.** `model_context_window` is the number of context tokens available to the active model. Set it to the length you gave Ollama. `model_auto_compact_token_limit` sets the token count at which Codex compacts the history.

## Step 7: check it is running locally

1. Run `ollama ps` while Codex is answering. The model should be listed with the context length you set.
2. In Codex, run `/status`. It shows the session configuration, the active model and the remaining context capacity.
3. Turn off the traffic that goes to OpenAI by default. Codex periodically sends anonymous usage and health data to OpenAI unless you add this to `~/.codex/config.toml`:
   `[analytics]`
   `enabled = false`
   `[feedback]`
   `enabled = false`
   `check_for_update_on_startup = false` stops the update check.
4. Turn off web search if nothing may leave the machine. Through the Ollama profile, Codex web-search requests are executed by Ollama's web-search service, which needs `ollama signin`:
   `codex --profile ollama-launch -c 'web_search="disabled"'`
5. Unplug the network and ask Codex to explain a file. If it answers, the model is local.

## What works and what does not on a local model

Works: Ollama says Codex can read, modify and execute code in your working directory with open models, and `/model` switching works when you start with `ollama launch codex`. Codex's sandbox, approval prompts and `AGENTS.md` are features of the client and do not depend on the model provider.

Known limits:

- **Stateless Responses only.** Ollama supports the Responses API without the stateful parts: no `previous_response_id`, no `conversation`, no `truncation`. Each request therefore carries the conversation so far.
- **No prompt caching to rely on.** Ollama's OpenAI-compatible API documents no cache settings. On a local model the cost of a long conversation is time.
- **Tool reliability depends on the model.** gpt-oss is OpenAI's open-weight family, described as designed for agentic tasks, and it is Codex's default local model. Reliability with other open models varies, so test a real edit before you settle on one.
- **Reasoning display.** OpenAI's docs note that some models and providers, gpt-oss among them, do not emit raw reasoning, so the setting that shows it has no visible effect.
- **OpenAI account features are out of scope.** Codex cloud tasks and ChatGPT sign-in features run on OpenAI's service. The built-in local providers are defined in the Codex source with `requires_openai_auth` set to false. OpenAI's docs do not say whether a first run with `--oss` asks you to sign in.
- **The context default is too small.** Below 24 GiB of VRAM Ollama allocates 4K unless you change it. Ollama says coding tools need at least 64000 tokens.
- **Speed.** Neither vendor publishes tokens per second for this pairing. Ollama's guidance is to avoid CPU offload; check the PROCESSOR column in `ollama ps`.

Codex in the ChatGPT desktop app is a separate integration. Ollama 0.34.0 and later can add local and cloud models to Codex's model picker from the Ollama app, under Apps.

## Ollama cloud models are not your own models

Ollama's Codex page also shows `codex --oss -m gpt-oss:120b-cloud`. Cloud models run on Ollama's servers. Ollama states that prompt and response data is never logged or trained on, and that it hosts models primarily in the United States with routing to Europe for extra capacity. If your code must stay on your machines, do not pass a `-cloud` or `:cloud` model name.

## The same setup for a team with Aventail ™ Connect

The steps above suit one developer who manages their own machine. They give an IT or security lead no record of which machine sent which request where, and no rule that a developer cannot edit back in `config.toml`.

Aventail ™ Connect configures supported apps to send their model requests through Aventail ™ Link, the inference engine and gateway that runs on each machine. Routing rules are set in Aventail ™ Control and evaluated on the device. Codex, Claude Code, Claude Desktop and OpenCode are supported. In this setup Link serves the model itself, in place of Ollama.

1. **Sign in to Control** at control.aventail.co.uk and choose Connect a device.
2. **Install Link** on each machine: desktop installers for macOS (Apple silicon), Windows x64 and Linux x64, or unattended:
   `curl -fsSL https://get.aventail.co.uk/install.sh | AVENTAIL_REGISTRATION_KEY='YOUR_REG_KEY' sh`
3. **Serve a model.** In Models, download a coding model and choose Start serving.
4. **Connect Codex.** In Connected apps, choose Connect next to Codex. The Codex CLI, the editor extension and Codex in the ChatGPT desktop app share one user configuration, so one connection covers all three. Sessions that are already open keep their model.
5. **Check where it ran.** Send a harmless prompt, then open Requests in Control.
6. **Write the routing rule.** The first matching enabled rule wins. For a local-only team, permit only On device; if local serving is unavailable, the request fails with an error.

Two limits from Aventail ™ 's docs: the Codex connection uses the Responses API, and the reviewed route supports local models, peers and OpenAI. Other cloud providers are not supported for Codex on this path.

Disconnect restores the settings Link changed. The Free plan covers three connected devices, including business use. Starter is £50 a month excluding VAT and includes ten devices. Routing policies need Control for Enterprise.

## Which path to take

| | Codex + Ollama by hand | Codex with Aventail ™ Connect |
| --- | --- | --- |
| Who it suits | One developer on their own machine | A team whose code must stay on approved models |
| Setup | `ollama launch codex`, `codex --oss`, or `config.toml` | Connect button in Link, rules in Control |
| Who picks the model | The developer, with `-m` or `/model` | The developer in Link, within the routing rule |
| Where requests go | Wherever `config.toml` says | Where the routing rule says, evaluated on the device |
| Record of requests | None | Requests view in Control |
| If the local model is down | Developer switches provider | Fails with an error, or falls back to an approved destination |
| Cost | Free | Free for three devices; £50 a month for ten |

## Frequently asked questions

**Can Codex CLI run on a local model?**
Yes. `codex --oss` runs Codex against a local provider, Ollama or LM Studio. `ollama launch codex` does the same setup from the Ollama side.

**Which Ollama model does Codex use by default?**
gpt-oss:20b. Codex pulls it if it is not on the machine. Pass `-m` to use another model, for example `codex --oss -m gpt-oss:120b`.

**Which Ollama version does Codex need?**
Codex checks the server version and refuses anything older than 0.13.4, because it needs the Responses API. `ollama launch` needs 0.15 or later.

**Why does my config with** `**wire_api = "chat"**` **fail?** Codex no longer supports the Chat Completions wire API. Set `wire_api = "responses"` in the provider block, or remove the line, since `responses` is the default.

**How do I set the context length for Codex with Ollama?**
Set it in Ollama first, with the app slider or `OLLAMA_CONTEXT_LENGTH=64000 ollama serve`. Then set `model_context_window = 64000` in `~/.codex/config.toml` so Codex compacts at the right point.

**Can Codex use Ollama on another machine?**
Yes. Define a provider in `~/.codex/config.toml` with `base_url` set to that server's address ending in `/v1`, and point `model_provider` at it.

**Is my code sent to OpenAI when I use Codex with Ollama?**
Model requests go to the `base_url` you set. Codex still sends anonymous usage and health data to OpenAI by default; `[analytics] enabled = false` turns that off. For how Codex handles data on OpenAI's own service, see Is Codex safe for work?.

## Related guides

- AI coding on your own models: https://aventail.co.uk/guides/ai-coding-on-your-own-models
- Claude Code + Ollama: https://aventail.co.uk/guides/claude-code-ollama
- OpenCode + Ollama: https://aventail.co.uk/guides/opencode-ollama
- Best local LLMs for coding: https://aventail.co.uk/guides/best-local-llms-for-coding
- Ollama vs: https://aventail.co.uk/guides/ollama-vs-aventail
  Aventail: https://aventail.co.uk/guides/ollama-vs-aventail
  ™: https://aventail.co.uk/guides/ollama-vs-aventail
- Route local models and cloud APIs: https://aventail.co.uk/guides/route-local-models-and-cloud-apis

## Sources

1. Ollama, Codex CLI integration: https://docs.ollama.com/integrations/codex
2. Ollama, ChatGPT Desktop integration: https://docs.ollama.com/integrations/chatgpt
3. Ollama, Context length: https://docs.ollama.com/context-length
4. Ollama, OpenAI compatibility (Responses API): https://docs.ollama.com/api/openai-compatibility
5. Ollama blog, OpenAI Codex with Ollama (15 January 2026): https://ollama.com/blog/codex
6. Ollama blog, ollama launch (23 January 2026): https://ollama.com/blog/launch
7. Ollama download page and releases (v0.40.16): https://ollama.com/download and https://github.com/ollama/ollama/releases/latest
8. Ollama library: gpt-oss, qwen3-coder, glm-4.7-flash, devstral-small-2, qwen3.5 at https://ollama.com/library
9. Ollama cloud: https://ollama.com/cloud
10. OpenAI, Codex CLI: https://developers.openai.com/codex/cli
11. OpenAI, Codex command line options: https://developers.openai.com/codex/cli/reference
12. OpenAI, Codex advanced configuration: https://developers.openai.com/codex/config-advanced
13. OpenAI, Codex configuration reference: https://developers.openai.com/codex/config-reference
14. Codex GitHub repository, README and release 0.169.0: https://github.com/openai/codex
15. Codex source, built-in local providers: https://github.com/openai/codex/blob/main/codex-rs/model-provider-info/src/lib.rs and https://github.com/openai/codex/blob/main/codex-rs/ollama/src/lib.rs
16. Aventail ™, Connect overview: https://docs.aventail.co.uk/docs/connect/overview
17. Aventail ™, Initial setup: https://docs.aventail.co.uk/docs/getting-started/initial-setup
18. Aventail ™, Routing: https://docs.aventail.co.uk/docs/fleet/routing
19. Aventail ™, Pricing: https://aventail.co.uk/#pricing

All sources were read on 15 November 2026. The developers.openai.com/codex pages redirect to learn.chatgpt.com/docs.

We use optional cookies and tracking to identify visiting companies, load our contact form, measure Google Ads download clicks and understand page use with PostHog on our homepage, Connect and How it works pages, Ollama and LM Studio comparison guides and campaign pages. Cookie policy (https://aventail.co.uk/cookies)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://aventail.co.uk/#organization",
      "name": "Aventail",
      "alternateName": "Locai",
      "legalName": "Loc.ai Ltd",
      "description": "Aventail, formerly Locai, was founded in 2026 and is a graduate of Google AI First. It gives enterprises the full AI stack to adopt AI securely: a built-in inference engine, deployment of supported models across approved hardware, on-device classification and policy-based routing between those machines and approved external AI providers, central management and an employee workspace. Organisations use Aventail to put approved information to work while controlling where inference requests run.",
      "url": "https://aventail.co.uk/",
      "logo": "https://aventail.co.uk/apple-touch-icon.png",
      "email": "hello@aventail.co.uk",
      "hasCredential": [
        {
          "@type": "EducationalOccupationalCredential",
          "name": "Cyber Essentials",
          "credentialCategory": "certification",
          "url": "https://aventail.co.uk/trust#cyber-essentials"
        }
      ]
    },
    {
      "@type": "Article",
      "@id": "https://aventail.co.uk/guides/codex-ollama#page",
      "url": "https://aventail.co.uk/guides/codex-ollama",
      "name": "Codex + Ollama: run OpenAI Codex CLI on a local model",
      "description": "Run OpenAI Codex CLI on a local model with Ollama: ollama launch codex, the --oss flag, the config.toml provider block, context length, models and limits.",
      "publisher": {
        "@id": "https://aventail.co.uk/#organization"
      },
      "headline": "Codex + Ollama: run OpenAI Codex CLI on a local model",
      "datePublished": "2026-11-16",
      "dateModified": "2026-11-16T18:48:12.650806+00:00",
      "image": "https://aventail-ai-platform.lovable.app/images/share/og-home-v7.jpg",
      "author": {
        "@id": "https://aventail.co.uk/#organization"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://aventail.co.uk/guides/codex-ollama#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://aventail.co.uk/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Guides",
          "item": "https://aventail.co.uk/guides"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "Codex + Ollama: run OpenAI Codex CLI on a local model",
          "item": "https://aventail.co.uk/guides/codex-ollama"
        }
      ]
    }
  ]
}
```