CPA Manager Plus: a self-hosted observability panel for CPA / CLIProxyAPI gateways

The question CPAMP is built to answer

A CLIProxyAPI deployment handles traffic, but it does not keep a long-lived record of what went through it. When a request fails at 3am, or when a monthly bill lands higher than expected, the gateway itself is not the place you look. CPA Manager Plus exists to hold that record: "A self-hosted CPA / CLIProxyAPI management panel and AI gateway observability dashboard for requests, usage, cost, quota, failures, and account health." That is the README's own framing, and it sets the audience precisely. This is for people already operating CPA, not for people choosing a proxy.

The README organises the product around three questions: why requests are failing, where the cost is going, and whether accounts and quotas are healthy. Each maps to a stored artefact rather than a live view. Failures become rows in persistent request history with status codes, affected models and accounts, and redacted evidence. Cost becomes a breakdown by model, provider, account, API key, project, channel and time range. Account health becomes credential state, quota windows and reset evidence for Codex and xAI accounts.

The scope is deliberately narrow. CPAMP manages and observes traffic through CPA / CLIProxyAPI. It is not a replacement proxy and does not forward model traffic by itself. If you want a gateway, this is not one.

How the Manager Server, SQLite store and CPA usage queue fit together

The architecture the repository describes has three parts. CPA / CLIProxyAPI sits in front of model traffic. A Manager Server, built from the Go workspace under apps/manager-server, runs the panel and the background work. A local SQLite database holds request history, Manager configuration, automation state and model prices.

The data path starts at the CPA usage queue. The README states that requests from that queue are persisted into local SQLite, which is what makes the account, client API key and realtime request views searchable after the fact. Failure bodies are not stored raw; the panel shows redacted failure evidence instead. That is a deliberate trade-off. You get enough context to diagnose a failure without keeping full request bodies on disk, but you also cannot replay an exact payload from the history view.

Pricing is a separate pipeline. Model prices sync from models.dev first, with LiteLLM and OpenRouter as fallbacks, plus local overrides for aliases or internal models. Cost figures are therefore estimates built from those price sources, not invoices. Long-context, cache, reasoning and service-tier pricing semantics are tracked separately, which matters because a single blended per-token rate would misprice most modern requests.

The applications live in a TypeScript npm workspace: apps/web for the panel and apps/docs for the documentation site. The root package.json exposes dev, build, test, lint and type-check scripts, and a manager-server:test script that runs go test ./... inside apps/manager-server. Nothing here is a hosted service. There is no account registration and no telemetry SDK.

Installing CPA Manager Plus and reading your first request history

There are two supported paths. The installer script handles a guided full-stack or CPAMP-only deployment, and the README gives this command to fetch and run it:

curl -fsSLO https://raw.githubusercontent.com/seakee/CPA-Manager-Plus/main/bin/install-cpamp.sh
bash install-cpamp.sh

If you want to see what the script would do before it touches anything, the README documents a dry-run mode through an environment variable:

CPAMP_DRY_RUN=1 bash install-cpamp.sh

The second path is Docker Compose, running CPA and CPAMP as two services. The README shows the CPA service on port 8317 and the Manager Server on port 18317, each with its own named volume:

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    restart: unless-stopped
    ports:
      - '8317:8317'
    volumes:
      - cpa-data:/app/data

  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    restart: unless-stopped
    ports:
      - '18317:18317'
    volumes:
      - cpa-manager-plus-data:/data

After the stack is up, the panel entry point depends on the mode. In Full Mode you open the Manager Server at :18317/management.html. In the lightweight mode you open CPA's own :8317/management.html, because the lightweight panel replaces the upstream UI in place rather than adding a service. The first thing worth doing once you are in is to let traffic flow and then open the request history view, where account, client API key and realtime views are searchable. If nothing appears, the usage queue is the thing to check, since that is the source the panel persists from.

The README also points at a Live Demo, and it is worth being blunt about what that is: it uses fictional data only, is not a deployment or runtime mode, and cannot connect to, manage or monitor a real CPA instance. It is a preview of the interface, nothing more.

Where CPAMP is the wrong tool

The clearest limitation is stated by the project itself: CPAMP is not a replacement proxy and does not forward model traffic. Deploy it without a CPA / CLIProxyAPI instance in front and it has nothing to observe. That rules it out for anyone who wants a single self-contained gateway with a dashboard attached.

The second constraint is storage. Request history, configuration, automation state and model prices all live in local files, and the README notes that the SQLite files must be backed up together with data.key to preserve encrypted CPA Management Keys. Restoring the database without that key leaves you with encrypted values you cannot read. This is a real operational obligation, and it is the kind of thing that is easy to skip until the day it matters.

Third, cost numbers are estimates assembled from external price sources plus local overrides. If you need billing-grade figures, the sync from models.dev with LiteLLM and OpenRouter fallbacks is a convenience, not an accounting system. Aliases and internal models need manual overrides or they will be priced wrong.

Finally, the health inspection and quota automation are scoped to Codex and xAI accounts, as the README states. Provider-specific health signals are described as available "when available", which is an honest way of saying coverage varies. If your estate is mostly other providers, the account automation half of the product does less for you.

CPAMP versus the official CLI Proxy API Management Center

The README frames the choice as three options rather than two. The official CLI Proxy API Management Center, maintained by the CPA project itself, is for people who want to keep the upstream UI and take updates from upstream. The CPAMP Lightweight Panel is for people who want to replace only the interface, without adding another service or a database, and it is served from the same CPA :8317/management.html entry point. CPAMP Full Mode is for people who need request history, cost analytics, inspection and automation, and it runs as a separate Manager Server on :18317.

The difference in approach is not cosmetic. The official panel and the lightweight panel are both views onto a running CPA instance; they add no persistence layer. Full Mode adds a store. That is why it needs its own container, its own volume, its own backup discipline and its own port. The trade is straightforward: you gain history and analytics, and you take on a second service to operate.

There is a fourth option the README does not push but does document: run both, with the full stack alongside CPA. Nothing in the described deployment prevents that, since the two services use separate volumes.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-28, which is recent enough that the project is being worked on. The release history supports that: v1.12.6 landed on 2026-08-28, v1.12.5 on 2026-08-26 and v1.12.4 on 2026-08-25. Three releases in four days is a fast cadence, and fast cadences cut both ways. You get fixes quickly, and you also carry upgrade work more often than you would with a slower project.

The installer documentation covers upgrade, repair and admin-key recovery behaviour, so the upgrade path is at least documented rather than improvised. What the README does not document is rollback. If a version regresses, there is no stated procedure for returning to the previous one, which makes the SQLite backup the thing standing between you and a bad upgrade. Back up the database and data.key before you move versions.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is permissive and low-friction for internal deployment. It is not legal advice, and if you redistribute CPAMP as part of a product you should read the LICENSE file in the repository rather than this summary.

Running costs are mostly the second container plus whatever storage the request history consumes over time. Since history accumulates in SQLite with no described retention or pruning policy, plan for the database to grow and decide early how you will archive or export it. The README does note JSONL export and import for request history, which is the escape hatch if the database gets unwieldy.

Editorial conclusion

Adopt CPAMP Full Mode if you already run CPA / CLIProxyAPI and need request history, cost breakdowns or scheduled Codex and xAI credential checks that the upstream panel does not keep. Do not adopt it as a proxy: the README states it does not forward model traffic, so it is the wrong tool if you have no CPA instance behind it, and the Live Demo cannot connect to a real one. Before deploying, verify which mode you are installing, since the lightweight panel replaces the UI on :8317 while Full Mode runs a separate Manager Server on :18317, and confirm that you can back up the SQLite files together with data.key.

Frequently asked questions

Official sources

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