CC Hub: a self-hosted Claude Code and Codex API gateway with load balancing and quotas

The problem CC Hub solves for teams sharing Claude Code and Codex

Claude Code and Codex are usually pointed at one provider account with one API key. That works for a single developer and breaks down the moment several people share the account. There is no per-person spend cap, no way to route around a provider outage, and no record of who consumed what. CC Hub exists to be that middle layer. It is a proxy that accepts Claude and OpenAI-compatible traffic, then decides which upstream provider handles each request according to weight, priority and group. The README frames the target user as a team that manages several AI service providers and wants the traffic to be observable and controllable. The repository is TypeScript, built on Next.js 16, Hono, PostgreSQL and Redis, and licensed MIT. It is not a client-side plugin or a statusline tool; it is a server you run.

How the routing, failover and rate limiting actually work

Requests arrive at the gateway and are matched to a provider through a scheduling decision that combines weight, priority and group. The README states there is built-in circuit breaking plus up to three failover attempts, so a failing upstream can be skipped rather than surfaced to the client. Sessions get a five-minute context cache, and the project records a decision chain, which is the audit trail of why a given request went where it went. Rate limiting is multi-dimensional: requests per minute, monetary limits over five-hour, weekly and monthly windows, and concurrent session counts. The interesting implementation detail is that these limits are enforced with Redis Lua scripts for atomicity, with a fail-open fallback. Fail-open is a deliberate trade-off: if Redis is unavailable, limits stop being enforced rather than blocking all traffic. For a team worried about runaway spend, that is a policy decision worth knowing about before deployment. The README also mentions an API key vacuum filter (ENABLE_API_KEY_VACUUM_FILTER, default true) that short-circuits invalid keys before they reach the database, which reduces load and slows brute-force attempts. The gateway exposes 39 REST endpoints documented as OpenAPI 3.1.0, generated from Server Actions, with both Swagger and Scalar UIs. OpenAI-compatible clients are served through /v1/chat/completions, and the README says tool calls and reasoning fields pass through with strict same-format routing and no cross-format conversion.

Installing CC Hub with the deploy script or Docker Compose

The README recommends a one-click deploy script that checks for Docker and Docker Compose, creates the deployment directory, generates an admin token and database password, starts the services and prints the access address. On Linux and macOS it downloads scripts/deploy.sh, marks it executable and runs it.

curl -fsSL https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.sh -o deploy.sh
chmod +x deploy.sh
./deploy.sh

Windows users run the PowerShell equivalent in an administrator shell, which downloads scripts/deploy.ps1. The script asks which branch to deploy: main for the stable version recommended for production, or dev for the development version. Keep the admin token it prints; the README calls it the only credential for logging into the backend.

The manual path is three steps. Clone the repository, copy the environment template, then edit .env and change ADMIN_TOKEN before starting anything.

git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
cp .env.example .env

The .env.example ships ADMIN_TOKEN=change-me, so leaving it untouched means a publicly known login credential. The Docker Compose defaults set DSN to postgres://postgres:postgres@postgres:5432/claude_code_hub and REDIS_URL to redis://redis:6379.

docker compose up -d
docker compose ps
docker compose logs -f app

After startup the admin backend listens on http://localhost:23000, the Scalar API docs on http://localhost:23000/api/actions/scalar and the Swagger UI on http://localhost:23000/api/actions/docs. The compose file keeps PostgreSQL and Redis off the host network by default; the database port is only exposed if you uncomment the 127.0.0.1:35432 mapping. Data persists under ./data/postgres and ./data/redis, with Redis running in append-only mode. The first real task after login is adding a provider and its credentials, then pointing a Claude Code or Codex client at the gateway. The README points to docs/api-authentication-guide.md for scripted or programmatic access and docs/public-status-api.md for the unauthenticated status endpoint.

Multi-process mode and the Redis dependency it creates

The production entry point is cluster.js, and CCH_MULTICORE_MODE controls how many gateway processes run. The default, auto, only enables multiple processes when the machine has at least 4 effective vCPUs and enough memory budget; 4 vCPUs yields two full gateway processes and 8 or more vCPUs yields up to four. CCH_MULTICORE_WORKERS can force a specific count between 1 and 32, where 1 means single process. The constraint that matters operationally: multi-process mode depends on Redis Pub/Sub to synchronize security settings, routing, system settings and provider group billing multipliers. If Redis is not configured, or if ENABLE_RATE_LIMIT is turned off, auto silently falls back to a single process, while an explicit multi-process setting fails to start. So the same Redis instance is doing rate limiting, session state and cross-process coordination. Anyone planning a single-process deployment to simplify operations should know they are giving up the throughput scaling path, and anyone enabling multi-process should size Redis accordingly. The compose file also caps database connections: DB_POOL_MAX defaults to 20 and is described as a total budget across data, control and writer pools, split deterministically across gateway processes. In Kubernetes, each Pod carries its own budget, so total connections scale with replica count.

Where CC Hub is the wrong tool

CC Hub is infrastructure, and it asks you to run infrastructure. If one developer wants to route Claude Code through a different endpoint, a local proxy or a client-side configuration change is a smaller answer than PostgreSQL, Redis and a Next.js application. The README's own environment requirements confirm the weight: Docker and Docker Compose are required, and local development additionally needs Node.js 22.15 or later, with Bun 1.3 optional. The database port is deliberately not published, which is good hygiene but also means debugging requires uncommenting a mapping or execing into the container. The fail-open behavior on rate limits is a real limitation for anyone treating quotas as a hard financial control: when Redis is down, enforcement stops. The README also carries a prominent notice that the project is in an active refactor and that CC Hub Plus, an AGPL rewrite described as a commercial-grade LLM gateway with format conversion, privacy filtering, model marketplace and billing, is expected in the third quarter. The notice states that during that refactor, development progress and community support for the Node.js version may be delayed. That is a maintenance risk stated by the project itself, not an inference. The last push to the repository was on 2026-09-11, and the most recent release listed is v0.9.5 from 2026-09-02.

How CC Hub differs from LiteLLM and a plain reverse proxy

The closest category is a general LLM gateway. LiteLLM is the reference point many teams reach for, and the difference in approach is visible in CC Hub's feature list: it includes LiteLLM synchronization for its price table, meaning it treats LiteLLM as a source of model pricing rather than as the gateway itself. CC Hub's design centers on Claude Code and Codex clients specifically, with session caching, decision-chain auditing and OpenAI-compatible routing at /v1/chat/completions that the README says passes tool calls and reasoning fields through without cross-format conversion. A generic gateway typically normalizes between provider formats; CC Hub explicitly does not, which reduces translation bugs but also means a client speaking a format the gateway does not route natively will not be accepted. Against a plain reverse proxy such as nginx, the difference is everything above the transport layer: weighted provider selection, circuit breaking, three-attempt failover, per-user monetary windows and a usage dashboard. A reverse proxy forwards bytes; CC Hub decides which upstream gets them and records why.

Licence, upgrade cost and what the refactor means for adopters

The current repository is MIT licensed, which permits commercial use, modification and redistribution with the usual attribution requirement. The README states that the planned CC Hub Plus rewrite will be released under AGPL instead. That is a licence change for the successor project, not a retroactive change to this codebase, but teams planning to migrate should treat the licence shift as a factor in their planning rather than assume continuity. On upgrades, the compose stack pins postgres:18 and redis:7-alpine, and the app image is ghcr.io/ding113/claude-code-hub:latest. Pulling latest means tracking whatever the maintainers publish; the release cadence visible in the repository is roughly every ten days across v0.9.3, v0.9.4 and v0.9.5, which is frequent enough that pinning a digest is worth considering for production. AUTO_MIGRATE defaults to true, so schema migrations run on startup, and the README notes it can be disabled. The Dockerfile runs Node with --report-on-fatalerror and --report-uncaught-exception, writing diagnostic JSON into /app/reports, and explicitly passes --report-exclude-env so that ADMIN_TOKEN, DSN, Redis, Langfuse and provider credentials are not persisted into those reports. Anyone mounting that directory should still treat the reports as sensitive operational data. This is not legal advice; review the MIT terms and the announced AGPL plans against your own distribution model.

Editorial conclusion

Adopt CC Hub if you run Claude Code or Codex for several people and want one endpoint, shared provider credentials and per-user spend limits that you control. Do not adopt it if you need a single-user local proxy, if you cannot operate PostgreSQL and Redis, or if you depend on long-term maintenance of this Node.js codebase: the README states the project is being refactored into CC Hub Plus under AGPL and that community support for the current version may lag. Verify first that your deployment can satisfy the multi-process prerequisites (Redis configured with ENABLE_RATE_LIMIT enabled) if you intend to run CCH_MULTICORE_MODE=auto, and check the docs/api-authentication-guide.md before wiring any client or script to the gateway.

Frequently asked questions

Official sources

1. ding113/claude-code-hub on GitHub
2. License: MIT
3. Project website
4. README
5. Releases