Connecting Codex CLI to Local Ollama: A Step-by-Step for Offline Dev

Developing software in environments with restricted internet access or strict privacy requirements necessitates a shift toward local-first workflows. One of the most effective ways to achieve this is by connecting Codex CLI to local Ollama instances. This setup allows you to leverage powerful large language models (LLMs) without sending your proprietary code to external servers. By redirecting the CLI to custom API endpoints, you maintain complete control over your data while enjoying the benefits of AI assisted programming.

Understanding the Architecture of Local AI Coding

The traditional approach to AI coding involves a local plugin or CLI sending code snippets to a cloud provider. While convenient, this introduces latency and potential security risks for sensitive projects. A local architecture replaces the cloud provider with a server running on your own hardware.

Ollama acts as the inference engine, managing the weights of models like Llama 3 or Mistral. It provides an OpenAI compatible API by default on port 11434. Codex CLI, originally designed to interact with OpenAI, can be pointed toward this local address. This transition is possible because many modern CLI tools now support custom base URLs for their API requests.

When you configure these tools to work together, you create a feedback loop that stays entirely on your machine. This is particularly useful for developers working in secure facilities, on airplanes, or in regions with unreliable connectivity.

Configuring Ollama for External Connections

Before modifying your CLI settings, you must ensure Ollama is prepared to receive requests. By default, Ollama listens on localhost. If you are running your coding environment inside a container or a specialized workspace, you might need to adjust the environment variables.

1. Install Ollama on your host machine (Mac, Windows, or Linux).
2. Pull your preferred model using ollama pull llama3 or a similar command.
3. Verify the server is running by visiting http://localhost:11434 in your browser.

If you plan to use a tool that runs in a virtualized environment, you may need to set the OLLAMA_HOST variable to 0.0.0.0 to allow connections from other local network interfaces. This ensures that any panel or terminal you use can reach the inference server.

Redirecting Codex CLI to Custom API Endpoints

The core of this setup involves the Codex CLI configuration file. Most CLI tools store their settings in a hidden directory within your home folder, such as .config/codex. You are looking for a key typically named api_base or base_url.

To connect to Ollama, change the base URL from the default OpenAI endpoint to http://localhost:11434/v1. The /v1 suffix is crucial because Ollama uses this path to maintain compatibility with the OpenAI API structure. You will also need to provide a placeholder API key. Since Ollama does not require authentication for local requests, any string like ollama or local-dev will suffice to satisfy the CLI requirement.

Once configured, your command line requests will be intercepted by your local Ollama instance. This allows for rapid iteration without the costs associated with token usage on commercial platforms.

Running AI Agents in a Local-First Workspace

While a standard terminal works for basic tasks, a dedicated workspace can significantly improve your productivity when managing multiple local LLMs. Deska provides an environment where you can run coding agents like Codex CLI and Claude Code side by side.

Deska is a local-first application that runs on Mac, Windows, and Linux. It allows you to create an infinite canvas where you can place different tools as panels. For an offline setup, you might have one panel running a terminal for Codex CLI, another showing your code editor, and a third running a local documentation server.

Benefits of Using Deska for Offline Development

• Multi-agent orchestration: You can run different agents in separate terminals to compare their outputs on the same problem.
• Session persistence: Your agent threads and command history stay on your local disk.
• Direct interaction: Use the Ask Deska feature to manage your workspace via voice or chat without needing a mouse.

The app is designed around the idea that your data and storage should remain under your control. By using Deska to host your local-first tools, you create a unified interface for your offline AI stack.

Comparing Local LLM Orchestrators

There are several ways to run local models, and each has its strengths. Ollama is popular for its simplicity and ease of use. Other tools like LocalAI or vLLM offer more granular control over hardware acceleration and batching.

These tools differ in approach when it comes to resource management. Ollama is excellent for individual developers, while vLLM is often preferred for serving models to a larger team. Regardless of the backend, the process for connecting Codex CLI remains similar: update the API base URL and ensure the model name matches the one available on your server.

Troubleshooting Common Connection Issues

When setting up custom API endpoints, you might encounter a few hurdles. The most common issue is a connection refusal. This usually means the Ollama server is not running or is blocked by a local firewall.

Another frequent problem is model name mismatch. If you try to run a command and receive a 404 error, check that the model specified in your CLI config matches the name you used during the ollama pull command. Some tools expect a specific format, such as llama3:latest, while others might just want llama3.

If you are using Deska and cannot see your local server, verify your settings to ensure the workspace has permission to access your local network. You can also use the troubleshooting guide to check for terminal permission issues.

FAQ

How do I use Codex CLI without an internet connection?

You must configure the CLI to point to a local inference engine like Ollama. Set the API base URL to your localhost address and ensure you have downloaded the required models while you were still online.

Can I use different models for different panels in Deska?

Yes, you can open multiple terminal panels and configure each one to use a different local model or a different AI agent. This allows you to work with specialized models for different tasks simultaneously.

Does using a local LLM affect computer performance?

Running LLMs locally is resource intensive. It primarily consumes GPU VRAM or system RAM if using a CPU. While Deska is a lightweight desktop app, the underlying model execution will utilize significant hardware resources depending on the size of the model.

Get Started with Local-First AI

Transitioning to an offline development workflow provides security, speed, and independence from cloud providers. By mastering the configuration of custom API endpoints, you unlock the full potential of your hardware.

If you are looking for a professional environment to host your local AI tools, you can download the Deska desktop app for free. It provides the canvas you need to organize your code, your agents, and your notes in a single, local-first workspace. Explore our plans if you eventually want to mix local models with managed cloud inference for even more power.