CPA‑Helper – Local admin panel for CLIProxyAPI

What it is – CPA‑Helper is a self‑hosted web dashboard that lets multiple users manage their CLIProxyAPI (CPA) accounts in one place. It records usage, shows cost estimates, lets admins create or disable user accounts, and provides per‑user API‑key management, model‑price configuration, and health‑checks for Codex auth files.

---

Core capabilities

Feature	What you can do
Usage analytics & cost estimation	See request counts, token usage, latency, success rate and an estimated USD cost – globally, per‑user, or per‑API‑key.
Request tracing	Filter request logs by time, user, model, endpoint, key description, or failure state.
User & role management	Admins can create, disable, rename users and assign “admin” or “regular” roles.
Balance & key pausing	Set monthly and lifetime USD balances per user; when a balance is exhausted the user’s CPA keys are automatically paused.
API‑key lifecycle	Users can create, edit, copy, delete keys and sync them to the underlying CPA service. Each key can be tested with a live request from the UI.
Model pricing catalog	Store per‑million‑token prices (input, output, cache) or fixed per‑request prices for image models; prices are used to compute costs and to charge balances.
Card‑shop index	A read‑only browser for public card‑shop product snapshots – useful for reference, not for transactions.
Available‑model view	Query the models that the bound CPA keys can reach and overlay the local price data.
Codex auth‑file inspection	Schedule cron jobs that scan Codex auth files, enforce quota thresholds, and adjust account priorities.
Local‑first storage	All data lives in an SQLite file under data/ (or a custom directory via CPA_HELPER_DATA_DIR).
Modern UI	Vue 3 + Naive UI with light/dark/system themes, charts (ECharts) and icons.

---

Architecture at a glance

• Backend – Go (standard library HTTP server) + SQLite (via modernc.org/sqlite). Handles API routes under /api/*, runs migrations with embedded Goose, and optionally polls the CPA usage queue.
• Frontend – Vue 3 + Vite + TypeScript, built with Naive UI, ECharts and lucide‑vue‑next.
• Data – SQLite database data/db/cpa_helper.sqlite3; the whole data/ folder is ignored by Git.
• Integration points – Calls only CPA management‑style endpoints (usage queue, key creation/deletion, credential queries). It never proxies actual model requests; those go directly from agents to CPA.

---

Getting started (quick‑start)

1. Docker‑Compose (recommended)

services:
  cpa-helper:
    image: walkingd/cpa-helper:latest
    container_name: cpa-helper
    restart: always
    network_mode: host   # exposes http://127.0.0.1:18317
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/app/data

docker compose pull
docker compose up -d   # UI available at http://127.0.0.1:18317

The first visit walks you through creating the initial admin account.

2. Run from source

1. Backend

   cd backend
   go mod download
   go run ./cmd/cpa-helper   # runs migrations then serves on :18317
   # health check
   curl http://127.0.0.1:18317/api/health
   

2. Frontend (dev mode)

   cd frontend
   npm install
   npm run dev   # defaults to http://127.0.0.1:5173
   

   If the backend already occupies 18317, set CPA_HELPER_PROXY_TARGET to another port before npm run dev.
3. Single‑service build (backend serves static files)

   cd frontend && npm run build   # creates frontend/dist
   cd ../backend && go run ./cmd/cpa-helper   # serves UI + API on :18317
   

---

Configuration highlights

• CLIProxyAPI / CPAMC URL – default http://127.0.0.1:8317; set in System Settings.
• Management key – required to call CPA’s management API.
• Local collector – when enabled, the backend pulls usage events from CPA’s queue and writes them to SQLite.
• Balances – unlimited by default; admins can set monthly/lifetime USD caps. Exhausted balances pause the user’s CPA keys.
• Model pricing – token‑based (USD per M tokens) or fixed‑price for image models; can be synced from LiteLLM.
• Data directory – override with CPA_HELPER_DATA_DIR if you don’t want the default ./data.
• Codex inspection – cron expression, quota thresholds, check‑only mode, worker count, priority rules.

---

Who might use it?

• Teams that run multiple agents against a shared CPA service and need per‑user accounting.
• Ops / DevOps engineers who want a simple UI to monitor usage, enforce budgets, and rotate API keys.
• Administrators of self‑hosted AI stacks (e.g., private LLM deployments) that expose a CLIProxyAPI‑compatible interface.

---

License

MIT – free to use, modify, and redistribute.

---

Bottom line: CPA‑Helper is a lightweight, Go‑backed, Vue‑fronted admin console that centralizes analytics, billing, and credential management for any service that implements the CLIProxyAPI/CPA management interface. It’s designed for on‑premise deployment, requires only Go 1.25+, Node 20+ and a running CPA endpoint, and stores everything locally in SQLite.