WizisCool/oh-my-cpa: Self-hosted control plane & usage observability console for CLIProxyAPI (CPA) — AI providers, client keys, streaming telemetry, and model cost snapshots.

CLIProxyAPI (CPA) is an API gateway: it adapts protocols, holds credentials and proxies requests. Oh My CPA (OMC) is a web console for it. OMC manages the gateway's providers, credentials and configuration, and records the usage and cost of every request. It is a single Go binary with the React console embedded and a local SQLite database, runs offline, and 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.

| Scenario | Method | | --- | --- | | CPA is not deployed yet | New install | | CPA is already deployed | CLIProxyAPI is already installed |

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 (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

| Where CPA runs | .env setting | | --- | --- | | Same host, listening on all interfaces | OMCPA_CPA_BASE_URL=http://host.docker.internal:8317 (default above) | | Another Docker Compose project | OMCPA_CPA_BASE_URL=http://:8317, plus OMCPA_NETWORK_NAME= and OMCPA_NETWORK_EXTERNAL=true (or add to CPA's Compose file) | | Another machine | OMCPA_CPA_BASE_URL=https://:8317 (or its private network URL) | | Same host, 127.0.0.1 only | Use the native executable |

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):

| Need | .env setting | | --- | --- | | Port 8080 is already in use | OMCPA_BIND=127.0.0.1:18317 (changes only the host port; keep container port 8080) | | Store data in ./oh-my-cpa-data | OMCPA_DATA_PATH=./oh-my-cpa-data and OMCPA_USER= (for example 1000:1000, after mkdir -p -m 700 ./oh-my-cpa-data; set before first start, as changing OMCPA_DATA_PATH later opens a new empty directory without moving existing volume data—see SQLite operations) | | Serve behind an HTTPS reverse proxy | Proxy to 127.0.0.1:8080 (for example Caddy reverse_proxy 127.0.0.1:8080; UI and API share one port) and set OMCPA_PUBLIC_URL=https://... |

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

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:

• Contributing Plugins: Plugin submission guidelines, validation suites, and catalog templates are hosted at omc-community/omc-plugins.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | OMCPA_CPA_BASE_URL | required | CPA's address | | OMCPA_CPA_MANAGEMENT_KEY | required | CPA's management key, and the console's sign-in password | | OMCPA_MASTER_KEY | required | At-rest encryption key (openssl rand -hex 32) | | OMCPA_BIND | 127.0.0.1:8080 | Docker host address mapped to the console | | OMCPA_LISTEN_ADDR | :8080 | Process listen address (for native installs) | | OMCPA_DATA_PATH | oh-my-cpa-data | Docker volume name or host directory path | | OMCPA_USER | 10001:10001 | Container uid:gid | | OMCPA_DATA_DIR | ./data | Directory of the SQLite database (/data in the container image) | | OMCPA_BASE_PATH | / | URL prefix. The default serves the console at the root | | OMCPA_PUBLIC_URL | unset | The address browsers use; https:// marks the session cookie Secure | | OMCPA_USAGE_INGEST_MODE | auto | Ingest mode (auto, subscribe, resp_pull, http_pull, or off) | | OMCPA_USAGE_RETENTION_DAYS | 90 | Days request records are kept, 0 for all; OMC Settings → Data retention overrides it. Dashboard statistics are permanent | | OMCPA_USAGE_INBOX_RETENTION_DAYS | 7 | Days captured payloads (raw records kept for re-decoding) are kept, 0 to follow request records | | TZ | system zone | Server calendar; keep it equal to CPA's. Containers default to UTC |

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.

Documentation

Using OMC

| Document | Contents | | --- | --- | | docs/install.md | Installation, verification, upgrades, troubleshooting | | docs/install-for-agents.md | The same install, as steps for a coding agent | | docs/operations.md | Settings reference and operational notes | | docs/ops/sqlite-operations.md | Backup, restore and master-key runbook | | docs/agent-capabilities.md | Agent capability contract and the MCP bridge | | docs/cpa-v8-compat.md | CPA v8 baseline and configuration relocation | | docs/pricing.md | Price books, billing tiers and locked cost snapshots |

Developing OMC

| Document | Contents | | --- | --- | | CONTRIBUTING.md | Development setup and the verification workflow | | docs/testing.md | Test layers, local feedback and CI verification | | AGENTS.md | The contract coding agents follow in this repository | | docs/architecture.md | Module boundaries, data flows and invariants | | CONTEXT.md · docs/design.md | Domain vocabulary · visual system | | docs/releasing.md | Tag-triggered Docker Hub images, native archives and GitHub releases | | docs/ops/cloudflare-demo.md | How the public demo is deployed |

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