Manager Server Guide

Manager Server Guide

CPA Manager Plus Manager Server is the long-running backend for the full CPAMP experience. It replaces the old CPA-Manager Usage Service model.

Manager Server is used when you open:

http://<host>:18317/management.html

It is not used when CPA itself serves:

http://<cpa-host>:8317/management.html

In CPA panel mode, CPAMP behaves as a pure CPA panel and does not call a separate Manager Server.

---

What Manager Server Does

Manager Server:

• Serves the embedded management panel
• Runs first setup and stores the bound CPA connection
• Authenticates users with the CPAMP admin key
• Encrypts the saved CPA Management Key with data.key
• Proxies CPA Management API calls after setup
• Consumes CPA usage events
• Persists usage events in SQLite
• Provides dashboard, monitoring, model pricing, API key alias, usage import/export, and server inspection APIs

---

Architecture

Browser
  -> Manager Server :18317
      -> /management.html
      -> /usage-service/info
      -> /usage-service/config
      -> /v0/management/usage from SQLite
      -> /v0/management/model-prices from SQLite
      -> /v0/management/api-key-aliases from SQLite
      -> /v0/management/dashboard/* from SQLite
      -> /v0/management/monitoring/* from SQLite
      -> /v0/management/codex-inspection/* from SQLite/background workers
      -> other /v0/management/* proxied to CPA
      -> collector -> CPA usage queue
      -> /data/usage.sqlite

CPA still runs separately. CPAMP does not bundle CPA.

---

First Setup and Login

On first startup, CPAMP needs an admin key.

You can provide one:

CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key'

If you do not provide one, Manager Server generates:

cmp_admin_...

and prints it once in startup logs.

First setup asks for:

Admin Key
CPA URL
CPA Management Key
Request Monitoring
Collection Mode
Poll Interval

After setup:

• Browser login uses the CPAMP admin key
• CPA Management Key is stored server-side, encrypted
• Manager Server uses the saved CPA Management Key when calling CPA
• New browsers no longer need the CPA Management Key

---

CPA Prerequisites

Request monitoring requires CPA usage publishing and the CPA usage queue.

Minimum:

CPA v6.10.8+ for HTTP usage queue

Recommended:

CPA v7.1.39+

CPA Management API must be enabled:

remote-management:
  secret-key: "your CPA Management Key"
  allow-remote: true

Request publishing can be enabled by CPAMP during setup/config save, or directly in CPA:

usage-statistics-enabled: true

Queue retention is controlled by CPA:

redis-usage-queue-retention-seconds: 60

Default retention is 60 seconds and the maximum is 3600 seconds. Keep Manager Server running continuously.

---

Collection Mode

Default:

auto

Behavior:

auto -> RESP Pub/Sub -> HTTP usage queue -> RESP pop fallback

Modes:

Mode	Use when
auto	Recommended default
subscribe	Force RESP Pub/Sub for low-latency direct CPA API access
http	Force HTTP usage queue; useful behind normal HTTP reverse proxies
resp	Force legacy RESP pop; must directly reach the CPA API port

RESP transports cannot pass through a normal HTTP reverse proxy. If you see unsupported RESP prefix 'H', the RESP client is probably connecting to an HTTP endpoint.

---

Configuration Boundary

Managed by Manager Server:

• Bound CPA URL
• Encrypted CPA Management Key
• Request monitoring switch
• Collection mode
• Poll interval
• Batch size
• Query limit
• SQLite usage data
• Model pricing data
• API key aliases
• Server inspection history

Still managed by CPA:

• usage-statistics-enabled
• redis-usage-queue-retention-seconds
• remote-management
• proxy and routing config
• logging config
• auth files
• provider config
• CPA config.yaml

Saving CPAMP configuration does not rewrite the full CPA config.yaml.

---

Environment Variables

Variable	Default	Description
CPA_MANAGER_CONFIG	empty	Optional config file path. Native packages default to config.json next to the binary
HTTP_ADDR	0.0.0.0:18317	Manager Server listen address
USAGE_DATA_DIR	Docker: /data; native: ./data	Base data directory
USAGE_DB_PATH	Docker: /data/usage.sqlite; native: ./data/usage.sqlite	SQLite database path
CPA_MANAGER_ADMIN_KEY	empty	Optional admin key
CPA_MANAGER_ADMIN_KEY_FILE	/run/secrets/cpa_admin_key	Optional admin key file
CPA_MANAGER_DATA_KEY	empty	Optional data encryption key
CPA_MANAGER_DATA_KEY_FILE	/run/secrets/cpa_data_key	Optional data encryption key file
CPA_MANAGER_DATA_KEY_PATH	Docker: /data/data.key; native: ./data/data.key	Generated data key path
CPA_UPSTREAM_URL	empty	Optional environment-managed CPA URL
CPA_MANAGEMENT_KEY	empty	Optional environment-managed CPA Management Key
CPA_MANAGEMENT_KEY_FILE	/run/secrets/cpa_management_key	Optional CPA Management Key file
USAGE_COLLECTOR_MODE	auto	auto, subscribe, http, or resp
USAGE_RESP_QUEUE	usage	RESP key argument; normally leave unchanged
USAGE_RESP_POP_SIDE	right	right uses RPOP; left uses LPOP
USAGE_BATCH_SIZE	100	Max records per batch
USAGE_POLL_INTERVAL_MS	500	Idle poll interval
USAGE_QUERY_LIMIT	50000	Max recent usage events
USAGE_CORS_ORIGINS	*	CORS origins for compatibility endpoints
USAGE_RESP_TLS_SKIP_VERIFY	false	Skip TLS verification for RESP connection
USAGE_QUOTA_COOLDOWN_ENABLED	false	Enable the Codex usage-limit cooldown worker
PANEL_PATH	empty	Optional custom management.html

Startup precedence:

environment variables > config.json > defaults

---

Runtime Endpoints

Endpoint	Purpose
GET /health	Health check
GET /status	Collector, SQLite, event count, and errors
GET /usage-service/info	Manager Server mode detection
GET /usage-service/config	Read CPAMP Manager Server config
PUT /usage-service/config	Save CPAMP config and restart collector if needed
POST /setup	First setup
GET /v0/management/usage	Compatible usage data
GET /v0/management/usage/export	Export JSONL usage events
POST /v0/management/usage/import	Import JSONL or compatible legacy snapshots
GET /v0/management/model-prices	Model pricing
PUT /v0/management/model-prices	Replace saved model pricing
POST /v0/management/model-prices/sync	Price sync
GET /v0/management/api-key-aliases	API key aliases
GET /v0/management/dashboard/*	Dashboard data
GET /v0/management/monitoring/*	Monitoring data
GET /v0/management/codex-inspection/*	Server Codex inspection
GET /models, GET /v1/models	Proxy model-list requests to CPA after setup
/v0/management/*	Proxied to CPA unless handled by CPAMP

After setup, Manager Server management endpoints require:

Authorization: Bearer <CPAMP_ADMIN_KEY>

---

Data and Security

Back up:

usage.sqlite
usage.sqlite-wal
usage.sqlite-shm
data.key

Security notes:

• The admin key is not stored in plaintext; only a salted HMAC credential is stored.
• The CPA Management Key is encrypted before being stored in SQLite.
• If usage.sqlite leaks without data.key, the saved CPA Management Key is not directly readable.
• If both usage.sqlite and data.key leak, the saved CPA Management Key can be decrypted.
• If data.key is lost, the saved CPA Management Key cannot be recovered.
• Request metadata may contain model names, endpoints, account labels, project snapshots, token usage, latency, and failure summaries.
• Raw failure bodies stay local in SQLite. Normal APIs and JSONL exports expose sanitized summaries instead of raw diagnostic bodies.

---

Codex Usage-Limit Cooldown

The quota cooldown worker is disabled by default.

Enable it only when you want Manager Server to temporarily disable Codex auth files after strict short-window usage-limit failures:

USAGE_QUOTA_COOLDOWN_ENABLED=true

The worker acts only when all of these are true:

• provider is codex
• HTTP status is 429
• structured error type is usage_limit_reached
• the event includes resets_at or resets_in_seconds
• the event includes an auth-file snapshot

Safety boundaries:

• Only CPAMP-owned cooldowns are auto-recovered.
• Auth files that were already disabled before CPAMP acted are not re-enabled automatically.
• Recovery re-reads current CPA auth files and verifies the auth file and auth index before enabling.
• The worker does not expose raw request fail_body or raw_json through management APIs.

---

Import and Export

Manager Server exports JSONL / NDJSON usage events.

It can import:

• JSONL / NDJSON exported by Manager Server
• Legacy usage snapshots only when request-level details exist

Aggregate-only legacy files cannot reconstruct request-level monitoring. Test imports against a backup or staging database when accuracy matters.