# How to Integrate OmniRoute with Claude Code, Cursor, or Codex CLI Using Setup Commands

> Integrate OmniRoute with Cursor, Claude Code, or Codex CLI using simple setup commands. Easily configure your IDE or CLI to leverage OmniRoute with exported environment variables and proxy settings.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-10

---

**Use `omniroute setup-cursor` to generate step-by-step configuration instructions for the Cursor IDE, and export `OPENAI_API_BASE` and `OPENAI_API_KEY` environment variables to route the Codex CLI through OmniRoute's OpenAI-compatible proxy running on port 20128.**

OmniRoute by diegosouzapw is a self-hosted proxy that normalizes APIs from dozens of LLM providers into a single OpenAI-compatible interface. You can integrate OmniRoute with Claude Code, Cursor, or Codex CLI by pointing these clients at your local OmniRoute instance, enabling centralized rate-limiting, usage tracking, and prompt compression while maintaining your existing workflow.

## How the Integration Works

Both Cursor and the Codex CLI expect a standard OpenAI-compatible endpoint (`/v1`) and Bearer token authentication. OmniRoute exposes this interface at `http://localhost:20128/v1` by default, reading your API key from the `OMNIROUTE_API_KEY` environment variable.

The `omniroute setup-cursor` command—implemented in `bin/cli/commands/setup-cursor.mjs`—automates configuration discovery by resolving your active context, fetching available model IDs from `/v1/models`, and printing the exact settings you must paste into the Cursor UI.

## Integrating OmniRoute with Cursor

The Cursor IDE stores its configuration in an opaque SQLite database, so you must configure it manually through the Settings UI. The `setup-cursor` command generates the specific values you need.

### Running the Setup Command

Execute the command for a local OmniRoute instance:

```bash
omniroute setup-cursor

```

For a remote instance or custom port:

```bash
omniroute setup-cursor --remote https://omniroute.example.com --only gpt-4,claude-sonnet

```

The `--only` flag filters the model list to show only specific providers in the output.

### How the Command Resolves Configuration

The `resolveCursorTarget` function in `bin/cli/commands/setup-cursor.mjs` determines the correct endpoint and API key by checking the `--remote` flag, active context, and environment variables:

```ts
export function resolveCursorTarget(opts = {}) {
  let root;
  if (opts.remote) root = String(opts.remote).replace(/\/+$/, "");
  else {
    try {
      root = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT)?.baseUrl;
    } catch { /* none */ }
    if (!root) root = `http://localhost:${Number(opts.port ?? process.env.PORT ?? 20128) || 20128}`;
  }
  let apiKey = opts.apiKey ?? opts["api-key"];
  if (!apiKey) {
    try {
      const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
      apiKey = c?.accessToken || c?.apiKey;
    } catch { /* none */ }
  }
  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
  return { apiBase: ensureV1(root), apiKey };
}

```

The `buildCursorInstructions` function then formats these values into the exact UI steps Cursor requires:

```ts
export function buildCursorInstructions({ apiBase, models }) {
  const lines = [
    "Cursor stores this config in an opaque database, so configure it in the app:",
    "",
    "  1. Cursor → Settings (Cmd/Ctrl + ,) → Models",
    "  2. Enable \"Override OpenAI Base URL\" and set it to:",
    `       ${apiBase}        (the /v1 suffix is required)`,
    "  3. Set the OpenAI API Key to your OmniRoute key (OMNIROUTE_API_KEY)",
    "  4. Add the model name(s) you want under \"Models\" (Cursor has no auto‑discovery):",
  ];
  const sample = (models && models.length ? models : ["glm/glm-5.2", "kmc/kimi-k2.7"]).slice(0, 8);
  lines.push(`       e.g. ${sample.join(", ")}`);
  lines.push("  5. Use the Chat panel (Cmd/Ctrl + L) to verify.");
  // ...
  return lines.join("\n");
}

```

### Manual Configuration Steps

After running the command, follow the printed instructions:

1. Open **Cursor → Settings (Cmd/Ctrl + ,) → Models**.
2. Enable **"Override OpenAI Base URL"** and set it to the printed URL (e.g., `http://localhost:20128/v1`).
3. Set the **OpenAI API Key** to your `OMNIROUTE_API_KEY` value.
4. Manually add model names under **Models** (e.g., `gpt-4`, `glm/glm-5.2`, `kmc/kimi-k2.7`).
5. Use the Chat panel (**Cmd/Ctrl + L**) to verify the connection.

**Note:** The custom base URL powers the **Chat panel only**—Composer, inline edit (**Cmd/Ctrl+K**), and autocomplete continue using Cursor's own backend.

## Integrating OmniRoute with Codex CLI

The Codex CLI reads configuration from standard OpenAI environment variables. Although the repository does not contain a dedicated `setup-codex` command, you can reuse the same resolution logic from `bin/cli/commands/setup-cursor.mjs` to build a setup script or simply export the variables directly.

### Environment Variable Configuration

Set the required environment variables to point Codex at OmniRoute:

```bash
export OPENAI_API_BASE=http://localhost:20128/v1
export OPENAI_API_KEY=$OMNIROUTE_API_KEY

```

For a remote instance:

```bash
export OPENAI_API_BASE=https://omniroute.example.com/v1
export OPENAI_API_KEY=sk-your-omniroute-key

```

After exporting these variables, any `codex` command (such as `codex generate` or `codex chat`) routes through OmniRoute, benefiting from its combo engine, rate-limiters, and usage-tracking layers.

### Alternative: Reusing the Resolution Logic

You can create a Codex-specific setup command by importing `resolveCursorTarget` from the Cursor setup module:

```ts
// bin/cli/commands/setup-codex.mjs
import { resolveCursorTarget as resolveTarget } from "./setup-cursor.mjs";

export async function runSetupCodex(opts = {}) {
  const { apiBase, apiKey } = resolveTarget(opts);
  console.log("\nAdd the following environment variables for Codex CLI:");
  console.log(`  OPENAI_API_BASE=${apiBase}`);
  console.log(`  OPENAI_API_KEY=${apiKey}`);
}

```

## Verifying the Integration

Regardless of the client, confirm the wiring with a direct request to the models endpoint:

```bash
curl -s -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
     "$OPENAI_API_BASE/models" | jq '.data[]?.id' | head

```

You should see OmniRoute’s model catalog (e.g., `gpt-4`, `claude-sonnet-5`, `glm/glm-5.2`), confirming that requests route correctly through the proxy.

## Summary

- **Cursor integration** uses the `omniroute setup-cursor` command from `bin/cli/commands/setup-cursor.mjs` to generate UI instructions; you manually paste the base URL (`http://localhost:20128/v1`) and API key into Cursor's Models settings.
- **Codex CLI integration** requires exporting `OPENAI_API_BASE` and `OPENAI_API_KEY` environment variables to point at your OmniRoute instance.
- Both methods expose OmniRoute's OpenAI-compatible API, enabling centralized control over routing strategies, prompt compression, and usage analytics.
- Use the `--remote` flag to connect to non-local OmniRoute instances, and `--only` to filter available models in the setup output.

## Frequently Asked Questions

### What port does OmniRoute use by default?

OmniRoute runs on **port 20128** by default. The `setup-cursor` command automatically resolves `http://localhost:20128` unless you specify a `--port` option, set the `PORT` environment variable, or pass a `--remote` URL.

### Can I use a remote OmniRoute instance instead of localhost?

Yes. Pass the `--remote` flag followed by the URL (e.g., `omniroute setup-cursor --remote https://omniroute.example.com`). The `resolveCursorTarget` function strips trailing slashes and ensures the `/v1` suffix is appended correctly.

### Why does Cursor require manual UI configuration instead of file-based setup?

According to the source code in `bin/cli/commands/setup-cursor.mjs`, **Cursor stores its configuration in an opaque SQLite database** that cannot be directly modified by the CLI. Therefore, the `setup-cursor` command prints instructions that you must manually enter into the Settings UI rather than writing a configuration file.

### Does OmniRoute support filtering which models appear in Cursor?

Yes. The `setup-cursor` command accepts an `--only` flag (e.g., `--only gpt-4,claude-sonnet`) that filters the model list fetched from `/v1/models` before printing the instructions. This helps you copy-paste only the model IDs you intend to use, since Cursor requires manual entry and does not auto-discover available models.