Running Codex CLI with Local Ollama and LM Studio Models: `--oss`, Configuration, and Safety

1. Introduction: Codex CLI Can Run Against Local Models

Codex CLI is not limited to OpenAI-hosted models. It can connect to a local model served by Ollama or LM Studio. These are the two basic commands:

codex --oss --local-provider ollama --model <MODEL_NAME>

codex --oss --local-provider lmstudio --model <MODEL_NAME>

A successful chat request does not prove that a model can work reliably as a coding agent. The harder test is whether it can inspect the right files, call tools with valid arguments, make a bounded edit, and verify the result. This guide covers both setup and a safe way to evaluate those capabilities.

2. Cloud and Local Operation Compared

In the standard configuration, Codex CLI sends the prompt and relevant context to an OpenAI model. Codex then mediates local file access, edits, and shell commands based on the model's decisions.

With --oss, the inference destination changes to Ollama or LM Studio. Codex CLI still performs the actual repository and shell operations. Local inference therefore reduces one class of data exposure; it does not make filesystem access harmless.

flowchart LR
    accTitle: Codex CLI inference paths
    accDescr: In standard operation, Codex CLI connects to an OpenAI model. In local mode, it connects to a local model through Ollama or LM Studio. Codex CLI mediates file operations and command execution in both cases.
    Repo[Working repository] <--> CLI[Codex CLI]
    CLI -->|Standard mode| OpenAI[OpenAI model]
    CLI -->|--oss| Provider[Ollama or LM Studio]
    Provider --> Local[Local model]
    CLI --> Tools[File edits and commands]

Cloud and local inference architecture

Local inference makes it easier to keep source code away from an external inference API, avoid usage-based API costs, and choose your own models and quantization. The tradeoff is that speed, context capacity, instruction following, and tool use depend heavily on the selected model and local hardware.

Do not interpret --oss as an automatic air gap. Ollama :cloud models, remote LM Link devices, Codex network features, and other integrations can still create network traffic. For sensitive code, verify the model identifier, server destination, network policy, logs, and telemetry settings.

3. Prerequisites and Test Environment

You need Codex CLI, Ollama or LM Studio, a model that runs locally, and a small Git repository with a working test command. Avoid granting write access to a production repository during the first experiment. A minimal fixture might look like this:

local-codex-demo/
├── src/
│   └── calculator.py
├── tests/
│   └── test_calculator.py
├── README.md
└── AGENTS.md

Evaluate one layer at a time: chat with the model directly, let Codex inspect files without changing them, request a proposed patch, allow one file edit, and finally run tests. This sequence separates connectivity failures from agent-capability failures.

4. Choosing a Local Coding Model

Chat quality is not enough

A Codex model must do more than generate plausible code. It needs to relate files, preserve constraints, call tools, produce structured arguments, interpret command output, and decide what to do next. Check at least the following:

• RAM or VRAM requirements and quantization
• Maximum and actually allocated context length
• Suitability for tool calling and structured output
• Code understanding and generation quality
• Chat template compatibility
• Exact model identifier exposed by Ollama or LM Studio

Small models are best introduced through single-file explanations, type hints, comments, simple tests, naming improvements, and localized refactoring. A model may connect successfully yet remain unreliable for repository-wide redesigns or long autonomous tasks based on ambiguous requirements.

Why context length matters

The user's prompt is only part of the input. System instructions, AGENTS.md, source files, tool arguments, command output, test failures, and conversation history all consume context.

Ollama recommends at least 64K tokens for agents and coding tools. LM Studio's Codex guide recommends a configuration above roughly 25K. Larger windows also require more memory, particularly for the KV cache, so monitor performance instead of selecting the largest value blindly.

5. Preparing Ollama

Start Ollama, download a model, inspect its identifier, and test it directly. The desktop app may already be running the server.

ollama serve
ollama pull <MODEL_NAME>
ollama ls
ollama run <MODEL_NAME>

Use the identifier shown by ollama ls as the value of Codex's --model. Confirm that ollama run can at least generate and explain a small function before adding Codex to the path.

To serve with a 64K context allocation:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

If performance collapses or the model fails to load, inspect the allocated context and CPU offloading:

ollama ps

Ollama also provides a Codex launcher that can generate the required integration configuration:

ollama launch codex

To configure without launching Codex:

ollama launch codex --config

The remaining examples use --local-provider ollama explicitly so that the active backend is visible in every command.

6. Preparing LM Studio

Download and load a model in LM Studio, then configure GPU Offload and context length. After a direct chat test, start the local API server from the Developer screen or the CLI:

lms server start --port 1234

LM Studio uses port 1234 by default. Codex connects through its OpenAI-compatible POST /v1/responses endpoint. When troubleshooting, check that the server is running, the model is loaded, requests appear in the Developer view, and Codex uses the exact exposed model identifier.

7. Starting Codex in OSS Mode

Specify both the provider and model:

codex --oss --local-provider ollama --model <MODEL_NAME>

codex --oss --local-provider lmstudio --model <MODEL_NAME>

--model can be shortened to -m:

codex --oss --local-provider ollama -m <MODEL_NAME>

According to the current OpenAI documentation, the interactive CLI prompts for a provider when --oss is set and no default exists. codex exec, however, exits with an error if it cannot resolve a provider. Explicit --local-provider arguments are therefore preferable in reproducible instructions and scripts.

If Codex reports that the model is missing, confirm that you supplied the API identifier rather than a display label. Use ollama ls for Ollama and the Developer view for LM Studio.

8. Saving Defaults in config.toml

User-level configuration lives in ~/.codex/config.toml:

oss_provider = "ollama"
model = "<MODEL_NAME>"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

You can then start local mode with:

codex --oss

Use oss_provider = "lmstudio" for LM Studio. Command-line arguments override configuration for a single invocation:

codex --oss --local-provider lmstudio --model <OTHER_MODEL>

To separate cloud and local defaults, create $CODEX_HOME/local.config.toml and select it as a profile:

codex --profile local --oss

Current Codex profiles are separate $CODEX_HOME/<profile-name>.config.toml files, so switching workflows does not require repeatedly editing the base configuration.

9. Letting a Local Model Operate on a Repository

Start with read-only inspection

Run Codex in the test repository and prohibit edits:

Inspect the structure of this repository.
Do not modify any files yet. Explain the role of each file and list possible improvements.

Check whether the model found the correct files, invented nonexistent files, or ignored the no-edit constraint.

Allow exactly one file edit

Work only on src/calculator.py.

Goals:
- Add type hints
- Add a docstring

Constraints:
- Do not rename functions or change behavior
- Do not add dependencies
- Do not modify other files

After editing:
- Inspect the diff
- Run pytest
- Report the changes and test result

Small models benefit from separate target, goal, constraint, and completion sections. Broad prompts such as “improve this project” encourage scope expansion and loops.

Use the same discipline for tests:

Inspect the current implementation and add boundary-value tests to tests/test_calculator.py.
Do not remove existing tests.
If tests fail, explain the cause before editing and retry at most twice.

Finally, verify independently rather than trusting the summary alone:

git status
git diff
pytest

10. Non-Interactive Runs with codex exec

codex exec performs one bounded task without opening the interactive interface. It is suitable for scripts and CI-style workflows.

codex exec \
  --oss \
  --local-provider ollama \
  --model <MODEL_NAME> \
  "Explain the structure of this repository"

For LM Studio:

codex exec \
  --oss \
  --local-provider lmstudio \
  --model <MODEL_NAME> \
  "Inspect the tests and list missing cases"

Prompts can also come from standard input:

cat prompt.txt | codex exec \
  --oss \
  --local-provider ollama \
  --model <MODEL_NAME> \
  -

Stay interactive until you understand the model's failure modes, then begin unattended use with read-only tasks.

11. Approval Policies and Sandboxing

The sandbox controls what Codex can technically access. The approval policy controls when it must ask a human. Both remain necessary with local inference.

Start in read-only mode:

codex \
  --oss \
  --local-provider ollama \
  --model <MODEL_NAME> \
  --sandbox read-only \
  --ask-for-approval on-request

When you are ready to permit edits, limit writes to the workspace:

codex \
  --oss \
  --local-provider ollama \
  --model <MODEL_NAME> \
  --sandbox workspace-write \
  --ask-for-approval on-request

The main sandbox modes are read-only, workspace-write, and danger-full-access. Approval policies include untrusted, on-request, and never. never does not mean “perform only safe actions”; it means Codex will not interactively request approval.

codex --dangerously-bypass-approvals-and-sandbox

This flag bypasses both controls. OpenAI's documentation warns that it should be used only inside an isolated runner. Do not combine it with a local model whose tool calling has not been thoroughly evaluated.

12. Common Local-Model Failure Modes

Separate failures into the Codex CLI, API server, model, and context or memory layers. Otherwise, it is easy to keep swapping models for what is actually a port or loading problem.

flowchart TD
    accTitle: Local Codex troubleshooting flow
    accDescr: Diagnose failures by checking API connectivity first, then model identity and loading, context and memory resources, and finally tool calling and instruction-following capability.
    Start[Reproduce failure] --> Request{Did the request reach
the API server?}
    Request -->|No| Server[Check port, server, and provider]
    Request -->|Yes| Loaded{Was the requested
model loaded?}
    Loaded -->|No| Model[Check model identifier and load state]
    Loaded -->|Yes| Resource{Slow, stalled, or
out of context?}
    Resource -->|Yes| Memory[Check context, RAM, VRAM, and offloading]
    Resource -->|No| Tool{Invalid tool calls or
ignored constraints?}
    Tool -->|Yes| Capability[Narrow the task or change model or template]
    Tool -->|No| Logs[Inspect Codex output, tests, and diff]

Troubleshooting local Codex runs

Tool calls break

Typical symptoms include claiming to read a file without doing so, emitting a tool call as plain text, or generating invalid JSON arguments. Choose a model suited to tool use, restrict each task to roughly one to three files, and separate structured-data generation from file editing.

Instructions disappear or actions loop

Repeat critical constraints at the end of the prompt and store durable repository rules in AGENTS.md. Add a stop condition such as: “Retry failed tests at most twice, then stop and report the blocker.”

The repository is too large

Use --cd to narrow the workspace, ask for a structure summary first, and explicitly name the important files. Large test logs consume context quickly, so run the smallest relevant test target.

Memory runs out or generation becomes extremely slow

With Ollama, use ollama ps to inspect context allocation and CPU offloading. In LM Studio, inspect load settings, GPU Offload, and estimated memory. Unload other models and reduce either model size or context length when necessary.

13. Local Codex Versus Cloud Codex

This is not an all-or-nothing choice. Select a backend based on confidentiality, task complexity, change risk, and the amount of human debugging time being consumed.

14. Tasks That Fit Local Models

Good starting tasks include code explanation, comments, type hints, naming improvements, small refactors, basic test generation, README drafts, one- or two-file diff reviews, and mechanical transformations.

Treat authentication, authorization, database migrations, large dependency upgrades, production deployment, infrastructure changes, deletions, security fixes, and cross-service work cautiously. If attempted, separate inspection, planning, editing, and verification into distinct stages with human review between them.

15. When to Switch to a Cloud Model

Switch when the model repeats the same failure two or three times, cannot identify the relevant files, repeatedly emits invalid tool calls, loses constraints, or reaches a task requiring complex design or debugging. The same applies when human cleanup costs more time than the AI saves.

flowchart TD
    accTitle: Model selection decision flow
    accDescr: Try a local model for low-risk, clearly bounded tasks and have a human inspect the diff. Use a cloud model when the work is complex, high-risk, repository-wide, or continues failing after limited retries.
    Task[Define task] --> Risk{Is the change high-risk?}
    Risk -->|Yes| Cloud[Cloud model with strict review]
    Risk -->|No| Scope{Few files and
clear requirements?}
    Scope -->|No| Cloud
    Scope -->|Yes| Local[Run with local model]
    Local --> Review[Human reviews diff and tests]
    Review --> Success{Acceptable?}
    Success -->|Yes| Done[Adopt change]
    Success -->|No| Retry{Fewer than two failures?}
    Retry -->|Yes| Narrow[Narrow task and constraints]
    Narrow --> Local
    Retry -->|No| Cloud

Choosing between local and cloud models

A practical split is to use local models for investigation, explanation, drafts, and small edits, then use human review and a cloud model for complex implementation or final review.

16. Conclusion

Codex CLI enables local-model mode with --oss and selects ollama or lmstudio through --local-provider. Pass the provider's exact model identifier through --model; set oss_provider to avoid repeating the provider; and remember that codex exec fails when no local provider can be resolved.

Local inference does not remove the need for permission controls. Begin with read-only and on-request, keep task scope and completion criteria narrow, and independently inspect diffs and tests. Local models are a strong fit for repetitive, bounded work; cloud models remain the pragmatic choice when complexity, scale, or change risk rises.