-
Notifications
You must be signed in to change notification settings - Fork 77
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.
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
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.
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
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.
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.
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-enabledredis-usage-queue-retention-secondsremote-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.
| Variable | Default | Description |
|---|---|---|
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_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 |
PANEL_PATH |
empty | Optional custom management.html
|
Startup precedence:
environment variables > config.json > defaults
| 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 |
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 |
/v0/management/* |
Proxied to CPA unless handled by CPAMP |
After setup, Manager Server management endpoints require:
Authorization: Bearer <CPAMP_ADMIN_KEY>
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.sqliteleaks withoutdata.key, the saved CPA Management Key is not directly readable. - If both
usage.sqliteanddata.keyleak, the saved CPA Management Key can be decrypted. - If
data.keyis 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.
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.