> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recursive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Connect Codex to local Ollama, Unsloth, or llama.cpp, or try the Nebius bridge.

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

> [!WARNING]
>
> 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](https://docs.recursive.com/guides/coding-tools#get-access).

## 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`](https://docs.recursive.com/guides/coding-tools#automatic-setup-with-rec).

### Ollama

Install Codex with `npm install -g @openai/codex` and prepare Flint with [Ollama](https://docs.recursive.com/edge/ollama.md). The Ollama launcher does not need the LiteLLM helper. From a disposable project directory, run:

```bash theme={null}
ollama launch codex
```

Choose `flint:40b-a2b-qat-int4`. Ollama’s [Codex launcher](https://docs.ollama.com/integrations/codex) 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](https://docs.recursive.com/edge/unsloth.md#connect-a-coding-harness), then run from your project directory:

```bash theme={null}
unsloth start codex --persist
```

The [Unsloth launcher](https://unsloth.ai/docs/integrations/unsloth-start) 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](https://docs.recursive.com/edge/llama-cpp.md). 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:

```yaml theme={null}
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](#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](#add-flint-to-codex) and [Start a Flint session](#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.

```bash theme={null}
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.

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```toml theme={null}
[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](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway). 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:

```bash theme={null}
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](https://docs.recursive.com/guides/coding-tools#verify-a-complete-tool-cycle). 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](#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](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility) and [provider configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).

Helper references: [LiteLLM Codex setup](https://docs.litellm.ai/docs/proxy/client_setup/codex_cli), [Nebius provider](https://docs.litellm.ai/docs/providers/nebius), and [1.101.6 release notes](https://docs.litellm.ai/release_notes/v1.101.6/v1-101-6).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.