Limitations

简体中文

codex-quota-monitor is built for a narrow operator workflow: watching a self-hosted CLIProxyAPI-backed Codex OAuth pool. It is useful when that is the system you run. It is intentionally incomplete outside that boundary.

Product Boundaries

• It is not a generic desktop usage tracker for every AI product.
• It does not install, configure, or replace CLIProxyAPI.
• It does not create accounts, manage subscriptions, harvest credentials, or bypass provider-side quota policy.
• It does not provide hosted analytics, cloud collection, built-in login, RBAC, multi-tenant isolation, or user access audit logs.
• It does not make LAN or public exposure safe by itself. Use an authenticated reverse proxy or access layer when sharing the dashboard.

Data Accuracy

The dashboard combines several operator-controlled sources: CPA management endpoints, gateway health, optional direct Codex quota sampling, optional SQLite history, and optional benchmark summaries. Missing or stale inputs can make per-account quota details Unknown, but the 5h and weekly pool headline shows the currently known Plus-equivalent capacity instead of replacing the whole headline with Unknown.

Important consequences:

• CPA usage and direct quota windows can disagree because they come from different systems.
• Reset times depend on what direct quota sampling can observe.
• A direct quota deactivated_workspace response means the account/workspace is unavailable and is excluded from Plus-unit capacity and account recommendations.
• Trends and ETA need enough SQLite history to become meaningful.
• Benchmark calibration is only as reliable as the benchmark run and selectors used to generate it.
• Non-Plus plan display may be visible without contributing to Plus-unit pool totals unless the project has an explicit conversion rule for that plan.
• Stats client grouping is a display-time attribution layer derived from stored CPA API names and --client-labels-file; changing the label file does not rewrite SQLite history. The legacy api grouping can still expose raw CPA API names and exists for compatibility, not privacy-preserving chargeback.

Unknown means the data may appear later. n/a should be reserved for states that are truly inapplicable.

API Compatibility

The HTTP API is mostly read-only. The protected POST /api/v1/quota/refresh action is the exception and uses an in-page refresh token by default. Legacy deployments may explicitly set manual_quota_refresh_auth = "management-key" to require the CPA management key as a bearer token; "none" is only for trusted local deployments. During 0.x releases, clients should expect new JSON fields to appear and ignore fields they do not understand. Documented stable fields should keep their meaning, but the project is still pre-1.0; check release notes before depending on exact payload shape in automation.

The API is not an authentication boundary. Host and origin checks reduce accidental browser misuse; they do not authenticate viewers.

Deployment Limits

The safe default is local access on 127.0.0.1. LAN access requires an explicit listen address, allowed-host configuration, firewall decision, and preferably an authenticated reverse proxy.

For NixOS deployments, services.codexQuotaMonitor.openFirewall is intentionally false by default.

Container and service deployments should mount only the needed management key file, auth-file directory, and writable state path. Mounting a home directory, password store, or unrelated secret directory is outside the intended model. If you use client labels, mount only that JSON file as an additional protected runtime file.

Security Limits

The monitor must read sensitive operator state to do its job. A compromised host, Python runtime, container runtime, browser, reverse proxy, CPA process, or root account can still expose secrets or operational metadata.

The project aims to avoid serializing raw management keys and OAuth token values into UI, API, metrics, history, benchmark summaries, diagnostics, and logs. Account labels, plan tiers, quota timing, model activity, health state, SQLite history, screenshots, and benchmark outputs can still be sensitive.

Read Security self-audit before mounting real credentials or exposing the dashboard beyond loopback.