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

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:

omniroute setup-cursor

For a remote instance or custom port:

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:

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:

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:

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

For a remote instance:

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:

// 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}