cpa-usage-keeper

English ｜ 简体中文

CPA Usage Keeper

Every flow leaves a trace.

Keep usage history for CLIProxyAPI (CPA), understand model costs, and track request performance and credential quotas. CPA Usage Keeper brings overviews, realtime diagnostics, request details, and quota history into one independently deployed dashboard.

Deploy Keeper | Deploy CPA + Keeper | Configuration

Screenshots

Overview	Realtime Diagnostics
Usage Analysis	Request Events
Credentials and Quotas	Quota History

Features

• Keep your history: persist CPA usage in SQLite with scheduled backups.
• Understand costs: analyze usage, caching, and estimated costs by model, API Key, and provider.
• Investigate requests: inspect and export request details, and explore success rates, time to first token (TTFT), and total latency.
• Track quotas: monitor credential health and remaining quotas, refresh quotas, edit priorities, and explore Codex quota history.
• Share scoped access: provide a read-only usage view for an individual CPA API Key.

CPA plugin embedding in CPAMC is also available. Deploy with Docker Compose, Homebrew, or binaries; login protection is enabled by default.

Sponsors and Special Thanks

• 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.

Quick Start

Keeper supports CPA v8.0.12+. Enable usage statistics by setting observability.usage.usage-statistics-enabled to true.
When multiple collectors share one CPA instance, all must use subscription mode to avoid interrupted collection or missing data.

Docker Compose is recommended; no Go, Node.js, or source build is needed. Choose a deployment below. For an existing CPA, have its address and management key ready, and choose a Keeper login password.

Login protection is enabled by default. Configure LOGIN_PASSWORD before starting Keeper, or explicitly set AUTH_ENABLED=false only when access is reliably isolated by the deployment environment.

Benchmark

Production-style linux/amd64 capacity measurements for sustained ingestion, Dashboard latency, CPU utilization, and Keeper cgroup peak memory are available in the Capacity Benchmark Report.

Developer Reference

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/benchmark/      Capacity suite, reports, manifests, and legacy microbenchmarks
deploy/                  Deployment templates
web/                     React + TypeScript frontend

cp .env.example .env
vim .env

go run ./cmd/server/main.go

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

make verify

Deployment

After startup, open http://your-server-address:8080 (http://127.0.0.1:8080 for a local deployment) and sign in with your Keeper login password. Adjust the URL if you configure a different port, HTTPS, or a base path.

Docker Compose (Recommended)

CPA + Keeper

1. Prepare the configuration files

First, download the configuration example from the official CPA repository into ./cpa/config.yaml in your deployment directory:

mkdir -p cpa/auths cpa/logs keeper
curl -fL https://raw.githubusercontent.com/router-for-me/CLIProxyAPI/main/config.example.yaml \
  -o cpa/config.yaml

In the same directory, download the CPA + Keeper Compose template:

curl -fL https://raw.githubusercontent.com/Willxup/cpa-usage-keeper/main/deploy/docker-compose.full.example.yml \
  -o docker-compose.yml

Use this download command for a new deployment only; edit an existing configuration directly to avoid overwriting it.

2. Configure CPA and Keeper

Edit the existing settings in cpa/config.yaml as listed below, preserving YAML nesting and indentation. Dots in the table denote nested paths, not literal YAML keys to add:

Keep server.host as an empty string, server.port as 8317, and oauth.auth-dir as "~/.cli-proxy-api" to match the container network and volume mounts in the template.

Edit the downloaded docker-compose.yml and fill in two values under Keeper’s environment:

• CPA_MANAGEMENT_KEY: use the same original management key configured in CPA.
• LOGIN_PASSWORD: replace the empty string "" with your own Keeper login password.

For optional environment-file setup, see advanced configuration.

3. Start and open Keeper

docker compose up -d

Open http://your-server-address:8080 and sign in with your Keeper login password.

For a new deployment, add model credentials in CPA and make a model request to generate usage records.

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

Keeper Only

1. Prepare the configuration files

When CPA is already deployed, download the Keeper-only Compose template and environment configuration into a new deployment directory:

curl -fL https://raw.githubusercontent.com/Willxup/cpa-usage-keeper/main/deploy/docker-compose.example.yml \
  -o docker-compose.yml
curl -fL https://raw.githubusercontent.com/Willxup/cpa-usage-keeper/main/.env.example -o .env
vim .env

For an existing deployment, edit the existing files directly to avoid overwriting your configuration.

2. Set the connection details and login password

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=

Set a private LOGIN_PASSWORD before starting the container.

Whether CPA runs on the Docker host or another machine, it must allow remote management and listen on an address reachable from the Keeper container; a listener bound only to 127.0.0.1 is not reachable. Set management.allow-remote: true and check server.host.

For other network layouts, set CPA_BASE_URL to a CPA address reachable from the container. Set REDIS_QUEUE_ADDR only when the Redis/RESP address differs from the automatically derived address.

3. Start and open Keeper

docker compose up -d

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

Access And Routine Management

For either Compose setup, sign in at http://your-server-address:8080 with your Keeper password and run docker compose down to stop it. View logs from the deployment directory:

docker compose logs --tail=100 -f cpa-usage-keeper

To update Keeper, keep your configuration and data directories and run:

docker compose pull cpa-usage-keeper
docker compose up -d cpa-usage-keeper

No Data After Startup?

• Check that CPA usage statistics are enabled: observability.usage.usage-statistics-enabled must be true.
• Ensure Keeper can reach CPA_BASE_URL and that CPA_MANAGEMENT_KEY matches the CPA management key.
• Check that CPA has received new model requests. If data is still missing, use the log command above to look for connection or authentication errors.

Docker (CPA Already Runs On The Host)

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

macOS Homebrew

Homebrew is the recommended macOS installation method:

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

Set CPA_BASE_URL, CPA_MANAGEMENT_KEY, and a private LOGIN_PASSWORD, 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/.

Linux Binary

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

systemd

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

Command-Line Options

The binary supports optional startup flags:

cpa-usage-keeper --env /path/to/keeper.env # Use a specific environment file.
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.

Windows Binary

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 CPA_BASE_URL, CPA_MANAGEMENT_KEY, and a private LOGIN_PASSWORD before starting.

Configuration

Edit your existing .env or Compose environment, depending on the deployment method; do not overwrite existing settings with a fresh template.

For a first deployment, set the CPA address, CPA management key, and Keeper login password. Most other settings can keep their defaults. Read the relevant sections when you need a domain, HTTPS, or a base path.

Minimum Required

Web Access And Reverse Proxy

For Docker/Compose, keep APP_HOST empty; publish 127.0.0.1:8080:8080 for host-only access. Set a browser-accessible CPA_PUBLIC_URL when CPA and Keeper use different domains, ports, or paths. See advanced configuration for details and the reverse-proxy example below.

Login Protection

Timezone And Request Behavior

Storage, Logs, And Backups

Raw requests are archived after 90 days and retained indefinitely by default; set USAGE_RAW_RETENTION_DAYS>=90 to remove expired archives. Deleted records cannot support historical recalculation, and deletion may not immediately shrink the database file. See storage and log details.

Rolling Back A Failed v1-to-v2 Upgrade

Keeper backs up the database before migration. If it fails, follow the failed migration rollback guide. Do not open a partially migrated database with v1.

Optional Features And Advanced Configuration

• OIDC administrator login: disabled by default; keep password login configured. Without subject restrictions, all users authenticated for the client become administrators; restrict application access at the provider.
• Quota refresh: configure schedules from the gear button in the Credentials inspection dialog; the page need not stay open after saving. The guide covers concurrency and debugging settings.
• Redis queue: separate addresses, TLS, and polling settings; defaults usually suffice.
• Built-in HTTPS: for Keeper to serve HTTPS directly; usually, use nginx, Caddy, or another reverse proxy instead.

Security Notes

• Browser APIs redact key-like fields, but the SQLite database and its unencrypted backups contain original data.
• Authentication is enabled by default. If it is explicitly disabled, restrict Keeper access at the deployment boundary; terminate public HTTPS at a reverse proxy.

Nginx Reverse Proxy

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;
}

Local Nginx needs no extra proxy trust settings. For containers, remote proxies, or CDNs, configure only the actual proxy networks in TRUSTED_PROXY_CIDRS; never trust all sources.

Request Events uses a streaming SSE response with a heartbeat roughly every 15 seconds. Ensure every proxy/CDN in the path forwards batches without buffering and uses a read/idle timeout comfortably above the heartbeat interval (for example, 60 seconds). Keeper sends X-Accel-Buffering: no, but proxy or CDN configuration may override it. Verify the first snapshot and subsequent updates arrive without waiting for the connection to close.

License

This project is open source under the MIT License.

Star History