Willxup/cpa-usage-keeper

CPA Usage Keeper – What It Does

Purpose – CPA Usage Keeper is a monitoring dashboard for CLIProxyAPI (CPA), a command‑line proxy that talks to AI models (OpenAI, Anthropic, etc.). It records every request that CPA forwards, stores the data in a local SQLite database, and presents the information in a web UI so you can see how much you’re spending, how fast the models respond, and whether your API‑key quotas are being exhausted.

Key features

• History persistence – CPA request logs are written to SQLite and backed up automatically.
• Cost analysis – Break down usage by model, provider, and API key; see estimated monetary cost and cache‑hit ratios.
• Request diagnostics – View individual request details, export them, and inspect metrics such as success rate, time‑to‑first‑token (TTFT) and total latency.
• Quota tracking – Monitor remaining quota for each credential, refresh quota information, and view historical quota changes (e.g., Codex quota).
• Read‑only sharing – Generate a scoped, read‑only view that can be shared with teammates.
• Optional community ranking – Pull community‑generated rankings of models/credentials.

How it’s packaged

• Docker image (GHCR) with official Docker‑Compose templates for a full CPA + Keeper stack or a Keeper‑only stack.
• Homebrew formula for macOS.
• Pre‑built Linux and Windows binaries (with systemd service template for Linux).
• All deployments include a login password (auth enabled by default).

Typical workflow

1. Enable usage statistics in your CPA configuration (observability.usage.usage-statistics-enabled: true).
2. Deploy Keeper (Docker‑Compose is the recommended method). Provide the CPA base URL, the CPA management key, and a Keeper login password via .env.
3. Open http://<host>:8080 and sign in.
4. The dashboard shows an Overview (total requests, cost), Realtime diagnostics (live request rate), Usage analysis (cost per model/API‑key), Request events (list of individual calls), and Quota history.

Technical overview

• Backend: Go 1.26+; HTTP API built with standard libraries, SQLite for persistence, background poller that syncs CPA usage and quota data.
• Frontend: React + TypeScript, served by the Go server.
• Extensible via environment variables (APP_HOST, APP_PORT, APP_BASE_PATH, TRUSTED_PROXY_CIDRS, etc.).
• Optional Redis queue support for high‑throughput setups.

Who might use it

• Teams running their own self‑hosted CPA instance who need visibility into model spend and quota health.
• Developers who want a quick, self‑contained UI to audit AI‑API usage without building custom logging.
• Ops teams that prefer Docker or Homebrew deployment and want a lightweight, password‑protected dashboard.

Getting started – See the README’s “Quick Start” section for Docker‑Compose commands, Homebrew install, or binary download. The project also provides a make verify target for running unit tests and linting.

---

All details are taken directly from the repository’s README; no additional features are inferred.