CliRelay: A Self-Hosted Gateway That Puts AI Coding CLIs Behind One Endpoint

The Problem: Subscription Credentials Scattered Across Machines

AI coding CLIs each expect to talk to their own vendor endpoint with their own credential. Claude Code holds an Anthropic OAuth credential, Gemini CLI holds a Google one, Codex holds an OpenAI one. When a team wants to share those subscriptions, the credentials get copied to laptops, and nothing records who spent what. CliRelay's answer is to put a single HTTP endpoint at port 8317 in front of all of them, so the CLI points at your server instead of the vendor, and the server holds the upstream credentials.

The README describes the audience directly: the project is built to be operated by more than one person. That is the dividing line. A solo developer who wants to route around a vendor outage can do that with a small reverse proxy. CliRelay is aimed at whoever has to answer the question of which account used the quota last Tuesday, and the multi-tenant console is where that answer lives.

How Traffic Moves: Channels, Groups and Failover

The architecture is a proxy with a control plane bolted on. On the data path, a client request arrives at the unified endpoint, and CliRelay selects an upstream channel. Channels are the individual credentials or upstream services, and the README lists the supported set: Gemini, Claude, Codex, Qwen, iFlow, Kimi, Antigravity, xAI/Grok, Vertex, Bedrock, OpenCode Go, ClinePass, Ollama Cloud, generic OpenAI-compatible upstreams, and Amp.

Selection has two documented strategies, round-robin and fill-first, applied across multiple API keys for the same provider. Groups are the second layer: channels are bound into groups, API keys are restricted to allowed groups, and groups can be exposed under custom path namespaces. Auto failover switches to a backup channel when a quota is exhausted or an error occurs.

That is a reasonable shape, but note what the README does not specify: the failover trigger conditions beyond quota exhaustion and unspecified errors, and the failover ordering. If you need deterministic routing you will have to read the source, because the documentation gives the mechanism but not the policy.

The Runtime Stack Is PostgreSQL and Redis, Not a Config File

This is the detail that separates CliRelay from a lightweight proxy. The README states the runtime data stack is PostgreSQL 15+, Redis 7+, and Ent ORM. PostgreSQL is the source of truth for runtime data; Redis handles cache, locks, limits, queues, and state that can be rebuilt. There is no documented SQLite mode or single-binary embedded store.

So the deployment unit is not one process. It is the CliRelay binary plus a Postgres instance plus a Redis instance, and the operational surface includes database migrations through Ent, backup of the request log tables, and the retention policy that the README mentions only in passing: full request and response message content is stored in compressed form, with separate retention for content versus metadata.

That separate retention is the right design, because message bodies are the expensive part. It also means the default retention values matter more than most configuration in this project, and the README excerpt does not state them. Treat the retention settings as something to read from the configuration before you point production traffic at the gateway.

Getting It Running: Ports, Panel and Management API

The README gives the endpoint as http://localhost:8317 and describes a management panel hosted at /manage, with a separate repository, kittors/codeProxy, listed as the management panel. Documentation lives at help.router-for.me. The Go toolchain requirement shown in the README badge is Go 1.26 or later.

Configuration keys visible in the material are namespaced permission strings rather than server settings: governance.tenants, models.write and providers.test are examples of the resource.action format used by the role model. That tells you how authorization is configured, not how the process is configured. The README excerpt does not show the server config file, the environment variables for the Postgres and Redis connections, or the command that starts the binary, so those are the first things to locate in the documentation site rather than guess at.

API keys are managed through a Management API with create, edit and delete operations, each key carrying a name, notes, and an independent enable/disable toggle. Portal accounts group several keys under one end-user identity. Per-key quotas cap tokens or requests, and period quota resets clear spending quotas for a chosen period.

Where CliRelay Is the Wrong Tool

The dependency footprint is the first limitation. If your use case is one developer, one machine, and a handful of API keys, running Postgres and Redis to proxy HTTP requests adds two services that can fail independently of the thing you actually care about. A stateless proxy with a config file and no database would cover that case with less to operate.

Second, the project is a fork. The README describes CliRelay as a heavily enhanced fork of CLIProxyAPI, rebuilt with a management layer, web control panel hosting, and a terminal TUI. A fork inherits its upstream's protocol quirks and diverges over time; the release notes in the supplied material show protocol fixes shipping regularly, including a Codex native web search fix in v0.5.1 and protocol repairs alongside scheduling changes in v0.5.0. Frequent protocol patches are expected for a project tracking several vendor APIs, but they also mean upgrades are not cosmetic.

Third, storing full message bodies in PostgreSQL is a data-handling decision, not just a storage one. Prompts and completions from coding sessions can contain source code. The README says content is compressed and has separate retention from metadata, which is a mitigation, but anyone deploying this is choosing to persist that content in their own database.

The Alternative: Keep the Proxy, Drop the Database

The obvious comparison is the upstream project itself, CLIProxyAPI, which CliRelay forks. The difference in approach is scope, not protocol. CLIProxyAPI is the proxy engine; CliRelay keeps that engine and adds the operational layer around it: tenants, users, roles, audit logs, menu management, the /manage web panel, and the PostgreSQL-backed request log with analytics.

If you do not need tenancy or an audit trail, the upstream gives you the routing without the database. If you do need to know which key consumed which quota, the upstream does not have that surface, and you would be building the logging and quota layer yourself against its API. The trade is concrete: CliRelay costs you two stateful services and a schema to maintain, and buys you the accounting.

Maintenance Cost and the MIT Licence

Release cadence in the supplied material is high. v0.5.1 landed on 2026-09-08, v0.5.0 on 2026-09-07, and v0.4.34 on 2026-09-05. Three releases in four days is a project moving quickly, and the release titles cover protocol fixes and channel scheduling changes. Plan for upgrades that touch request handling, and read the release notes before pulling, because a scheduling change can alter which upstream serves a given request.

CliRelay is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and it is compatible with running the gateway inside a company. It says nothing about the terms of the upstream AI subscriptions you route through it; those are separate agreements between you and each vendor, and proxying a subscription for other people may fall outside them. The management panel is a separate repository with its own licence, which the supplied material does not state, so check it before shipping the panel to users.

The health score engine, WebSocket system stats, and analytics dashboards all read from the same PostgreSQL instance. If the database is unavailable, the README's description implies the runtime data is unavailable with it, so treat Postgres availability as part of your gateway's availability, not as a sidecar.

Who Should Deploy It, and What to Check First

CliRelay fits an organisation that already operates PostgreSQL and Redis, has several people or teams sharing AI CLI subscriptions, and needs per-key quotas plus an audit log of security-sensitive changes. It also fits anyone who wants a single endpoint that speaks OpenAI, Claude, Gemini and Codex protocols so that different CLIs can point at one address.

It does not fit a single developer, and it does not fit anyone unwilling to run a database alongside their proxy. Before deploying, verify four things: the default content retention values, since message bodies are the sensitive part; the configuration keys for the Postgres and Redis connections, which the README excerpt does not show; the licence of the kittors/codeProxy panel; and whether the failover policy documented in your version matches what you need, given that v0.5.0 changed channel scheduling. The permission strings give you the shape of the access model, so decide which accounts get models.write and providers.test before you hand out panel logins, not after.

Editorial conclusion

Adopt CliRelay if you already run PostgreSQL 15+ and Redis 7+ and need several people or teams to share CLI subscriptions with per-key quotas and an audit trail. Do not adopt it if you are one developer proxying your own keys: a single-user reverse proxy is a smaller dependency than this. Before deploying, verify that the management panel repository (kittors/codeProxy) is a version you are willing to run, and check what the message-body retention settings actually delete.

Official sources

1. Issues
2. kittors/CliRelay on GitHub
3. License: MIT
4. README
5. Releases