Manager Server Guide

Manager Server is the backend for the full CPAMP experience. It hosts management.html, stores local SQLite data, consumes the CPA usage queue through the collector, and protects management capabilities with the CPAMP Admin Key.

When you open this entry point, you are using Manager Server mode:

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

When CPA itself serves this entry point, you are using CPA Panel mode:

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

CPA Panel mode does not read Manager Server SQLite and does not provide the full historical monitoring, model prices, API Key aliases, import/export, or server inspection history.

What Manager Server Does

Manager Server:

• Serves the embedded management panel.
• Runs first setup and stores the bound CPA connection.
• Authenticates users with the cmp_admin_... 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, Request Monitoring, Usage Analytics, Model Pricing, API Key Alias, Usage Import/Export, and Server Codex 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 not configured, Manager Server generates:

cmp_admin_...

and prints it once in the 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 and 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

Usage 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

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, and 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.
USAGE_ACCOUNT_ACTIONS_ENABLED	false	Enable the account action queue for auth issues that need review.
USAGE_ACCOUNT_ACTIONS_AUTO_DISABLE	false	Enable automatic disabling for auth issues. This only takes effect when the account action queue is enabled.
PANEL_PATH	empty	Optional custom management.html.

Startup precedence:

environment variables > config.json > defaults

When USAGE_QUOTA_COOLDOWN_ENABLED, USAGE_ACCOUNT_ACTIONS_ENABLED, or USAGE_ACCOUNT_ACTIONS_AUTO_DISABLE is set through the environment, the matching panel switch is shown as environment-sourced and locked. Remove the environment variable and restart Manager Server if you want the setting to be editable from the panel.

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.
GET /usage-service/account-processing-policy	Read quota cooldown, account action queue, and auto-disable policy.
PATCH /usage-service/account-processing-policy	Update account processing policy. Fields locked by environment variables cannot be modified through the API.
GET /usage-service/quota-cooldowns	Read active quota cooldowns so the auth files page can show recovery hints.
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/account-action-candidates	Auth issue action queue.
POST /v0/management/account-action-candidates/{id}/ignore	Ignore an account action candidate.
POST /v0/management/account-action-candidates/{id}/resolve	Mark an account action candidate as resolved.
POST /v0/management/account-action-candidates/{id}/enable	Re-enable the auth file linked to a candidate.
DELETE /v0/management/account-action-candidates/{id}/auth-file	Delete the auth file linked to a candidate.
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.

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.