# CPA Usage Keeper: a SQLite-backed usage dashboard for CLIProxyAPI

> CPA Usage Keeper is a standalone Go service that polls a CLIProxyAPI instance, stores usage in SQLite and serves a dashboard. It fits if you already run CPA and want history that outlives the proxy process.

**Willxup/cpa-usage-keeper** — Standalone CliProxyAPI usage tracker with SQLite persistence and built-in dashboard.

- Repository: https://github.com/Willxup/cpa-usage-keeper
- Stars: 1,213 · Forks: 159
- Language: Go
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/willxup-cpa-usage-keeper

## The gap CPA Usage Keeper fills next to CLIProxyAPI

CLIProxyAPI (CPA) is the upstream proxy; Keeper is a separate process that reads from it. The README describes Keeper as a standalone persistence and analytics dashboard for 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. That split is the whole point. The proxy forwards requests; Keeper keeps the record.

The audience is narrow and specific. You need a running CPA instance, a management key, and a reason to look at history rather than a live counter. Multi-tenant operators who hand out CPA API Keys and want per-key cost attribution are the obvious users. So are people running CPA for a small team who want to know which model or provider is eating the budget. If you never deployed CPA, nothing here applies to you. The README's own quick-start table lists four deployment shapes, and every one of them assumes CPA already exists or is being stood up alongside Keeper.

## How the poller, SQLite store and dashboard fit together

The repository layout is the clearest description of the architecture. cmd/server is the entry point; internal/poller handles CPA usage and metadata synchronization; internal/repository holds SQLite persistence and aggregations; internal/service covers usage, pricing and identity; internal/quota does provider quota refresh and inspection; internal/ranking handles community ranking aggregation and sync; internal/api exposes HTTP routes and handlers; internal/auth handles sessions and access control.

So the data flow is one-directional: Keeper calls CPA's management endpoints using CPA_BASE_URL and CPA_MANAGEMENT_KEY, the poller writes what it finds into SQLite, and the dashboard reads aggregates back out. Keeper does not sit in the request path, which is why it can be restarted without affecting proxied traffic. Persistence is SQLite through gorm.io/driver/sqlite and github.com/mattn/go-sqlite3, and the Dockerfile sets CGO_ENABLED=1, so the build depends on cgo. The image also declares VOLUME ["/data"], which is where the database lives.

Two constraints come straight from the README. CPA usage statistics must be enabled with usage-statistics-enabled: true, and when multiple usage collectors share one CPA instance, they must all use subscription mode or collection may stop or become incomplete. That second one is the kind of failure that shows up as missing rows rather than an error message.

## Installing CPA Usage Keeper with Docker Compose and logging in

The README recommends Docker Compose and splits it into a full stack (CPA plus Keeper) and a Keeper-only stack for an existing CPA. Both target linux/amd64 and linux/arm64. The Keeper-only path is the one most readers will take, and the environment file is the first thing to edit.

The minimum required settings are the CPA URL and the management key. The .env.example gives this pair with its own comments about which is required:

```bash
cp .env.example .env
# CPA_BASE_URL: URL used by the Keeper server to call CPA
# CPA_MANAGEMENT_KEY: CPA management key used to access management endpoints
```

The example file ships CPA_BASE_URL=http://127.0.0.1:8317 and a placeholder management key, and notes that inside Docker Compose the URL is usually http://cli-proxy-api:8317. Replace the placeholder before starting anything.

Login protection is on by default. The README is explicit: configure LOGIN_PASSWORD before starting Keeper, or set AUTH_ENABLED=false only when access is reliably isolated by the deployment environment. The container listens on APP_PORT (default 8080) and exposes a health endpoint at /healthz, which the Dockerfile's HEALTHCHECK polls every 30 seconds.

For local development rather than containers, the README lists Go 1.26+, Node.js 24+, npm and a running CPA instance, then two terminals:

```bash
go run ./cmd/server/main.go
```

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

The frontend comes up on http://127.0.0.1:5173 and proxies /api to http://127.0.0.1:8080, overridable with VITE_API_PROXY_TARGET. Other documented install paths are Homebrew for macOS, plain Linux and Windows binaries, and systemd. The README does not document rollback or downgrade steps between releases.

## Where CPA Usage Keeper is the wrong tool

Keeper cannot tell you anything CPA does not report. If usage-statistics-enabled is false, there is nothing to poll. If several collectors point at the same CPA instance and they are not all in subscription mode, the README warns that collection may stop or become incomplete, and Keeper has no way to detect that on its own. The dashboard will simply be missing data.

The storage model is a single SQLite file. There is no mention of a Postgres or MySQL backend in go.mod or the repository layout, so an operator who needs a shared relational database behind the dashboard is out of scope. Keeper is also not a proxy, not a rate limiter and not a gateway: it does not sit between clients and providers, so it cannot block a request or enforce a quota. Quota refresh and inspection are described as monitoring features, not enforcement.

There is a security trade-off worth naming. Keeper needs the CPA management key to pull configuration and credential data, and it can inspect Auth Files and AI Providers. Anyone who reaches the dashboard is close to that material, which is why login protection is enabled by default and why AUTH_ENABLED=false is framed as a deployment-isolation decision rather than a convenience setting. A read-only view scoped to an individual CPA API Key exists, but the full dashboard is not a low-privilege surface.

## Keeper compared with watching CPA's own management page

The alternative most operators already have is CPA's management interface, which is where Keeper sends you when you click the Back to CPA link (CPA_PUBLIC_URL, or the current origin plus /management.html when it is empty). That page is part of CPA and reflects CPA's own state during the session you are looking at. Keeper's difference is persistence and aggregation: it writes usage into SQLite, keeps optional scheduled backups, and answers questions about trends, cost composition, hourly heatmaps and latency diagnostics that a live management page is not built to answer.

The second alternative is doing nothing and reading logs. That works until you want per-API-Key cost or a success-rate series over a time range, at which point you are writing your own collector against the same management endpoints Keeper already polls. The trade-off is operational: Keeper adds a second service, a database file to back up, and a management key to distribute. If your only question is whether CPA is up right now, CPA's own page answers it and Keeper is extra surface area.

## Maintenance, licence and what each release costs you

The repository is not archived and the last push was on 2026-08-27. The release cadence visible in the repository is tight: v1.14.7 on 2026-08-23, v1.14.8 on 2026-08-24, v1.14.9 on 2026-08-27. Three patch releases in five days suggests active bug-fixing, and it also means upgrade cost is real: if you pin a tag and stop watching, you accumulate small fixes rather than one large jump.

Upgrades are cheap in mechanism. The Docker image carries the version through -X cpa-usage-keeper/internal/version.Version, the binary is the only artifact, and the database is a file on the /data volume. The Makefile defines the checks the project itself runs: go test ./cmd/... ./internal/..., npm run test, lint, typecheck and build under verify-frontend, and docker build -t cpa-usage-keeper:ci . under verify-docker. Running make verify before deploying a newer tag is the closest thing to a supported pre-flight check.

The licence is MIT, stated in the repository and in the LICENSE file at the top level. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained, and it comes with no warranty. That is a description of the licence text, not legal advice; if you redistribute Keeper inside a product, have your own counsel read the LICENSE file rather than this paragraph. One practical note: the project bundles a capacity benchmark suite under internal/benchmark with its own report, so check that directory's terms if you plan to reuse the numbers.

## Conclusion

Adopt CPA Usage Keeper if you already run CLIProxyAPI and want usage history in your own SQLite file rather than only what CPA keeps in memory. Skip it if you have no CPA instance, or if you cannot turn on usage statistics or share the management key, because the poller has no other data source. Before rolling it out, confirm that usage-statistics-enabled is true in CPA, set LOGIN_PASSWORD rather than disabling authentication, and check the Capacity Benchmark Report for the ingestion and memory figures your host has to absorb.

## FAQ

### What is CPA Usage Keeper and which proxy does it work with?

It is a standalone persistence and analytics dashboard for CLIProxyAPI (CPA) that stores usage in SQLite and serves views for usage, cost, request health, quotas and model or API statistics. It reads from CPA rather than proxying traffic itself, so a running CPA instance is a prerequisite.

### How do I install CPA Usage Keeper?

The README recommends Docker Compose, with a full stack when CPA and Keeper are deployed together and a Keeper-only stack when CPA already exists; both cover linux/amd64 and linux/arm64. Homebrew, Linux and Windows binaries, and systemd are also listed as deployment options.

### Why is my CPA Usage Keeper dashboard missing usage data?

Check that CPA has usage statistics enabled with usage-statistics-enabled: true, since Keeper has no other data source. The README also warns that when multiple usage collectors share one CPA instance, they must all use subscription mode or collection may stop or become incomplete.

### Does CPA Usage Keeper require a login?

Login protection is enabled by default. The README says to configure LOGIN_PASSWORD before starting Keeper, and to set AUTH_ENABLED=false only when access is reliably isolated by the deployment environment.

### What licence does CPA Usage Keeper use?

The repository and the LICENSE file at the top level state MIT. That permits use, modification and redistribution provided the copyright and permission notices are retained, and it carries no warranty.

## Sources

- [Official README](https://github.com/Willxup/cpa-usage-keeper#readme)
- [Project repository](https://github.com/Willxup/cpa-usage-keeper)
- [Release notes](https://github.com/Willxup/cpa-usage-keeper/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/willxup-cpa-usage-keeper