CPA Manager Plus: A Self-Hosted Observability Layer for CPA / CLIProxyAPI

What CPA Manager Plus Actually Solves

CPA / CLIProxyAPI is a gateway that routes model traffic, but its official management center does not keep a persistent record of what went through it. CPA Manager Plus closes that gap by storing request history, cost breakdowns, and account health signals in local SQLite files. The README frames it as a panel that answers three questions: why requests fail, where cost goes, and whether accounts and quotas are healthy. The target user is an operator who runs CPA in production and needs to inspect failures without exposing raw error bodies, or who manages multiple Codex or xAI accounts with quota windows and reset evidence. It is not a replacement proxy. It observes and manages traffic through CPA, but it does not forward model traffic itself.

Two Deployment Modes and What Each Assumes

The project offers a Lightweight Panel that replaces the official UI directly on CPA's port 8317, and a Full Mode that runs as a separate Manager Server on port 18317. The Lightweight Panel is for people who just want a different interface without adding a database or another service. Full Mode is for those who need persistent observability and long-running operations like quota cooldowns and account action queues. The README's comparison table is explicit: Lightweight Panel is best for replacing only the UI, Full Mode for request history and automation. This split matters because it changes the operational burden. Full Mode means a second container, a second port, and a separate data volume. The installer script supports both, but you should know which mode you want before running it.

How Request History and Failure Diagnosis Work

Requests are pulled from the CPA usage queue and persisted in local SQLite. The panel then lets you search by account, client API key, or realtime request views. For failures, it shows status, latency, token usage, cache state, and redacted evidence. The redaction is a deliberate design choice: the README says it avoids exposing raw failure bodies. That is a useful constraint for security, but it also means you cannot see the full error payload from within the panel. If you need the exact body for debugging, you would have to go to the CPA logs directly. The request history can be exported and imported as JSONL, which gives you a portable audit trail. The documentation does not specify how long history is retained or whether there is a pruning mechanism, so that is something to verify.

Cost Analytics: Price Sync and Local Overrides

Cost breakdowns are computed per model, provider, account, credential, API key, project, channel, and time range. The panel tracks input, output, reasoning, cache, service tier, and long-context pricing semantics. Price data is synced from models.dev first, with LiteLLM and OpenRouter as fallbacks. You can also set local overrides for aliases or internal models. That fallback chain is practical because models.dev may not cover every provider or custom model. The local override feature is essential for internal models that have no public price listing. However, the README does not say how often price sync runs or what happens when a price is missing. If you rely on accurate cost numbers for billing, you should test the sync behavior with your specific provider before trusting the dashboard.

Account Health, Quota Cooldowns, and Automation

For Codex and xAI accounts, the panel can inspect quota windows, reset evidence, credential state, workspace state, and provider-specific health signals. It can apply controlled quota cooldowns and route credential failures into an account action queue for review and recovery. This is the automation part of the project. It is not a full replacement for manual account management, but it gives a structured way to handle quota exhaustion. The README says the inspection can run locally or on a Manager Server schedule. That scheduling is what makes it useful for long-running operations. The action queue is a review step, not a blind auto-recovery, which is a sensible safety measure. Still, the documentation does not detail how cooldowns are calculated or what triggers a credential failure. You would need to read the full docs or test it with a real account.

Getting It Running: Commands and Configuration

The quick start offers a guided installer. You download and run a shell script: curl -fsSLO https://raw.githubusercontent.com/seakee/CPA-Manager-Plus/main/bin/install-cpamp.sh, then bash install-cpamp.sh. There is a dry-run flag: CPAMP_DRY_RUN=1 bash install-cpamp.sh, which previews what the installer would do. For a Docker Compose setup, the README shows two services: cli-proxy-api on port 8317 and cpa-manager-plus on port 18317, with separate volumes cpa-data and cpa-manager-plus-data. The full stack runs alongside CPA, not inside it. The installer documentation covers upgrade, repair, and admin-key recovery, which suggests that key management is a real operational concern. The README also notes that backups should include SQLite files together with data.key to preserve encrypted CPA Management Keys. That is a specific, concrete backup requirement that is easy to miss.

Limitations and When It Is the Wrong Tool

The most obvious limitation is that CPA Manager Plus is not a proxy. If you expect it to route traffic or replace CPA, it will not. Another limitation is the redacted failure evidence. It protects sensitive data but can frustrate debugging. The Lightweight Panel mode has no database, so it cannot provide persistent history or automation. If you choose that mode, you lose the core observability features. The README also states that the live demo uses fictional data only and cannot connect to a real CPA instance, so you cannot evaluate real behavior without deploying it. The project relies on the CPA usage queue being accessible; if your CPA version changes its queue format, the panel may break. Finally, the project is self-hosted and stores everything locally, which is a feature for privacy but a burden for teams that want centralized logging or multi-node aggregation. There is no mention of a remote database option, so all data lives on the Manager Server's filesystem.

Alternatives and a Maintenance Reality Check

The official alternative is the CLI Proxy API Management Center, which the README itself lists as the upstream UI maintained by the CPA project. The difference is that the official center is part of CPA and does not require a separate service or database. It gives you management but not persistent request history or automation. If you only need to change provider configs and view live status, the official center is simpler. There are also generic AI gateway observability tools like Grafana or Prometheus, but they would require you to export CPA metrics and build your own dashboards. CPA Manager Plus is purpose-built for CPA, so it has account-specific health signals like quota windows and reset evidence that generic tools lack. On maintenance, the project is under active development with releases every few days in the recent history, which suggests a fast-moving codebase. That means you should expect frequent updates. The MIT license is permissive, but the documentation is still the primary source for upgrade paths. The installer covers upgrade and repair, but you should test those paths in a staging environment before relying on them in production.

Editorial conclusion

Adopt CPA Manager Plus if you run CPA / CLIProxyAPI and need persistent request history, cost analytics, and account quota automation without sending data to a third party. Skip it if you only need the official management UI or if your team cannot tolerate a second service on port 18317. Before deploying, verify that your CPA version's usage queue exports match what the panel expects, and test the backup procedure for SQLite files and data.key in a staging environment, because losing data.key could compromise encrypted management keys.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes