ccLoad

What ccLoad solves

ccLoad is described as an AI API gateway for Claude Code, Codex, Gemini, and OpenAI compatible clients. The README states it removes the operational mess of running multiple AI API upstreams by keeping those clients on one stable gateway, then handling upstream selection, failover, cooldown, protocol conversion, request visibility, and cost limits in the service instead of in every client script. The stated problem cases are manual channel switching across different credentials and quotas, rate limits and upstream failures such as 429 and 502 and 504, opaque request status during long streaming requests, HTTP 200 responses that contain error content, and cost drift across shared gateways. ccLoad answers these with smart routing that picks high-priority channels first and uses weighted round-robin among equal channels, automatic failover that skips failed credentials, models, channels, and URLs by classified error scope, and model-aware cooldown that cools only the actual upstream model for structured cooldown responses, 5xx, a 429 at the credential level, model-unavailable 404, and model-retirement 410, promoting the whole channel to cooldown only after every model or credential is cooling. Multi-URL scheduling weights a single channel's URLs by observed latency and health, and per-URL protocol routing declares the wire protocols each URL accepts. The README also describes soft-error detection that catches HTTP 200 bodies carrying an error structure or SSE rate-limit events, routing them through the same failover path as a genuine upstream failure so a client session is not silently broken.

Features and monitoring

The README lists a long set of features. The architecture uses the Gin framework and claims support for more than one thousand concurrent connections with high-performance caching. Local token counting is described as API-compliant with sub-five-millisecond response and over ninety-three percent accuracy. Smart error classification distinguishes credential-level, model, channel, and client errors, and detects soft errors where HTTP 200 masks an actual error, treating SSE rate-limit errors as 429. Failover shares one exponential-backoff policy across credential-level, model, and channel failures, with explicit upstream reset deadlines taking priority. Live monitoring shows active requests, logs, token usage, time to first byte, cost, and upstream details in a web dashboard, with token usage stats and a runtime status panel reporting CPU, resident memory, and garbage collection. OAuth channels cover Codex, Anthropic, Antigravity, and xAI with automatic refresh where supported, plus Cursor and Z.ai imports, with batch quota refresh and auto-disable for rejected credentials. Cost controls include per-channel daily limits, per-token limits, rolling sixty-second request caps, and per-channel concurrency caps. Other features include a responses WebSocket bridge, Docker multi-arch images, one-click Hugging Face Spaces deployment, channel time windows, per-token model restrictions, and debug logs with sensitive header masking. The README states the service uses token-based admin authentication and API access control, and that scheduled checks probe channel availability in the background so failed channels are detected without waiting for a live request to fail.

Deployment and storage

The README gives several deployment paths. Docker is recommended, either with a prebuilt image or a source build through compose, and the service requires a CCLOAD_PASS value or it exits. A source build uses Go with a high-performance JSON library enabled by default, and a binary download is offered for Linux amd64. Hugging Face Spaces deployment is described as free, with a small Dockerfile and auto HTTPS, though the free tier has resource limits, a sleep policy after forty-eight hours without access, a fixed port, and public access that requires API tokens. Storage can use embedded SQLite by default, or MySQL and PostgreSQL, which are mutually exclusive. A hybrid mode keeps authoritative I/O on SQLite first and coalesces writes to a remote database every ten seconds, while a pure external database mode stores everything remotely for restart safety. The README notes that on Hugging Face the tmp directory clears on restart, so an external database is recommended for persistence. OAuth quota cost tracking accumulates per-credential weekly and monthly standard cost aligned to upstream quota windows, with a manual Codex quota reset when a reset credit is available. The architecture diagram shows clients reaching an HTTP proxy, authentication and route dispatch, a channel selector with priority and weighted round-robin, a protocol registry, and a URL selector, with storage and logs feeding back through SQLite, MySQL, or PostgreSQL.

Editorial conclusion

ccLoad is distributed under the MIT license, and the repository's most recent commit was on 2026-08-26. The gateway is hosted at github.com/caidaoli/ccLoad.