CliRelay

A self-hosted gateway that puts your AI coding subscriptions and API keys behind one endpoint — with a multi-tenant control panel to run it.

Route Claude Code, Codex, Gemini CLI and any OpenAI-compatible client through the accounts you already pay for.
See every request, cap every key, and fail over automatically when an account runs dry.

English | 中文

Docs · Control panel · Releases · Report a bug

---

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.

More monitor-center views

Model performance, channel health and portal users	Dark theme

Access and credentials

• Add AI account groups every way in by what you will do — sign in with a browser, enter a device code, or import a credential — and walks through the steps that provider actually has, including which address to copy back and why the landing page does not load.
• Credential import turns a held credential (Claude session key, Codex or Antigravity refresh token, Grok SSO cookie) into an account. It explains where to find each one and what handing it over means, accepts many at once, and retries failed rows on their own.
• AI accounts show each OAuth account with its plan, quota windows, success rate and subscription expiry; AI providers hold API-key upstreams with base URL, headers, proxy binding and per-key model lists.
• Portal accounts own one or more client keys and share a quota; permission profiles bundle channel groups, models, limits and an optional system prompt so a new user is set up in one pick.
• Content moderation profiles can be tested against sample text and bound to accounts, keys or a provider default; CC Switch config builds one-click import presets for Claude Code and Codex.

Models and routing

• Model plaza shows every model the current tenant can reach, with capabilities, the channels that serve it and its price per million tokens.
• Model catalog is where models, owners, capabilities and pricing are maintained, with an optional OpenRouter sync and a built-in model test.
• Channel groups decide which channels a key may use and how traffic is spread inside the group; groups can follow new upstream models automatically.
• Outbound proxies are defined once and bound to the accounts or provider keys that need a fixed egress IP.

Organization

• Tenants carry their own accounts, keys, routing and data, with a lease period; administrators switch the effective tenant from the header.
• Roles grant resource.action permissions such as providers.test or models.write, which decide the pages, buttons and API calls each user gets.
• Audit logs record who changed what, from where, and whether it succeeded.

System

• Config edits the running configuration through grouped forms with inline validation, or as YAML in the source editor; a recommended low-resource profile tunes small hosts in one click.
• System info shows the API and management endpoints, backend and panel versions, and checks for updates.
• Menu management curates which entries a tenant sees and which permission each requires.

Supported providers

Quick start

Docker Compose is the recommended installation. It starts CliRelay, PostgreSQL 15, Redis 7 and the updater sidecar.

git clone https://github.com/kittors/CliRelay.git
cd CliRelay
# Linux bind mounts need write access for the non-root container user:
# sudo chown -R 10001:10001 auths logs data
docker compose up -d

On the first start, the clirelay-init service creates .env and config.yaml if they are missing and generates the secrets it needs (CLIRELAY_ADMIN_PASSWORD, CLIRELAY_POSTGRES_PASSWORD, CLIRELAY_UPDATER_TOKEN). Existing non-empty values are kept.

Then, in the control panel:

1. Add an upstream — AI Accounts → Add AI account to sign in with a subscription or import a credential, or AI Providers for an API key.
2. Create a client key — Portal Accounts → Create user; each portal account holds one or more keys. A fresh install ships with no client key and rejects client requests until you create one; the your-api-key-* values in config.example.yaml are placeholders that are always rejected.
3. Point your tools at CliRelay — see below.

[!NOTE] The container runs as 10001:10001; config.yaml must be readable by it, and writable if you want to save config from the panel. If a Synology/DSM shared-folder ACL blocks the entrypoint's chown, fix ownership on the host and restart cli-proxy-api. If you pre-set CLIRELAY_ADMIN_PASSWORD, use at least 12 characters with an upper-case letter, a lower-case letter and a symbol; a weaker value is replaced on the next start.

Connect your tools

Use a client key created in the panel wherever a tool expects an API key.

Claude Code

export ANTHROPIC_BASE_URL=http://localhost:8317
export ANTHROPIC_AUTH_TOKEN=sk-your-client-key
claude

Codex CLI (~/.codex/config.toml)

model_provider = "clirelay"

[model_providers.clirelay]
name = "openai"
base_url = "http://localhost:8317/v1"
requires_openai_auth = true

Any OpenAI-compatible client

curl http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-your-client-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello"}]}'

[!TIP] CC Switch Config in the panel builds a one-click import link for Claude Code and Codex, with the model mapping and channel group already filled in.

Full client guides: help.router-for.me.

Configuration essentials

Everything below can be changed in the panel's Config page or in config.yaml.

# Keep full bodies for 7 days, capped at 2 GB
request-log-storage:
  store-content: true
  content-retention-days: 7
  max-total-size-mb: 2048

# Follow dev builds, or turn update checks off
auto-update:
  enabled: true
  channel: dev

Config and credential storage can also live in PostgreSQL, Git or an S3-compatible object store instead of local files, selected through environment-based bootstrap settings.

Deployment options

Online updates run through the updater sidecar: the panel shows the target version, each stage as it happens, and the result, and reconnects on its own if the API restarts during the update.

Architecture

CliRelay/
├── cmd/server/               # Binary entry point and CLI modes
├── internal/api/             # HTTP server, management routes, middleware
├── internal/auth/            # Provider OAuth, cookie and device-code flows
├── internal/runtime/         # Executors per provider, scheduling, cooldown
├── internal/translator/      # OpenAI ⇄ Anthropic ⇄ Gemini ⇄ Responses translation
├── internal/identity/        # Tenants, users, roles, permissions, menus, audit logs
├── internal/usage/           # Request logs, rollups, monitor endpoints, retention
├── internal/config/          # Config parsing, defaults, migrations
├── internal/store/           # Local, Git, PostgreSQL and object-store persistence
├── internal/managementasset/ # /manage panel hosting and asset sync
├── internal/tui/             # Terminal management UI
├── sdk/                      # Embeddable Go SDK, handlers and executors
├── deploy/                   # Cluster building blocks and deploy scripts
└── docker-compose.yml        # Default container deployment

Documentation

Contributing

git clone https://github.com/kittors/CliRelay.git
cd CliRelay
git fetch origin
git switch -c feature/your-change origin/dev
# make your change, then
git push origin feature/your-change   # and open a pull request against dev

Please target pull requests at dev, not main; main is updated by releases. See CONTRIBUTING.md for the branch and merge workflow.

License and acknowledgements

CliRelay is released under the MIT License.

It stands on the core proxy logic of router-for-me/CLIProxyAPI. Our thanks to the original project and all its contributors — their foundation made it possible to build the management layer, request logging, quota control and the control panel on top.