ccLoad

Self-hosted AI API gateway for Claude Code, Codex, Gemini, and OpenAI-compatible clients.

English | 简体中文 · Website

▶ Watch the 47-second overview · 中文版

What Is ccLoad

You may have several AI sources: official API keys, third-party relay services, and ChatGPT or Claude subscriptions. Each client has to be configured separately, and when one quota runs out or an upstream fails, a running Claude Code or Codex session stops.

ccLoad is a gateway you run on your own computer or server. It manages all of those sources, and every client only needs the ccLoad address and a ccLoad token:

Claude Code / Codex / Gemini / OpenAI-compatible tools
                │  one address + one ccLoad token
                ▼
             ccLoad   pick an upstream → retry the next one on failure → convert protocols if needed → record usage and cost
                │
   ┌────────────┼──────────────┬──────────────────────────┐
Official API keys  Relay services  Codex / Claude and other subscriptions  …

Three terms are used throughout the steps below:

• Channel: one upstream source, such as "a relay service's URL plus key" or "a signed-in Codex account". Each channel lists the models it serves.
• API token: the key ccLoad gives to your clients. Clients only talk to ccLoad with this token and never see the real upstream keys.
• Admin console: open http://your-host:8080/web/ and sign in with the admin password CCLOAD_PASS to add channels, create tokens, and view logs and costs.

Who It's For

• Developers with several AI subscriptions: Combine ChatGPT, Claude and other plans with spare API keys, so Claude Code and Codex keep running when one quota runs out.
• Teams sharing model access: Give each teammate a token with model, budget and concurrency limits. Upstream credentials stay in one place and access can be revoked at any time.
• Operators running many channels: Manage channels with priorities, health-based ordering, scheduled checks, CSV import and export, and a log entry for every request.

Quick Start

Five steps get Claude Code or Codex working through ccLoad.

Step 1: Install and start

Pick one method. Every method requires the admin password CCLOAD_PASS; without it the service exits immediately. The service listens on port 8080 by default.

Docker (recommended):

docker run -d --name ccload \
  -p 8080:8080 \
  -e CCLOAD_PASS=your_admin_password \
  -v ccload_data:/app/data \
  ghcr.io/caidaoli/ccload:latest

Data lives in the Docker volume ccload_data, so removing or upgrading the container keeps it.

Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/caidaoli/ccLoad/master/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/caidaoli/ccLoad/master/.env.docker.example
# Edit .env and set CCLOAD_PASS to your admin password
docker compose up -d

Homebrew (macOS / Linux):

brew tap caidaoli/ccload https://github.com/caidaoli/ccLoad.git
brew install caidaoli/ccload/ccload

# Create .env in the config directory with one line: CCLOAD_PASS=your_admin_password
mkdir -p "$(brew --prefix)/var/ccload"
cd "$(brew --prefix)/var/ccload"
(umask 077; touch .env)
${EDITOR:-vi} .env

brew services start caidaoli/ccload/ccload

Download the binary: get the file for your platform from Releases (ccload-linux-amd64, ccload-linux-arm64, ccload-darwin-arm64, ccload-darwin-amd64, ccload-windows-amd64.exe). On Linux:

chmod +x ccload-linux-amd64
CCLOAD_PASS=your_admin_password ./ccload-linux-amd64

Data is stored in data/ccload.db under the current directory by default.

Without a server, you can deploy for free on Hugging Face Spaces; see Deployment.

Check that the service is up:

curl http://localhost:8080/health

On a server, replace every localhost in this guide with the server's IP address or domain.

Step 2: Sign in to the admin console

Open http://localhost:8080/web/ and sign in with the CCLOAD_PASS from step 1.

Step 3: Add a channel

Go to Channels and click Add Channel:

• API-key upstreams (official APIs, relay services): the easiest way is Auto-fill channel configuration. Paste the address and key your provider gave you (for example OPENAI_BASE_URL=https://api.example.com and OPENAI_API_KEY=sk-...); ccLoad checks the connection and fetches the model list. When filling the form by hand, enter only the base URL, without /v1 or an endpoint path.
• Subscription accounts (Codex/ChatGPT, Claude, Antigravity, xAI, CodeBuddy, Z.ai Coding Plan, Cursor, Zed): choose the account type in Channels and follow the prompts to authorize in the browser or import credentials.

The model list decides whether a channel is used. ccLoad picks channels by the model name the client requests: if the client asks for claude-sonnet-4-6, some channel must list claude-sonnet-4-6. Add models with Fetch Models or Common Models; when the upstream uses a different name, put the upstream name in Redirect Target.

After saving, click Test on the channel to confirm it responds.

Step 4: Create an API token

Go to API Tokens (/web/tokens.html), create a token and copy it. Every client uses it to reach ccLoad; /v1/* and /v1beta/* requests without a token return 401.

Step 5: Point your clients at ccLoad

Test with curl first. Replace your-api-token with the token from step 4 and the model with one configured on your channel:

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude!"}]
  }'

Claude Code:

1. Edit ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json on Windows). Create it if it does not exist; if it already has other settings, merge just these two entries into env:

   {
     "env": {
       "ANTHROPIC_BASE_URL": "http://localhost:8080",
       "ANTHROPIC_AUTH_TOKEN": "your-api-token"
     }
   }
   

   Leave /v1 off the address; Claude Code appends /v1/messages itself. Settings in this file apply to every terminal and IDE extension, so no shell profile changes are needed.

2. Make sure the model names match. Besides the main model, Claude Code uses a Haiku model (such as claude-haiku-4-5) for background tasks like title generation, and every one of these names must appear in some channel's model list. If your channels lack them, point them at models your channels do have; the full file becomes:

   {
     "env": {
       "ANTHROPIC_BASE_URL": "http://localhost:8080",
       "ANTHROPIC_AUTH_TOKEN": "your-api-token",
       "ANTHROPIC_DEFAULT_OPUS_MODEL": "model-name-from-your-channel",
       "ANTHROPIC_DEFAULT_SONNET_MODEL": "model-name-from-your-channel",
       "ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-name-from-your-channel"
     }
   }
   

3. Verify: run claude -p "hello"; a reply means it works. In interactive mode, /status shows the current base URL.

Codex CLI:

1. Log in with your ccLoad token (this replaces any existing ChatGPT login in Codex; the same command works in Windows PowerShell):

   echo your-api-token | codex login --with-api-key
   

2. Edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), If the file does not exist, create it and paste everything below. If it already has content, add the two parts separately: the model_provider = "ccload" line at the very top of the file (before any [...] section, or it will not take effect), and the whole [model_providers.ccload] block at the end of the file:

   model_provider = "ccload"
   
   [model_providers.ccload]
   name = "OpenAI"
   base_url = "http://localhost:8080/v1"
   wire_api = "responses"
   requires_openai_auth = true
   supports_websockets = true
   

   base_url must include /v1. requires_openai_auth = true makes Codex use the token from the previous step, and supports_websockets = true enables Responses WebSocket.

3. Verify: run codex exec --skip-git-repo-check "hello"; a reply means it works.

   If you use the app-server daemon (for example codex agents or codex remote-control): the daemon is a long-running process, so not every change applies right away. After you edit config.toml, sessions already open keep the old settings and only new sessions pick up the change; after you run codex login again with a new token, the daemon keeps using the old token until it restarts. After changing the config or logging in again, run:

   codex app-server daemon restart
   

   To check whether the daemon is running, run codex app-server daemon version; a failed to connect error means it is not running and needs no restart.

Other OpenAI-compatible tools (Cherry Studio, SDKs, and so on): set the base URL to `http://localhost: