9Router AI Routing Proxy

9Router is free, open-source software and does not charge any fees, send invoices, or handle credit card information. It acts as a local proxy/router.

How Billing Works

• 9Router Software: Always FREE.
• Providers: You pay your AI providers (e.g., Claude, OpenAI, Anthropic) directly via their own subscription or API models.
• Dashboard Costs: The costs displayed in the 9Router dashboard are estimated savings trackers, not actual bills. They show what you would have paid if you were using paid APIs directly, helping you visualize the value of using free models or existing subscriptions.

Provider Categories

9Router acts as a local AI routing gateway that provides an OpenAI-compatible API surface (/v1/*). It sits between developer clients (like Claude Code, Codex CLI, or Continue) and upstream AI providers (like OpenAI, Anthropic, or Gemini).

Core Capabilities

• OpenAI-compatible API: Use standard OpenAI SDKs/CLIs by pointing them to the 9Router endpoint.
• Request Translation: Automatically converts requests between different provider formats.
• Fallback Mechanisms:
  • Model Combo Fallback: If a requested model fails, 9Router can iterate through a sequence of models defined in a 'combo'.
  • Account Fallback: If one API key or OAuth account hits a rate limit or error, 9Router automatically tries the next available account for that provider.
• Usage Tracking: Logs costs and token usage locally.
• Local Persistence: Stores all provider connections, keys, and settings in a local JSON database.

sequenceDiagram
    autonumber
    participant Client as CLI/SDK Client
    participant Route as /api/v1/chat/completions
    participant Chat as src/sse/handlers/chat
    participant Core as open-sse/handlers/chatCore
    participant Model as Model Resolver
    participant Auth as Credential Selector
    participant Exec as Provider Executor
    participant Prov as Upstream Provider
    participant Stream as Stream Translator
    participant Usage as usageDb

    Client->>Route: POST /v1/chat/completions
    Route->>Chat: handleChat(request)
    Chat->>Model: parse/resolve model or combo
    ...
    Core->>Prov: upstream API call
    Prov-->>Exec: SSE/JSON response
    Exec-->>Core: response + metadata
    Core->>Stream: translate/normalize stream to client format
    Stream-->>Client: SSE chunks / JSON response
    Stream->>Usage: extract usage + persist history/log

The 9router reasoning level resolution logic is provider-scoped. This ensures that specific reasoning overrides for OpenAI Codex (cx/) do not unintentionally affect other providers like Kiro (kr/) even if they use similar model names.

Resolution Logic for cx/ provider

1. Parsing: The system recognizes (max) and (ultra) as discrete reasoning levels via the suffix parser.
2. Translation:
   • If the requested level is supported by the specific Codex model, it is preserved.
   • For gpt-5.6-luna, an ultra request is converted to max (the highest supported level for Luna).
   • For any other unsupported max or ultra requests, the system converts them to xhigh as a safe fallback.
3. Execution: The Codex executor resolves virtual models (like -review variants) to their base models before dispatching, ensuring the reasoning level is correctly applied to the upstream Codex Responses endpoint.

Note: Do not use hyphen-suffixes like gpt-5.1-codex-max for reasoning overrides; max in that context is part of the actual model identifier. Always use the parenthesized syntax (max) or (ultra) for reasoning level overrides.

9Router uses a 3-tier fallback system to automatically route requests through the best available provider based on quota, cost, and availability. This ensures continuous service even when primary subscriptions are exhausted or rate-limited.

The 3 Tiers

1. Tier 1: SUBSCRIPTION (Primary) - Maximizes value from existing paid services (e.g., Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot).
2. Tier 2: CHEAP (Backup) - Ultra-low-cost providers used when subscription quotas run out (e.g., GLM-4.7, MiniMax M2.1, Kimi K2).
3. Tier 3: FREE (Emergency) - Zero-cost providers for unlimited coding when budgets are reached (e.g., iFlow, Qwen, Kiro).

Routing Logic

When a request is made, 9Router follows this sequence:

1. Check Quota: Verifies if the primary provider has remaining quota.
2. Check Cost Tier: Follows the hierarchy: Subscription $\rightarrow$ Cheap $\rightarrow$ Free.
3. Check Reset Timing: Considers when quotas will reset.
4. Check Provider Health: Automatically skips providers returning errors (e.g., 503 Service Unavailable).

Request $\rightarrow$ 9Router $\rightarrow$ Check Tier 1 (Subscription)
                     $\downarrow$ quota exhausted
                     Check Tier 2 (Cheap)
                     $\downarrow$ budget limit
                     Check Tier 3 (Free)
                     $\downarrow$
                     Response