FAQ

CPA Manager Plus provides full monitoring and analytics through the Manager Server-hosted panel. The old CPA-Manager "External Usage Service" setup for CPA Panel mode is not supported in Plus.

Use the Manager Server-hosted panel for CPAMP analytics:

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

Which Deployment Mode Should I Use?

Goal	Recommended mode
New deployment	Full Docker / Manager Server mode
Request monitoring, historical statistics, model prices, aliases, import/export	Full Docker / Manager Server mode
Existing CPA panel only, without Manager Server analytics	CPA Panel mode
No Docker	Native Manager Server mode

CPA Panel mode is for lightweight access to the CPA-hosted panel. It does not configure Manager Server and does not read Manager Server SQLite data. Use Docker or native packages when you need the full CPAMP feature set.

Which Address Should I Open?

Full Docker or native Manager Server mode:

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

CPA Panel mode is usually accessed from the CPA port:

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

If you see login instead of setup, Manager Server is already configured. Use the CPAMP Admin Key to log in.

What Is The Difference Between Admin Key And CPA Management Key?

Place	Key
CPAMP Full Docker / native login	CPAMP Admin Key, usually starting with cmp_admin_...
CPAMP first setup CPA connection	CPA Management Key
CPA Panel mode login	CPA Management Key
Normal model API calls	CPA API Key
GET /v1/models	CPA API Key
CPAMP Manager Server APIs after setup	CPAMP Admin Key

Do not mix these keys. Full Docker and native modes encrypt the CPA Management Key and save it to SQLite. In CPA Panel mode, the browser holds the CPA Management Key.

Full Docker Opens Login Instead Of Setup

Manager Server is already configured.

Use the CPAMP Admin Key:

cmp_admin_...

Do not use the CPA Management Key on the CPAMP login form. If the admin key is lost, follow Reset Admin Key.

What If I Forget The Admin Key?

Stop Manager Server, back up the data directory, then follow Reset Admin Key.

I Changed CPA Panel Repository, But Monitoring Is Empty

Changing the CPA panel repository only changes the frontend served by CPA.

Request monitoring and historical analytics require Manager Server:

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

Open:

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

Complete setup with:

CPAMP Admin Key
CPA URL
CPA Management Key

Do not look for the old "External Usage Service" setting in Plus.

Setup Shows The Wrong Default CPA URL

The setup form can suggest a default CPA URL from the frontend build.

Fix options:

1. Enter the correct CPA URL manually.
2. Rebuild the panel with VITE_DEFAULT_CPA_BASE_URL=<your-cpa-url>.

Docker Desktop host CPA commonly uses:

http://host.docker.internal:8317

Same Compose network commonly uses:

http://cli-proxy-api:8317

Linux host CPA + Docker CPAMP needs --add-host=host.docker.internal:host-gateway. See Docker Deployment.

What If The Monitoring Page Is Empty?

Start with Request Monitoring Troubleshooting to inspect /status, collector, usage queue, and retention.

Common causes:

1. CPA usage publishing is not enabled
2. Manager Server is not configured
3. CPA URL is wrong from the Manager Server network perspective
4. CPA Management Key is wrong
5. CPA version is too old
6. Collector mode is incompatible with the network path
7. Multiple Manager Servers consume the same CPA usage queue
8. Manager Server was down longer than CPA queue retention
9. Poll interval is longer than the queue retention window

Check CPA usage publishing:

usage-statistics-enabled: true

Or enable it through CPA Management API:

curl -X PUT \
  -H "Authorization: Bearer <CPA_MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"value":true}' \
  http://<cpa-address>:8317/v0/management/usage-statistics-enabled

Check Manager Server status:

curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
  http://<cpamp-host>:18317/status

Important fields:

collector.lastError
lastConsumedAt
lastInsertedAt
eventCount

If lastConsumedAt is empty, Manager Server is not consuming events. Check CPA URL, Management API, CPA version, queue publishing, and collector errors.

If lastConsumedAt changes but lastInsertedAt does not, SQLite writes are failing. Check disk space, permissions, and /data mount.

If both change but the page is empty, check browser filters, time range, hard-refresh the page, and verify /v0/management/usage.

What Is unsupported RESP prefix 'H'?

This usually means a RESP collector connected to an HTTP endpoint.

RESP mode must directly reach the CPA API port. It cannot pass through a normal HTTP reverse proxy. Recommended fix:

USAGE_COLLECTOR_MODE=auto

Use CPA v6.10.8+ for the HTTP usage queue, or CPA v7.1.39+ for the current recommended metadata set.

If you must use RESP, set CPA URL to a direct address:

http://cli-proxy-api:8317

Do not use a public HTTPS reverse proxy domain.

Can An HTTP Reverse Proxy Proxy RESP?

No. RESP Pub/Sub and RESP pop must connect directly to the CPA API port. HTTP queue can go through an HTTP proxy.

For same-domain deployment, read Reverse Proxy. Rule of thumb:

/management.html        -> CPAMP
/usage-service/*        -> CPAMP
/v0/management/*        -> CPAMP
/v1/*                   -> CPA
/backend-api/codex/*    -> CPA
OAuth callbacks         -> CPA
Fallback routes          -> CPA

Use CPAMP Admin Key for CPAMP management paths and normal API keys for /v1/*.

Container Cannot Connect To Host CPA

Inside a Docker container, 127.0.0.1 means the container itself.

If CPA runs on a Linux host and CPAMP runs in Docker:

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

Then use:

http://host.docker.internal:8317

Test from inside the container:

docker exec -it cpa-manager-plus sh
wget -qO- http://host.docker.internal:8317/healthz

Docker Rebuild Lost Data

Most likely /data was not mounted, or Plus started with a new empty volume.

Correct:

-v cpa-manager-plus-data:/data

Wrong:

docker run seakee/cpa-manager-plus:latest

After migration from old CPA-Manager, be careful with volume names:

old common volume: cpa-manager-data
Plus examples:     cpa-manager-plus-data

If you expect old data, mount the old volume or copy the old data.

Why Do Backups Need data.key?

Back up the full data directory:

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

The CPA Management Key is encrypted with data.key before being saved to SQLite. If data.key is lost, the encrypted CPA Management Key cannot be recovered and the CPA connection must be saved again.

401 From Manager Server

After setup, Manager Server endpoints require:

Authorization: Bearer <CPAMP_ADMIN_KEY>

Examples:

curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
  http://<cpamp-host>:18317/status

curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
  http://<cpamp-host>:18317/v0/management/config

The CPA Management Key is not accepted for CPAMP Manager Server-only APIs.

/models Returns 412

Manager Server setup is not complete.

Open:

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

Finish setup first.

Usage From A Downtime Window Is Missing

CPA usage queue is memory-backed and has limited retention.

Default retention:

60 seconds

Maximum:

3600 seconds

If Manager Server is down longer than the retention window, that period usually cannot be recovered from CPA. Keep Manager Server running continuously.

CPA Panel Mode Is Missing Monitoring Or Model Prices

This is expected.

CPA Panel mode does not use Manager Server analytics. Open:

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

for monitoring, dashboard analytics, model prices, API key aliases, usage import/export, and server inspection.

CPA Panel Still Shows An Old Panel

Check that CPA configuration points at this project:

remote-management.panel-repo = https://github.com/seakee/CPA-Manager-Plus

If the new panel still does not load, clear CPA's cached panel file and reload or restart CPA:

rm static/management.html

If Disable Panel Auto Updates is enabled, CPA only downloads the panel again when the cached file is missing.

Does CPAMP Upload Data?

No telemetry is uploaded. CPAMP does not include analytics SDKs and does not require a cloud account. By default it connects only to the CPA Gateway you configure; optional features such as model price sync, OAuth, and provider checks call external services only when you explicitly configure or trigger them.

Does The Demo Site Connect To A Real Backend?

No. The live demo uses frontend mock data and does not need CPA, Manager Server, CPA Management Key, tokens, or SQLite.

What Is management.html In A Release?

management.html is the single-file management panel shipped in release packages. It can be hosted by Manager Server or CPA Panel. The online documentation remains on GitHub Pages and is not distributed with install packages.