CliRelay

Contents

• What is CliRelay?
• Highlights
• How a request flows
• A tour of the control panel
• Supported providers
• Quick start
• Connect your tools
• Configuration essentials
• Deployment options
• Architecture
• Documentation
• Contributing
• License and acknowledgements

What is CliRelay?

A heavily extended fork of CLIProxyAPI, rebuilt around a production management layer, a web control panel and day-2 operations.

CliRelay turns AI CLI subscriptions, OAuth credentials, provider API keys and OpenAI-compatible upstreams into one managed API layer. Clients talk to a single endpoint using the OpenAI, Anthropic or Gemini protocol; CliRelay authenticates them with its own client keys, picks a healthy upstream account, translates the request when needed, and records what happened.

It is built to be run by a team. Tenants keep their accounts, keys and data apart; users get roles with fine-grained permissions; every security-sensitive change lands in an audit log; and portal accounts let end users hold several API keys and check their own usage without asking an admin.

PostgreSQL 15+ is the source of truth for runtime data. Redis 7+ holds caches, locks, rate limits, queues and other rebuildable state.

Highlights

How a request flows

flowchart LR
    subgraph clients["Your tools"]
        cc["Claude Code"]
        cx["Codex CLI"]
        gc["Gemini CLI"]
        oa["Any OpenAI-compatible client"]
    end

    subgraph relay["CliRelay :8317"]
        auth["Client key<br/>portal account · permission profile"]
        quota["Quotas & rate limits"]
        route["Channel group routing<br/>scheduling · cooldown · failover"]
        exec["Provider executors<br/>protocol translation"]
        auth --> quota --> route --> exec
    end

    subgraph upstreams["Upstream accounts"]
        oauth["OAuth accounts<br/>Claude · Codex · Gemini · Antigravity · Grok · Qwen · Kimi · iFlow"]
        keys["Provider keys<br/>OpenAI-compatible · Vertex · Bedrock · OpenCode Go · ClinePass · Ollama Cloud"]
    end

    clients --> auth
    exec --> oauth
    exec --> keys
    relay -. "request logs, usage rollups" .-> pg[("PostgreSQL")]
    relay -. "cache, locks, limits" .-> rd[("Redis")]

1. Authenticate. A client key resolves to its portal account and permission profile, which decide the allowed channel groups, models and quotas.
2. Admit. Daily, period and lifetime spending, request quotas, RPM, TPM and concurrency are checked before anything reaches an upstream — for HTTP and for Responses WebSocket turns alike.
3. Route. The request goes to a healthy channel (an AI account or a provider key) inside the allowed groups, following the scheduling strategy; failures cool the channel down and fail over to the next one.
4. Translate and record. The executor speaks the upstream's protocol, streams the answer back, and writes a request log row and usage rollups that power the dashboards.

A tour of the control panel

The control panel (kittors/codeProxy) is served by CliRelay at /manage. The screenshots below follow its own navigation and were taken from a live deployment; names, keys, addresses and accounts are replaced with sample values.

Observability

• Monitor center answers four questions at a glance: is it healthy, is it slow, what is failing, and where is traffic going.
  • The health score combines success rate, the share of traffic on failing channels and P95 latency against the previous period, and explains each check.
  • Six tiles cover requests, success rate, P95 latency, time to first token, tokens with cache hit rate, and cost — each with a period-over-period change and a sparkline.
  • Below them: a trend view, the latency distribution (P50 / P90 / P95 / P99), failures by channel, model or portal user, model / channel / user rankings, a traffic-flow diagram and a weekday × hour heatmap. Click any row to filter the whole page.
• Dashboard summarises requests, success rate, tokens, cost, failures and cache ratio for today, 7 or 30 days, next to a live system monitor (CPU, memory, disk, database and log storage).
• Request logs list every call with its channel, portal user and key, cache / input / output tokens, latency and cost. Filter by user, model, channel and status, and open the request and response bodies when body storage is enabled.

Access and credentials