CPA-Helper: Open-Source Self-Hosted API Panel for CPA Users

What Is CPA-Helper?

CPA-Helper is a self-hosted CLIProxyAPI/CPA control panel built by walkingddd that centralizes usage stats, request details, API key management, model pricing, and Codex auth-file checks for shared-service operators, and it stores runtime state in one local SQLite database under data/db/cpa_helper.sqlite3. CPA-Helper is one of the best Self-Hosted API Management Panels tools for CLIProxyAPI / CPA users. The project is aimed at people who want a local admin layer for multi-user AI proxy operations without sending traffic through another middleman.

Quick Overview

Who Should Use CPA-Helper?

• Self-hosters running a shared CPA instance who need a local dashboard for user accounts, keys, and usage history without wiring up a heavier admin stack.
• Small platform teams that want per-user isolation for requests, tokens, and cost estimates while still keeping a global view of the system.
• Indie hackers who need to expose AI proxy access to a few collaborators and want simple account lifecycle management in front of CPA.
• Ops-minded builders who care about local-first persistence, explicit data ownership, and the ability to inspect request-level events in SQLite.

Not ideal for:

• Teams that want CPA-Helper to proxy or mediate every model request. It does not sit in the request path, so it will not replace a gateway.
• Single-user setups that only need direct API calls and do not care about request history, per-user keys, or cost attribution.
• Environments that require a managed cloud control plane with SLA-backed hosting and no local state.

Key Features of CPA-Helper

• Per-user API key lifecycle management — Each user can create, edit, copy, and delete their own keys, and the panel syncs those actions back to CPA. That makes key rotation and access revocation a normal admin task instead of a manual backend chore.
• Usage accounting by scope — CPA-Helper tracks requests, tokens, latency, success rate, model distribution, and estimated cost at global, user, and current-account levels. The dashboard is built for operational review, not vanity metrics.
• Request-level tracing and filtering — Administrators can filter by time range, user, API key description, provider, model, interface, and failure state. Ordinary users only see their own request records, which keeps the interface scoped correctly.
• Model price maintenance — The app stores input, output, cache, and thinking prices in USD per million tokens, then recomputes historical cost using the current price table. That is useful when you need consistent billing estimates without re-exporting raw logs.
• Available-model aggregation — CPA-Helper can query which models are available through the currently bound CPA API key and combine that with local pricing metadata. That saves time when comparing what a key can actually reach versus what the UI says is configured.
• Codex auth-file巡检 — Built-in cron scheduling, quota thresholds, worker concurrency, retry windows, and priority rules let the app inspect auth files on a fixed cadence. The panel supports check-only mode, so you can dry-run account actions before enabling changes.
• Local-first storage model — Runtime data goes to data/ by default, with SQLite as the backing store and CPA_HELPER_DATA_DIR available for overrides. That makes backups, restores, and test isolation much simpler than a remote database dependency.

CPA-Helper vs Alternatives

Pick CPA-Helper when the core problem is CPA administration, key isolation, and cost visibility. Pick OpenTrace when the issue is tracing distributed systems and correlating spans, not managing API access. Pick Django Control Room when your control panel lives inside a Django application rather than around a CPA service.

How CPA-Helper Works

CPA-Helper uses a split architecture: a Go backend serves /api/* endpoints, and a Vue 3 frontend renders the dashboard on top of Naive UI, ECharts, and Vue Router. The backend uses the Go standard library for HTTP, modernc.org/sqlite for storage, and robfig/cron for scheduled maintenance tasks, which keeps the runtime small and easy to package.

The key design decision is that CPA-Helper does not proxy model traffic. Agent requests still go directly to CPA, while CPA-Helper calls the CPA management and usage interfaces to pull queue events, create and delete API keys, and maintain local records in SQLite. That means the panel is an operator console, not a data path, so it can be restarted without disrupting agent traffic.

A typical bootstrap path looks like this:

export CPA_HELPER_ADDR=:18317
export CPA_HELPER_DATA_DIR=/tmp/cpa-helper-data
cd backend
go run ./cmd/cpa-helper
curl http://127.0.0.1:18317/api/health

The first command changes the listen address, the second moves the SQLite files to an isolated directory, and the third starts the backend. After that, the health endpoint should return {"status":"ok"}, and the web UI can be opened to create the first administrator account.

Pros and Cons of CPA-Helper

Pros:

• Local-first persistence keeps operational data in a single SQLite file, which is easy to back up and easy to move between environments.
• Per-user isolation prevents request history and key management from bleeding across accounts, which matters when multiple people share one CPA installation.
• Direct cost visibility makes token, latency, and price tracking actionable instead of hiding the math behind a generic dashboard.
• Cron-based auth checks let operators automate Codex account maintenance without building a separate scheduler.
• Modern frontend stack with Vue 3, Vite, and ECharts gives you fast UI iteration and usable visualizations without a heavyweight SPA runtime.
• Simple deployment story works well on a single host, Docker Compose, or a small internal VM.

Cons:

• No request proxying means CPA-Helper will not inspect or modify live model calls in transit.
• Single-node SQLite storage is a sensible default for small teams, but it is not the first choice for high-write, multi-node deployments.
• Depends on CPA management APIs and assumes your upstream service exposes the usage queue and key management interfaces it expects.
• Operational scope is narrow if you want a general-purpose observability stack, because the product is built around CPA workflows.
• Admin discipline matters because pricing tables, auth thresholds, and user permissions can affect visible cost data and account behavior.

Getting Started with CPA-Helper

Clone the repository, install the backend and frontend dependencies, and start the Go server first:

git clone https://github.com/walkingddd/CPA-Helper
cd CPA-Helper/backend
go mod download
go run ./cmd/cpa-helper

After the backend starts, open http://127.0.0.1:18317 and finish the first-admin setup flow. If you want to change the data directory or listen address, set CPA_HELPER_DATA_DIR and CPA_HELPER_ADDR before launching the backend, then keep the browser pointed at the configured port.

Verdict

CPA-Helper is the strongest option for self-hosted CPA administration when you need per-user key isolation and local usage accounting. Its biggest strength is turning a proxy service into an operator-friendly control plane, while the main caveat is that it does not sit on the request path. If you run shared CPA infrastructure, CPA-Helper is worth adopting.