English ｜ 简体中文

Every flow leaves a trace.

CPA Usage Keeper is a standalone persistence and analytics dashboard for CLIProxyAPI (CPA). It stores CPA usage in SQLite, pulls CPA configuration and credential data, and provides views for usage, cost, request health, quotas, and model/API statistics.

• Persist CPA usage data in SQLite, with optional scheduled backups
• Track requests, tokens, cost, cache usage, success rate, RPM/TPM, and latency, with filters for time range, model, API Key, source, and result
• Inspect and export request-level events with configurable table columns
• Analyze usage trends, cost composition, model/API Key/AI Provider mix, hourly heatmaps, and latency diagnostics
• Monitor Auth Files and AI Providers with usage metrics, health inspection, and quota refresh
• Opt into community rankings by overall score, tokens, requests, cache rate, average TTFT/latency, or peak TPM/RPM
• Open a read-only usage view scoped to an individual CPA API Key
• Sync CPA Auth Files, API Keys, and AI Providers automatically, and maintain model pricing for cost estimates
• Deploy with Docker/Docker Compose, Homebrew, binaries, or systemd, with optional password protection
• Embed the Keeper dashboard in CPAMC through the CPA plugin

• Thanks to CLIProxyAPI (CPA) for providing the upstream CPA foundation and data source this project builds on.
• Thanks to @YouShouldBetOnMe for supporting CPA Usage Keeper.
• Thanks to the CPA discussion group for their discussions and feedback.

Before using CPA Usage Keeper, make sure CPA usage statistics are enabled: usage-statistics-enabled: true.

Docker Compose is the recommended deployment method. Use the full stack when deploying CPA and Keeper together, or the Keeper-only stack when CPA already exists.

For public deployments, enable AUTH_ENABLED=true and configure LOGIN_PASSWORD to protect your data.

cmd/server/              Application entry point
internal/api/            HTTP routes and handlers
internal/app/            Application wiring and startup
internal/auth/           Sessions and access control
internal/poller/         CPA usage and metadata synchronization
internal/repository/     SQLite persistence and aggregations
internal/service/        Usage, pricing, and identity services
internal/quota/          Provider quota refresh and inspection
internal/ranking/        Community ranking aggregation and sync
deploy/linux/            systemd service template
web/                     React + TypeScript frontend

• Go 1.26+
• Node.js 22+
• npm
• A running CLIProxyAPI (CPA) instance

1. Copy .env.example to .env, then set at least CPA_BASE_URL and CPA_MANAGEMENT_KEY.

cp .env.example .env
vim .env

2. Start the backend.

go run ./cmd/server/main.go

3. In another terminal, install frontend dependencies and start the development server.

npm --prefix ./web ci
npm --prefix ./web run dev -- --host 127.0.0.1

Open http://127.0.0.1:5173. The frontend proxies /api to http://127.0.0.1:8080; override it with VITE_API_PROXY_TARGET when the backend uses another port.

Run the full verification baseline:

make verify

Or run checks individually:

go test ./cmd/... ./internal/...
npm --prefix ./web run test
npm --prefix ./web run lint
npm --prefix ./web run typecheck
npm --prefix ./web run build

Docker Compose is recommended for both a complete CPA + Keeper stack and a Keeper-only deployment.

Save the following as docker-compose.yml, then replace the management key and login password:

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    ports:
      - "8317:8317"
      - "1455:1455"
    volumes:
      - ./cpa/config.yaml:/CLIProxyAPI/config.yaml
      - ./cpa/auths:/root/.cli-proxy-api
      - ./cpa/logs:/CLIProxyAPI/logs
    networks:
      - cpa-network

  cpa-usage-keeper:
    image: ghcr.io/willxup/cpa-usage-keeper:latest
    container_name: cpa-usage-keeper
    restart: unless-stopped
    depends_on:
      - cli-proxy-api
    ports:
      - "8080:8080"
    environment:
      TZ: Asia/Shanghai # Sets the container timezone; log timestamps use this timezone.
      CPA_BASE_URL: http://cli-proxy-api:8317
      CPA_MANAGEMENT_KEY: replace-with-your-management-key
      REDIS_QUEUE_ADDR: cli-proxy-api:8317
      AUTH_ENABLED: true
      LOGIN_PASSWORD: replace-with-your-login-password
    volumes:
      - ./keeper:/data
    networks:
      - cpa-network

networks:
  cpa-network:
    driver: bridge

Run docker compose up -d to start the stack and docker compose down to stop it.

CPA data is stored under ./cpa, and Keeper data is stored under ./keeper.

When CPA is already deployed, use the repository's Keeper-only Compose template:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
vim .env

For CPA running on the Docker host, start with:

CPA_BASE_URL=http://host.docker.internal:8317
CPA_MANAGEMENT_KEY=replace-with-your-management-key
AUTH_ENABLED=true
LOGIN_PASSWORD=replace-with-your-login-password

Set CPA_BASE_URL to the reachable CPA address for other network layouts. If CPA uses a non-default Redis/RESP address, also set REDIS_QUEUE_ADDR.

Run docker compose up -d to start Keeper and docker compose down to stop it.

Keeper data is stored under ./data by the provided template.

Use the same .env values as the Keeper-only Compose setup when you prefer docker run:

docker run -d \
  --name cpa-usage-keeper \
  --add-host=host.docker.internal:host-gateway \
  -p 8080:8080 \
  -v "$(pwd)/keeper:/data" \
  --env-file .env \
  ghcr.io/willxup/cpa-usage-keeper:latest

Homebrew is the recommended macOS installation method:

brew tap Willxup/cpa-usage-keeper
brew install cpa-usage-keeper

Set at least CPA_BASE_URL and CPA_MANAGEMENT_KEY, then start the service:

vim "$(brew --prefix)/etc/cpa-usage-keeper.env"
brew services start cpa-usage-keeper

Upgrade and service commands:

brew services list
brew services restart cpa-usage-keeper
brew update
brew upgrade cpa-usage-keeper

Data is stored under $(brew --prefix)/var/cpa-usage-keeper; logs are written under $(brew --prefix)/var/log/.

Download the linux_amd64 or linux_arm64 archive from Releases, then extract and run it:

mkdir -p cpa-usage-keeper
tar -xzf ./cpa-usage-keeper_*_linux_*.tar.gz -C cpa-usage-keeper --strip-components=1
cd cpa-usage-keeper
cp .env.example .env
vim .env
./cpa-usage-keeper

The Linux package includes a service template. Run these commands from the extracted package directory:

sudo cp cpa-usage-keeper.service /etc/systemd/system/cpa-usage-keeper.service
sudo sed -i "s|__CPA_USAGE_KEEPER_DIR__|$(pwd)|g" /etc/systemd/system/cpa-usage-keeper.service
sudo systemctl daemon-reload
sudo systemctl enable --now cpa-usage-keeper

sudo systemctl status cpa-usage-keeper
sudo journalctl -u cpa-usage-keeper -f
sudo systemctl restart cpa-usage-keeper

The binary supports optional startup flags:

cpa-usage-keeper --host 127.0.0.1 # Override APP_HOST for this process.
cpa-usage-keeper -v               # Print the build version and exit; --version is also supported.

Download the windows_amd64 or windows_arm64 ZIP package from Releases and extract it. In PowerShell, open the extracted package directory and run:

Copy-Item .env.example .env
notepad .env
.\cpa-usage-keeper.exe

Set at least CPA_BASE_URL and CPA_MANAGEMENT_KEY before starting. For public deployments, also set AUTH_ENABLED=true and LOGIN_PASSWORD.

Copy the example config:

cp .env.example .env

For first-time deployments, start with "Minimum required" and "Web access and reverse proxy". Most other settings can keep their defaults.

• The --host startup flag overrides APP_HOST. When neither is set, Keeper preserves its existing behavior and listens on all available network interfaces.
• For Docker/Compose, keep APP_HOST empty. To restrict access to the Docker host, publish the port as 127.0.0.1:8080:8080.
• APP_BASE_PATH must be empty or start with /; /cpa/ is normalized to /cpa.
• CPA_BASE_URL is the server-side CPA address and may use a private host or Docker service name.
• CPA_PUBLIC_URL controls browser navigation and cross-origin CPAMC frame trust. Leave it empty for same-origin /management.html, or set an explicit public CPA URL when domains, ports, or paths differ.

For cross-origin CPAMC embedding, CPA_PUBLIC_URL must be a complete http:// or https:// URL with a host. Relative paths affect navigation only.

Scheduled Auth Files quota refresh is configured from the gear button in the Auth Files inspection dialog. The setting is stored in the local SQLite database and does not require the page to stay open.

When file logging is enabled, cpa-usage-keeper-YYYY-MM-DD.log contains all emitted levels. Error, fatal, and panic entries are also copied to cpa-usage-keeper-error-YYYY-MM-DD.log, which keeps the previous 30 local calendar dates plus the current date.

Usually, HTTPS should be terminated at nginx, Caddy, or another reverse proxy. Set TLS_ENABLED=true only when the Keeper process must serve HTTPS directly, and provide TLS_CERT_FILE and TLS_KEY_FILE; relative paths are resolved against the .env file directory.

Security and data notes:

• Browser APIs redact key-like fields, but the SQLite database and its unencrypted backups contain original data.
• For public deployments, enable AUTH_ENABLED=true and terminate HTTPS at a reverse proxy.
• Login session hashes persist in SQLite until logout or AUTH_SESSION_TTL expiry.
• CPAMC uses a separate embed session: an HttpOnly cookie when available, or a per-tab header token in browser session storage as a fallback.
• Same-origin embedding works by default. For cross-origin embedding, set CPA_PUBLIC_URL to the public CPA/CPAMC origin used for frame-ancestors.
• Redis inbox messages are retained through the current day after success or for 7 days after failure.

When serving under /cpa, set APP_BASE_PATH=/cpa and keep the prefix in your reverse proxy:

location /cpa/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

When CPA and Keeper share a browser origin, CPA_PUBLIC_URL can be omitted and "Back to CPA" uses /management.html. For another domain, port, or path, set the public CPA URL:

CPA_PUBLIC_URL=https://cpa.example.com

This project is open source under the MIT License.