oh-my-cpa

Centralize APIs, OAuth and routing, observe requests, quota and cost

Management · Routing · Observability · Agent & MCP

Live Demo ·
Install ·
Features ·
Ecosystem & Plugins ·
Documentation ·
简体中文

Oh My CPA (OMC) is a web console for CLIProxyAPI v8+,
built on shadcn/ui with a modern UI/UX, fluid motion, and desktop and mobile layouts.
OMC centralizes providers, OAuth accounts, visual routing and a built-in plugin
ecosystem, and provides comprehensive request records, live routing, multi-dimensional
pricing analytics, quota window warmup and forecasting, and Agent/MCP tools. Data is
protected with AES-GCM encryption and automatic config backups, and the console signs
in with CPA's management key.

[!TIP]
Try the Live Demo

Screenshots

Request records Every request, filterable by model, provider, key, status and cost	Cost & usage A price book matched from OpenRouter, with custom overrides
Insights Compare usage across keys, models and providers with trends and rhythms	Agent Query usage, analyze traffic and operate the console in natural language
OAuth management Sign in, inspect quota and configure each credential in one place	AI providers Endpoints, models, priority and an enable switch enforced by the gateway

Mobile layout
Every page adapts to a narrow screen

Install

Install with an agent

Paste the following into Claude Code, Codex, Cursor or another coding agent. The agent
inspects the machine, picks the matching method and installs it:

Install Oh My CPA for me by following
https://raw.githubusercontent.com/WizisCool/oh-my-cpa/main/docs/install-for-agents.md

Install with Docker Compose

Requires Docker Engine with the Compose plugin and CLIProxyAPI v8.0.0 or later. The
commands assume a Linux or macOS shell with curl and openssl. The console's sign-in
password is CPA's management key.

New install

Deploys CPA, OMC and the console updater together in a new directory:

mkdir -p oh-my-cpa && cd oh-my-cpa
curl -fsSL https://github.com/WizisCool/oh-my-cpa/releases/latest/download/compose.full.yml -o compose.yml
curl -fsSL https://github.com/WizisCool/oh-my-cpa/releases/latest/download/cpa.config.example.yaml -o config.yaml
printf 'CPA_MANAGEMENT_KEY=%s\nOMCPA_MASTER_KEY=%s\n' "$(openssl rand -hex 24)" "$(openssl rand -hex 32)" > .env
chmod 600 .env
docker compose up -d

Open http://127.0.0.1:8080/ and sign in with the CPA_MANAGEMENT_KEY value
from .env. Providers and client keys are added in the console; clients send requests
to CPA at http://127.0.0.1:8317.

CLIProxyAPI is already installed

Deploys OMC and the updater beside an existing CPA without modifying or restarting CPA:

mkdir -p oh-my-cpa && cd oh-my-cpa
curl -fsSL https://github.com/WizisCool/oh-my-cpa/releases/latest/download/compose.omc.yml -o compose.yml
printf 'OMCPA_CPA_BASE_URL=http://host.docker.internal:8317\nOMCPA_MASTER_KEY=%s\n' "$(openssl rand -hex 32)" > .env
cat >> .env <<'EOF'
OMCPA_CPA_MANAGEMENT_KEY='<CPA plaintext management key, not the hash in config.yaml>'
EOF
chmod 600 .env

Edit .env to replace <CPA plaintext management key, not the hash in config.yaml> (keep single quotes if the key contains $, escaping any literal ' as \'), set OMCPA_CPA_BASE_URL for where CPA runs, and start:

docker compose up -d

Open http://127.0.0.1:8080/ and sign in with the management key.

Common .env adjustments (no compose.yml edits needed; run docker compose up -d to apply):

Updating

With oh-my-cpa-updater in place, System Information in the console shows
Update now beside a newer release of Oh My CPA or CLIProxyAPI. The updater pulls the
image, replaces the container with its settings, volumes and networks unchanged, and
restores the previous container if the new one does not start.

A deployment installed before this service existed gains it with one command on the
Docker host; the Compose file is not edited:

docker run --rm --pull always -u 0 -v /var/run/docker.sock:/var/run/docker.sock wiziscool/oh-my-cpa:latest updater install

The command adds an oh-my-cpa-updater container and brings Oh My CPA up to the current
release in the same step. docker rm -f oh-my-cpa-updater removes it. An image pinned to
a version tag is never changed from the console. Upgrading
describes each case and the manual alternative.

Install a native executable

Tagged releases include executables
for macOS (Darwin), Windows, Linux and FreeBSD, on amd64 and arm64. Each archive embeds
the console and includes an environment template; verify its SHA-256 hash against the
release's checksums.txt. No Go, Node or Docker is required. CPA must be installed
separately. Follow the native installation guide
for configuration, permissions and upgrades.

Notes

[!IMPORTANT]
Back up .env. OMCPA_MASTER_KEY encrypts the database, and the data cannot be read
without it.

oh-my-cpa-updater is the only container that mounts /var/run/docker.sock, which
amounts to control of Docker on that host; oh-my-cpa itself stays non-root and
read-only. Console updates are turned off by deleting oh-my-cpa-updater from
compose.yml and removing its running container with docker rm -f oh-my-cpa-updater.
Updates are then applied with docker compose pull && docker compose up -d.

The installation guide covers remote access, HTTPS, host bind-mount
permissions, building from source, upgrades and troubleshooting.

Features

• AI providers: Codex, Claude, Gemini, Meta Muse, xAI, Vertex AI, Gemini Interactions, DeepSeek and OpenAI-compatible services, each with credentials, advanced model options, runtime retry/error policies, priority, weight, proxy and an enable switch enforced by the gateway.
• OAuth management: sign in from the console for Codex, Claude, Antigravity, xAI, Kimi (kimi.com and kimi.ai), Devin and Meta Muse, or import a Vertex service account key. Auth files, manual token refresh, model lists, Meta quota, live xAI/Antigravity plan readings and credential-specific aliases are managed per credential; shared model aliases and exclusion rules apply provider-wide. Codex, Claude and supported Antigravity groups show what is left of each window in dollars and tokens, estimated from the quota each refresh sees used and carried into a new cycle by earlier ones. Quota readings refresh themselves about a minute after a window resets and every six hours by default, adjustable in OMC Settings. Codex/Claude window warmup adds opt-in reset and daily schedules, credential overrides and an optional confirmed tiny request. Approved schedules check current quota and billing before sending, then observe window activation.
• Client keys: create, name and revoke gateway API keys. Names appear in request records and filters.
• Model catalog: pull model lists straight from upstream providers.
• Playground: test any routed model with text and images, streamed multi-turn answers and request diagnostics.
• Plugins: installed plugins, a plugin store connected to the OMC Community registry, typed settings forms, and trusted plugin pages with native CPA management/model-directory compatibility. See the trust boundary.

• Insights: per-key, per-model, per-provider and per-credential comparison over today, yesterday, this or last week and month, rolling spans or custom ranges, each against the previous period, with each key's model mix, a traffic flow and an hour-of-day usage rhythm.
• Dashboard: request volume, token throughput, cache hit rate and cost over presets from 15 minutes to 90 days, an all-time window since installation, or any custom range, plus a year-long token heatmap. Statistics are kept permanently; request records roll out of a configurable retention.
• Live routing: a rolling minute of which models were called and which credentials and providers CPA sent them to. Each new request travels the map out to its credential and back, rerouted attempts and cooldowns included. The panel updates as records are stored, falls back to a short poll when the live stream is unavailable, and is shown on desktop widths.
• Model panels: token trend and usage ring by call model or by requested model, with cost shares.
• Request records: multi-select facets and full-text search; new records appear live as soon as they are stored; a detail drawer with duration, TTFT, token breakdown and the raw per-request log. Each record keeps the model the upstream reported serving, and flags the ones where it differs from the model requested.
• Display currency: choose from eleven mainstream currencies, including USD, CNY, MYR, JPY and EUR, in OMC Settings. Dashboard, request records and Insights use Frankfurter v2 rates, refreshed daily or manually and cached in SQLite; accounting and Cost & Usage stay in USD.
• Background collection: usage is ingested by stream or polling, even with no browser open.
• Logs and audit trail: tail the gateway log, read the console's own service log, and review an append-only audit trail with filters and JSON export.

• Request-time snapshots: a request's cost is fixed by immutable price versions when it completes.
• OpenRouter price book: every served model priced from OpenRouter's public list, including long-context and time-of-day tiers.
• Linked and custom prices: pin a model to an OpenRouter entry or set custom rates, with tier presets and a calculator.
• Channel multipliers: scale everything one provider answers, for example a relay billed at 30% of list.
• Channel model prices: give the same model different custom rates and time tiers on different channels, with shared prices as the default.

• Dual-mode config editor: structured forms, or a Monaco YAML editor that preserves comments.
• Automatic config backups: an encrypted copy of config.yaml before every change, restorable from the console.
• Encryption at rest: stored credentials and raw usage messages are AES-GCM encrypted.
• Audited sensitive actions: revealing keys, downloading auth files and exporting logs are written to the audit log, and refused if that write fails.
• Personalization: four interface languages, light and dark themes with custom palettes, interface and monospace fonts from a font library (bundled, uploaded or installed from Google Fonts and served by the console itself), a deployment time zone, and K/M/B or 万/亿 number units.

Ecosystem & Plugins

Oh My CPA connects out of the box to the OMC Community ecosystem to discover, install, and update plugins and provider extensions.

• OMC Community Hub: Discover officially maintained providers, companion tools, and community extensions at github.com/omc-community.
• Plugin Registry Sources: The console subscribes by default to omc-community/omc-plugins. Operators can subscribe to the aggregated source or split lists in CPA's config.yaml or OMC Settings:
  • Aggregated Source (Default): https://raw.githubusercontent.com/omc-community/omc-plugins/main/registry.json
  • Officially Maintained: https://raw.githubusercontent.com/omc-community/omc-plugins/main/official.json
  • Community Contributed: https://raw.githubusercontent.com/omc-community/omc-plugins/main/community.json
• Contributing Plugins: Plugin submission guidelines, validation suites, and catalog templates are hosted at omc-community/omc-plugins.

Configuration

The full reference, with deployment constraints and operational notes, is
docs/operations.md.

Architecture

Browser ──▶ Direct listener / existing HTTPS ingress ──▶ Oh My CPA (:8080)
                                                 ├─ Embedded React SPA (/)
                                                 ├─ SQLite WAL (/data)
                                                 └─ Usage collector ──▶ CLIProxyAPI (:8317)

• Single binary: the React console is embedded in the Go executable.
• Single replica: SQLite in WAL mode, one process per data directory.
• Root by default: served at /, with an optional OMCPA_BASE_PATH for deployments that need a sub-path.
• Allowlisted facade: ordinary console APIs project safe DTOs; trusted plugin pages use the bounded native contract. Arbitrary target URLs remain refused.

docs/architecture.md has the module map, data flows and invariants.

Documentation

Using OMC

Developing OMC

Contributing

Issues and pull requests are welcome. Development needs Go 1.26+, Node.js 22+ and
pnpm 11+:

pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev          # Air + Vite with hot reload at http://127.0.0.1:5173/

Run pnpm verify before pushing.
CONTRIBUTING.md covers setup and the verification workflow.

Security

Report vulnerabilities privately as described in SECURITY.md, not in a
public issue.

Acknowledgements

Oh My CPA is built on CLIProxyAPI, which
handles protocol adaptation, credentials and request proxying.

Thanks also to the Linux.do community.

License

MIT