WizisCool/oh-my-cpa

Manage APIs and OAuth in one place, visualize requests, cost and usage

MCP · Visualization · Management

Live Demo · Install · Features · Agents and MCP · Documentation · 简体中文

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.

Request records Every request, filterable by model, provider, key, status and cost	Cost & usage A price book matched from OpenRouter, with custom overrides
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

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/master/docs/install-for-agents.md

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.

Save the following as compose.yml in a new directory:

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8317:8317"
    environment:
      MANAGEMENT_PASSWORD: ${CPA_MANAGEMENT_KEY:?}
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
      - ./plugins:/CLIProxyAPI/plugins

  oh-my-cpa:
    image: wiziscool/oh-my-cpa:latest
    restart: unless-stopped
    depends_on:
      - cli-proxy-api
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      OMCPA_CPA_BASE_URL: http://cli-proxy-api:8317
      OMCPA_CPA_MANAGEMENT_KEY: ${CPA_MANAGEMENT_KEY:?}
      OMCPA_MASTER_KEY: ${OMCPA_MASTER_KEY:?}
      OMCPA_DATA_DIR: /data
    volumes:
      - oh-my-cpa-data:/data

volumes:
  oh-my-cpa-data:

In that directory, download CPA's starter configuration, generate the two keys and start both services:

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/omc/ 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.

Add the service under services: in the Compose file that runs CPA, and merge oh-my-cpa-data: into the top-level volumes: key if one exists. cli-proxy-api is the service name in CPA's own Compose file; replace it if the service is named differently.

  oh-my-cpa:
    image: wiziscool/oh-my-cpa:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      OMCPA_CPA_BASE_URL: http://cli-proxy-api:8317
      OMCPA_CPA_MANAGEMENT_KEY: ${OMCPA_CPA_MANAGEMENT_KEY:?}
      OMCPA_MASTER_KEY: ${OMCPA_MASTER_KEY:?}
      OMCPA_DATA_DIR: /data
    volumes:
      - oh-my-cpa-data:/data

volumes:
  oh-my-cpa-data:

Add two lines to .env in the same directory:

OMCPA_CPA_MANAGEMENT_KEY=<CPA's management key in plaintext, not the hash in config.yaml>
OMCPA_MASTER_KEY=<output of: openssl rand -hex 32>

Run docker compose up -d oh-my-cpa, which leaves the CPA container running as it is. Open http://127.0.0.1:8080/omc/ and sign in with the management key.

Save the following as compose.yml in a new directory. OMCPA_CPA_BASE_URL is CPA's address as seen from inside the container: the value below reaches a CPA on the same machine that listens on all interfaces, and reaching CPA lists the other cases.

services:
  oh-my-cpa:
    image: wiziscool/oh-my-cpa:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      OMCPA_CPA_BASE_URL: http://host.docker.internal:8317
      OMCPA_CPA_MANAGEMENT_KEY: ${OMCPA_CPA_MANAGEMENT_KEY:?}
      OMCPA_MASTER_KEY: ${OMCPA_MASTER_KEY:?}
      OMCPA_DATA_DIR: /data
    volumes:
      - oh-my-cpa-data:/data

volumes:
  oh-my-cpa-data:

Create .env in the same directory:

OMCPA_CPA_MANAGEMENT_KEY=<CPA's management key in plaintext, not the hash in config.yaml>
OMCPA_MASTER_KEY=<output of: openssl rand -hex 32>

Run docker compose up -d, then open http://127.0.0.1:8080/omc/ and sign in with the management key.

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.

CPA hands each usage record to a single reader. If another usage tracker reads the same CPA, stop it, or add OMCPA_USAGE_INGEST_MODE: "off" under environment: to use OMC for management only. Other management panels do not conflict.

The installation guide covers the hardened Compose files published with each release, remote access, HTTPS, building from source, upgrades and troubleshooting.

In the console: On the /agent page, a model routed through CPA answers questions and operates the console: usage and request analysis, providers, OAuth, quota, client keys, configuration and pricing. Reads run directly. Changes are prepared server-side and run only after an Allow in the console. Secrets, tokens and OAuth authorization never enter the model's context. Answers can mix text with inline interactive components that appear while they are generated: local filters, calculators, diagrams and charts. Components use the console's visual system; follow-ups needing new data or actions stay in the reviewed conversation flow.

From an external agent: The same capabilities are served over MCP at <console URL>/api/mcp (Streamable HTTP), so an agent on another machine connects by URL with the CPA management key as a bearer token. Nothing is installed on the agent's side. The Connect action at the top of /agent shows the deployment's own endpoint with ready-to-copy configuration.

Claude Code:

claude mcp add --transport http oh-my-cpa https://cpa.example.com/omc/api/mcp \
  --header "Authorization: Bearer $OMCPA_CPA_MANAGEMENT_KEY"

Codex (~/.codex/config.toml):

[mcp_servers.oh-my-cpa]
url = "https://cpa.example.com/omc/api/mcp"
bearer_token_env_var = "OMCPA_CPA_MANAGEMENT_KEY"

Clients configured in JSON, such as Cursor:

{
  "mcpServers": {
    "oh-my-cpa": {
      "url": "https://cpa.example.com/omc/api/mcp",
      "headers": { "Authorization": "Bearer <CPA management key>" }
    }
  }
}

{
  "mcpServers": {
    "oh-my-cpa": {
      "command": "/path/to/oh-my-cpa",
      "args": ["mcp"],
      "env": {
        "OMCPA_SERVER_URL": "https://cpa.example.com/omc",
        "OMCPA_CPA_MANAGEMENT_KEY": "<CPA management key>"
      }
    }
  }
}

An external agent reads state and makes low-risk writes, such as display names and preferences, directly. Every other change it can only prepare: it cannot approve the operation, submit a secret or complete an OAuth sign-in, and the prepared change returns a link that opens its approval in the console. The management key is administrator-equivalent, so connect only trusted agents and serve the console over HTTPS before connecting one remotely. docs/agent-capabilities.md is the contract.

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

Browser ──▶ Direct listener / existing HTTPS ingress ──▶ Oh My CPA (:8080)
                                                 ├─ Embedded React SPA (/omc/)
                                                 ├─ 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.
• Sub-path native: served under /omc by default (OMCPA_BASE_PATH), so it shares a host with CPA.
• 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.

Using OMC

Developing OMC

Issues and pull requests are welcome. Development needs Go 1.25+, 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/omc/

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

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

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

Thanks also to the Linux.do community.

MIT