Codex CLI

Choose a local Ollama, Unsloth, or llama.cpp connection below, or use the Nebius partner walkthrough with a local LiteLLM helper.

This integration is experimental. Codex requires a Responses-compatible runtime or the translation helper below. Check tool calls, streaming, and conversation continuation with your runtime.

Only the Nebius path needs an assigned key from the 1Password access handoff.

Connect local runtimes

These local connections require a compatible runtime. Keep normal approval and sandbox settings enabled, check the selected model, and verify tools and a follow-up turn. For automatic setup with OpenCode instead, use rec launch opencode.

Ollama

Install Codex with npm install -g @openai/codex and prepare Flint with Ollama. The Ollama launcher does not need the LiteLLM helper. From a disposable project directory, run:

ollama launch codex

Choose flint:40b-a2b-qat-int4. Ollama’s Codex launcher provides a session profile and model catalog. Its guide calls for at least 64K context; verify that your Flint runtime and hardware support that budget.

Unsloth

Load a compatible Flint GGUF in Unsloth, then run from your project directory:

unsloth start codex --persist

The Unsloth launcher currently requires its GGUF/llama-server backend for Codex. --persist retains the managed Codex home; use it on subsequent launches too. Confirm Flint is selected and test tool execution and continuation.

llama.cpp through the local bridge

Start the supplied Flint-compatible llama.cpp server. For a build exposing Chat Completions, use the pinned helper below to translate Codex’s Responses requests. Save the following as ~/.config/flint-litellm/local.yaml after completing the helper installation:

model_list:
  - model_name: flint
    litellm_params:
      model: openai/flint-local
      api_base: http://127.0.0.1:8080/v1
      api_key: os.environ/LOCAL_API_KEY
    model_info:
      mode: completion
general_settings:
  master_key: os.environ/FLINT_PROXY_KEY

openai/ selects LiteLLM’s Chat Completions adapter; the request goes to the configured local URL. Match the suffix to the server’s --alias. Sampling uses the server defaults. Export LOCAL_API_KEY="local" in the helper terminal for the unauthenticated localhost server, or privately supply its actual key if authentication is enabled. Follow Start the helper, skipping the Nebius key prompt and using --config ~/.config/flint-litellm/local.yaml instead of config.yaml. Create/load FLINT_PROXY_KEY as shown there; it protects the bridge and is separate from the model server’s credential. Then follow Add Flint to Codex and Start a Flint session. Codex connects to port 4000; the helper forwards to llama.cpp on 8080. The custom catalog and tool-translation limitations below still apply. The remaining walkthrough uses Nebius as the upstream; substitute local.yaml when following it for a local server.

Install Codex and the helper

Use Node.js/npm and Python 3.11 on macOS, Linux, or WSL. Skip the Codex installation if it is already installed.

npm install -g @openai/codex
codex --version
python3.11 -m venv ~/.venvs/flint-litellm
~/.venvs/flint-litellm/bin/pip install 'litellm[proxy]==1.101.6' 'prisma==0.15.0'
mkdir -p ~/.config/flint-litellm

The Prisma package is needed by this pinned proxy’s authentication-error handler, even for this database-free setup. Without it, a missing key can produce HTTP 500 instead of an authentication error. You do not need to configure a database or run Prisma migrations. Save this as ~/.config/flint-litellm/config.yaml. Your real Nebius key belongs in the environment variable, not this file.

model_list:
  - model_name: flint
    litellm_params:
      model: nebius/dedicated/shadowlaunch/ll-alpha
      api_base: https://api.tokenfactory.us-north1.nebius.com/v1
      api_key: os.environ/NEBIUS_API_KEY
      temperature: 1
      top_p: 0.95
      extra_body:
        top_k: 20
    model_info:
      mode: completion
general_settings:
  master_key: os.environ/FLINT_PROXY_KEY

Start the helper

In the first terminal, paste your Nebius key at the hidden prompt:

export NEBIUS_API_KEY="$(python3 -c 'import getpass; print(getpass.getpass("Nebius API key: "))')"

Create a separate key for the local helper on the first run. This command preserves an existing helper key on subsequent runs:

umask 077
if [ ! -e ~/.config/flint-litellm/proxy-key ]; then
  python3 -c 'import secrets; print("sk-" + secrets.token_hex(32))' \
    > ~/.config/flint-litellm/proxy-key
fi
export FLINT_PROXY_KEY="$(cat ~/.config/flint-litellm/proxy-key)"
~/.venvs/flint-litellm/bin/litellm \
  --config ~/.config/flint-litellm/config.yaml \
  --host 127.0.0.1 --port 4000

Keep this terminal open. The helper listens only on your machine and forwards model requests to the upstream selected in its YAML: Nebius in config.yaml, or your local model server in local.yaml.

Add Flint to Codex

Merge this block into ~/.codex/config.toml. If the table already exists, update it instead of adding a duplicate. Preserve your existing settings.

[model_providers.flint_bridge]
name = "Flint via local LiteLLM"
base_url = "http://127.0.0.1:4000/v1"
env_key = "FLINT_PROXY_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

Custom model metadata

flint is a local routing alias, not a model built into Codex. Without a matching model catalog, Codex can warn that it is using fallback metadata. Requests can still reach the helper, but context accounting, compaction, reasoning controls, and tool choices may not match Flint. Keep this recipe to small experimental tasks until those behaviors are qualified. For a supported rollout, Recursive must supply a catalog matching the deployed Codex version with slug = "flint", verified Flint capabilities and limits, and upgrade = null. Load that catalog with model_catalog_json as described in the official gateway rollout guide. Do not rename Flint to an OpenAI model to hide the warning. LiteLLM’s ordinary /v1/models response is not itself a Codex model catalog.

Start a Flint session

Open a second terminal. Replace the project path with a disposable copy of your repository:

export FLINT_PROXY_KEY="$(cat ~/.config/flint-litellm/proxy-key)"
cd /path/to/project-copy
codex -c 'model_provider="flint_bridge"' --model flint

Check the startup header or /status: the selected model must be flint and the provider must be flint_bridge / Flint via local LiteLLM. Existing profiles and managed settings can affect the session; stop if another model or provider is selected. Ask “Read this project and explain how to run it. Do not change files yet.” Then run the complete tool-cycle check. Keep Codex’s normal approval and sandbox settings enabled. After the tool task completes, send a follow-up question about its result to check conversation continuation. Record codex --version, the helper version, errors, and any intervention. A healthy proxy or one text reply is not a successful agent test. To return to your usual setup, exit Codex and launch it normally. Stop the helper with Ctrl+C when finished. For a later session, repeat Start the helper and Start a Flint session, reusing the existing local helper key.

Troubleshooting

Cannot connect: check that the helper is running on 127.0.0.1:4000 and both terminals loaded the same FLINT_PROXY_KEY.
Model not found: use flint in Codex and the correct upstream in the helper’s YAML: nebius/dedicated/shadowlaunch/ll-alpha for Nebius, or openai/ followed by your local server’s model ID.
Unknown model metadata: see custom model metadata. Fallback metadata does not establish Flint’s context limits or tool compatibility.
HTTP 500 with No module named 'prisma': install both pinned packages from the first step and restart the helper. Then check that both terminals loaded the same helper key.
Text works but tools fail: record the failing call, bridge error, and exact versions. LiteLLM 1.101.6 includes a Codex tool-translation fix.

Codex uses wire_api = "responses". Changing it to "chat" does not make a Chat Completions endpoint compatible. See the official gateway requirements and provider configuration reference. Helper references: LiteLLM Codex setup, Nebius provider, and 1.101.6 release notes.

Get started

Local inference

GPU inference

Harness

Resources

Connect local runtimes

Ollama

Unsloth

llama.cpp through the local bridge

Install Codex and the helper

Start the helper

Add Flint to Codex

Custom model metadata

Start a Flint session

Troubleshooting

​Connect local runtimes

​Ollama

​Unsloth

​llama.cpp through the local bridge

​Install Codex and the helper

​Start the helper

​Add Flint to Codex

​Custom model metadata

​Start a Flint session

​Troubleshooting

Connect local runtimes

Ollama

Unsloth

llama.cpp through the local bridge

Install Codex and the helper

Start the helper

Add Flint to Codex

Custom model metadata

Start a Flint session

Troubleshooting