CLIProxyAPI with CPA Manager Plus: A Self-Hosted AI Gateway and Observability Stack

AI, Self-Hosted, Tutorial

CLIProxyAPI with CPA Manager Plus

If you use AI subscription plans such as Claude Code, ChatGPT Codex, Gemini (Antigravity), Grok Build, or Kimi Code and want to call them through a standard OpenAI/Gemini/Claude API endpoint while tracking requests, costs, and account status in an intuitive dashboard, the combination of CLIProxyAPI + CPA Manager Plus is a self-hosted solution worth considering. This article introduces both projects, highlights their key features, explains why you should use them together, and walks through deployment with Docker Compose.

1. What is CLIProxyAPI?

CLIProxyAPI is an open-source proxy server that wraps AI CLI/agent tools (Antigravity, ChatGPT Codex, Claude Code, Grok Build, etc.) into an API service compatible with the OpenAI, Gemini, and Claude standards. In other words, instead of paying for separate API access for each provider, you can leverage the subscription plans you have already purchased (Claude Pro, ChatGPT Plus/Pro, Gemini, etc.) to call models through a local API endpoint that works with most existing SDKs and clients.

The project currently supports a wide range of large model providers: Kimi (Moonshot AI), OpenAI GPT series, Anthropic Claude series, Google Gemini (via Antigravity), and xAI Grok - all through OAuth login or API key, without exposing sensitive account information outside your own server.

2. What is CPA Manager Plus?

CPA Manager Plus (CPAMP) is an administration and monitoring dashboard built specifically for CLIProxyAPI. If CLIProxyAPI is the “engine” that processes requests, then CPA Manager Plus is the “dashboard” that lets you see everything the engine is doing: configuring providers/OAuth, monitoring requests in real time, analyzing costs, checking quotas and account health for Codex/Claude/xAI, all within a self-hosted interface.

CPA Manager Plus offers two deployment modes:

  • Lightweight Panel: replaces only the default admin UI of CLIProxyAPI. No additional service, database, or port required.
  • Full Mode: runs a standalone Manager Server (image seakee/cpa-manager-plus) backed by a SQLite database that stores request history, supports cost analysis, account checks, and automation. This is the mode designed to run alongside CLIProxyAPI in a Docker Compose stack.

3. Key Features of CLIProxyAPI

  • Multi-standard API endpoints: provides interfaces compatible with OpenAI (including the Responses API), Gemini (including the Interactions API), and Claude for CLI models.
  • OAuth support for multiple providers: OpenAI Codex, Claude Code, Grok Build, Gemini/Antigravity, Kimi - login with your existing subscription account, no separate API key needed.
  • Streaming and non-streaming responses, including WebSocket-based replies where supported.
  • Function calling / tool use: compatible with agents that need to invoke tools.
  • Multimodal input: accepts both text and images.
  • Multi-account load balancing (round-robin): combine multiple Gemini, OpenAI, Claude, or Grok accounts to increase usage quotas and reduce rate-limit risk.
  • Custom OpenAI-compatible provider support through configuration, for example OpenRouter.
  • Management API for remote configuration and account management - the foundation that tools like CPA Manager Plus connect to.
  • Go SDK that lets you embed the proxy directly into other applications.

4. Why Combine CLIProxyAPI with CPA Manager Plus?

On its own, CLIProxyAPI only focuses on forwarding and formatting requests and responses. Since v6.10.0 the project has removed its built-in usage statistics feature to keep the core lightweight. This means that if you run CLIProxyAPI alone, you have no overall visibility into:

  • Which requests are failing, how latency looks, and where calls originate.
  • Estimated costs per model and per account.
  • Which Codex/Claude/xAI accounts are nearing quota exhaustion or are “unhealthy” and need cleanup.

This is exactly why CPA Manager Plus is recommended: it turns CLIProxyAPI from a “silent, hard-to-control” proxy into a system that can be operated long-term by a team or by an individual running multiple AI accounts simultaneously. Concrete benefits:

  1. Granular request monitoring: track by account, model, channel, latency, status, and token usage.
  2. Flexible cost estimation: edit model pricing tables, one-click sync prices from LiteLLM.
  3. Quota and account health management: run batch checks, detect exhausted or errored accounts, get cleanup suggestions, and execute one-click remediation. Very useful when managing many Codex/Claude accounts at once.
  4. Persistent storage: all events are saved to SQLite, so data survives container restarts.
  5. Clear separation of concerns: CLIProxyAPI handles proxying and gateway logic; CPA Manager Plus handles observability and administration. The split makes the stack easier to scale and maintain, in line with the “one service per responsibility” principle of Docker Compose deployments.

5. Docker Compose Deployment

Below is a Docker Compose configuration that runs CLIProxyAPI alongside CPA Manager:

---
services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    pull_policy: always
    container_name: cli-proxy-api
    restart: unless-stopped
    volumes:
      - ./config/config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    ports:
      - "8317:8317"
      - "8085:8085"
    networks:
      - cpa-net
  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    pull_policy: always
    container_name: cpa-manager-plus
    restart: unless-stopped
    environment:
      HTTP_ADDR: "0.0.0.0:18317"
      USAGE_DB_PATH: "/data/usage.sqlite"
      CPA_MANAGER_DATA_KEY_PATH: "/data/data.key"
      CPA_MANAGER_ADMIN_KEY: "<set-a-long-random-admin-key>"
      CPA_UPSTREAM_URL: "http://cli-proxy-api:8317"
      CPA_MANAGEMENT_KEY: "<match-remote-management.secret-key>"
      USAGE_COLLECTOR_MODE: "auto"
    ports:
      - "18317:18317"
    volumes:
      - cpa-manager-data:/data
    depends_on:
      - cli-proxy-api
    networks:
      - cpa-net
networks:
  cpa-net:
volumes:
  cpa-manager-data:
    external: true
    name: cpa_cpa-manager-data

Component Explanation

cli-proxy-api service

  • image: eceasy/cli-proxy-api:latest: community-packaged CLIProxyAPI image.
  • ./config/config.yaml:/CLIProxyAPI/config.yaml: mount the main config file where API keys, provider lists, and the Management API toggle are declared.
  • ./auths:/root/.cli-proxy-api: stores OAuth tokens after logging in to Claude Code, Codex, Gemini, etc. This directory must be persisted so you do not have to re-authenticate every time the container restarts.
  • ./logs:/CLIProxyAPI/logs: runtime logs, useful for debugging.
  • Port 8317: main API port (OpenAI/Gemini/Claude-compatible endpoint). Port 8085 is usually used for OAuth callback when logging in accounts.

cpa-manager-plus service

  • HTTP_ADDR: internal address and port that the Manager Server listens on inside the container, matching the 18317 port published to the host.
  • USAGE_DB_PATH / CPA_MANAGER_DATA_KEY_PATH: paths to the SQLite database (usage.sqlite) and encryption key file (data.key), both stored under /data.
  • CPA_MANAGER_ADMIN_KEY: administrator key used to log in to the CPA Manager Plus dashboard. Set a long, random, secret string - this is your dashboard login key, separate from the CLIProxyAPI Management Key.
  • CPA_UPSTREAM_URL: points to CLIProxyAPI’s internal address within the same Docker network (http://cli-proxy-api:8317). Docker Compose resolves the service name to an internal DNS entry.
  • CPA_MANAGEMENT_KEY: must exactly match the remote-management.secret-key declared in config.yaml of CLIProxyAPI. This is the key that authorizes the Manager Server to call CLIProxyAPI’s Management API.
  • USAGE_COLLECTOR_MODE: auto: lets the Manager Server automatically pick the best usage data collection method (RESP Pub/Sub, HTTP usage queue, or RESP pop) based on the internal network setup.
  • depends_on: cli-proxy-api: guarantees CLIProxyAPI starts before the manager.
  • Volume cpa-manager-data:/data: persists the SQLite database and data.key encryption file. Back this up regularly, because if data.key is lost, the CPA Management Keys stored in SQLite cannot be recovered. In this compose file the volume is declared as external: true with name cpa_cpa-manager-data, meaning the volume must be created beforehand (e.g. via docker volume create cpa_cpa-manager-data) rather than being auto-created by Compose. This is useful when you want data to survive independently of the stack lifecycle, or when reusing the volume across multiple docker compose up/down cycles.

Required config.yaml Settings

For CPA Manager Plus to connect and collect usage data, the config/config.yaml of CLIProxyAPI must enable the Management API and allow remote access from the internal Docker network:

remote-management:
  secret-key: "<match-CPA_MANAGEMENT_KEY-from-cpa-manager-plus-service>"
  allow-remote: true

usage-statistics-enabled: true

The secret-key here must exactly match the CPA_MANAGEMENT_KEY environment variable in the cpa-manager-plus service.

Deployment Steps

  1. Create a project directory, for example cliproxyapi-stack/. Inside it create config/config.yaml, an empty auths/ directory, and an empty logs/ directory.
  2. Paste the Docker Compose content above into docker-compose.yaml.
  3. Configure config.yaml with remote-management and usage-statistics-enabled as shown above, plus the list of api-keys you want to use to authenticate clients calling CLIProxyAPI.
  4. Run the command:
docker compose up -d
  1. Visit http://<host>:18317 (or /management.html depending on the version) to complete the initial setup for CPA Manager - enter the CPA internal URL (http://cli-proxy-api:8317) and the Management Key.
  2. Because the cpa-manager-data volume is declared external: true, create it before running docker compose up:
docker volume create cpa_cpa-manager-data
  1. Run docker compose up -d, then check the logs to retrieve the Admin Key (if you did not already set CPA_MANAGER_ADMIN_KEY yourself):
docker compose logs cpa-manager-plus
  1. Visit http://<host>:18317/management.html, log in with the Admin Key, then register the CPA internal URL (http://cli-proxy-api:8317) and CPA Management Key if not already configured via environment variables.
  2. In the CLIProxyAPI UI, perform OAuth login for each account (Claude Code, Codex, Gemini, etc.).
  3. Point your client/SDK (Claude Code, code using the OpenAI SDK, etc.) at the endpoint http://<host>:8317 using an API key declared in config.yaml.

Security note: replace the CPA_MANAGER_ADMIN_KEY and CPA_MANAGEMENT_KEY values in the compose file with your own long random secrets. Do not reuse the example values, and do not commit a .env or compose file containing these keys to a public repository.

6. Conclusion

CLIProxyAPI solves the problem of “using your existing AI subscriptions as an API.” CPA Manager Plus solves the problem of “managing and observing” that system as usage scales up - multiple accounts, multiple models, multiple internal users. Combining both in a Docker Compose stack gives you a self-hosted AI gateway that is cost-efficient, easy to monitor, and easy to maintain, suitable for both individuals and development teams that rely on several AI agent tools daily.