codex-quota-monitor 0.2.0

CLIProxyAPI-backed Codex OAuth quota and usage dashboard with routing scores, NixOS module, and Prometheus metrics

Codex Quota Monitor

简体中文

What This Is

A small self-hosted dashboard for people who run Codex OAuth accounts behind CLIProxyAPI.

Its main job is simple: turn the pool's 5h and weekly quota into Plus-equivalent remaining capacity, so you know how much work the pool can still take. It also shows which accounts should keep working, when exhausted accounts come back, and whether the pool or the monitor itself needs attention.

Community and contact:

• Matrix space: https://matrix.to/#/#codex-quota-monitor:matrix.h0pper.xyz
• Email: [e-mail]

Usage / stats views already cover request and token trends from local SQLite history, reducing the day-to-day need to open CPA usage / statistics pages; CPA remains the upstream gateway and is not installed or managed by this project.

If you just want to see the UI, run cqm --demo after installation, then open http://127.0.0.1:4516/. Demo mode uses built-in sample data and does not need CPA, management keys, or auth files.

Quick Start

You need an existing CLIProxyAPI management endpoint. The common local setup is:

• CPA management: http://127.0.0.1:8317
• CPA health: http://127.0.0.1:8317/healthz
• Dashboard: http://127.0.0.1:4515
• A key file containing the same plaintext value as CPA remote-management.secret-key

If you want Codex, Claude, or another coding agent to handle installation, smoke tests, or service wiring, start by handing it Deploy with an agent. That guide lists the facts to prepare, safety boundaries, and acceptance checks.

Pick one way to install or run it:

Run with uv / pipx

Install uv first if it is not already available:

curl -LsSf https://astral.sh/uv/install.sh | sh

After v0.2.0 is published, install from PyPI first:

uv tool install codex-quota-monitor==0.2.0

If you prefer pipx, install the same version:

pipx install codex-quota-monitor==0.2.0

To preview the source before the tag is published, use uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'.

Point it at your CPA:

cqm \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

Then open http://127.0.0.1:4515/.

Before turning it into a service, run:

cqm print-config
cqm doctor

Run with Nix

nix run github:xsyxnx/codex-quota-monitor#cqm -- \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

More NixOS module notes are in docs/nixos-module.md.

Run with Docker

docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp \
  -p 127.0.0.1:4515:4515 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_BASE_URL=http://host.docker.internal:8317 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_KEY_FILE=/management-key \
  -e CODEX_QUOTA_MONITOR_GATEWAY_HEALTH_URL=http://host.docker.internal:8317/healthz \
  -v codex-quota-monitor-data:/data \
  -v /path/to/management-key:/management-key:ro \
  -v /path/to/auth-files:/auth-files:ro \
  -e CODEX_QUOTA_MONITOR_AUTH_DIR=/auth-files \
  ghcr.io/xsyxnx/codex-quota-monitor:0.2.0

To preview the source before the release image exists, build one locally with docker build -t codex-quota-monitor:local ..

Use the NixOS module

{
  services.codexQuotaMonitor = {
    enable = true;
    managementBaseUrl = "http://127.0.0.1:8317";
    managementKeyFile = "/path/to/management-key";
    gatewayHealthUrl = "http://127.0.0.1:8317/healthz";
    authDir = "/path/to/auth-files";
  };
}

The module keeps the service on 127.0.0.1 and keeps the firewall closed unless you explicitly open it. See docs/nixos-module.md.

For the full install guide, including service files and config files, see docs/install.md and docs/quick-start.md.

Features You May Care About

• Equivalent remaining quota: 5h and weekly windows are shown as Plus-equivalent capacity; Pro is weighted as 20x Plus so you do not have to do pool math by hand.
• Account recommendations: each account gets a routingScore for humans and wrappers to rank directly.
• Machine-readable recommendation API: /api/v1/recommendations can feed an agent-wrapper without scraping the page.
• Stable API: status, stats, diagnostics, and alerts all use versioned /api/v1/* JSON endpoints.
• Stats workbench: /api/v1/stats/series exposes SQLite-backed request and token series with JSON and CSV exports.
• ETA estimates: with SQLite history enabled, estimated exhaustion times for the 5h and weekly pools at the current burn rate.
• Demo mode: --demo uses built-in sample data, with no CPA, key, or auth files required.
• Grafana: Prometheus /metrics is available for dashboards and alerts.
• Security self-audit: dedicated docs cover data flow, secret exposure, and preflight checks.
• Reverse proxy deployments: loopback by default, suitable for tunnels or a dedicated-hostname reverse proxy.
• Redacted display: the UI can mask email addresses and token-like strings for screenshots or remote debugging.
• Import / export: SQLite history keeps trend data and can be backed up, moved, and restored.
• Light / Dark: the dashboard has both modes, so it does not glare next to a dark terminal.
• Custom fonts: set UI and monospace fonts to make Chinese text, numbers, and tokens easier to read.
• Mobile / Kindle: narrow screens still show the core status.
• Logs: foreground-friendly by default, with structured logs for service managers or collectors.
• Nix: flake app/package and a reusable NixOS module are included.
• Agent entry point: docs, APIs, and recommendation groups are ready for agent-driven installation, deployment, and status reads.
• tldr / doctor: cqm tldr gives the short version; cqm doctor checks the setup before production use or during troubleshooting.

Useful docs:

• API and metrics
• Security self-audit
• Benchmark guide
• Troubleshooting
• Deploy with an agent

Feedback And Contributions

• GitHub Issues: https://github.com/xsyxnx/codex-quota-monitor/issues
• Matrix space: https://matrix.to/#/#codex-quota-monitor:matrix.h0pper.xyz
• Email: [e-mail]

Bug reports are most useful when they include the monitor version, how you installed it, whether it talks to raw CPA or a local proxy, and redacted output from cqm doctor.

Small docs fixes, deployment notes, and bug fixes are welcome.

Rough Edges And Roadmap

This is still a focused 0.x operator tool.

Known limits:

• It does not install or manage CLIProxyAPI.
• It does not provide login, RBAC, multi-tenant isolation, or hosted analytics.
• It is not a generic quota tracker for every AI product.
• The browser UI expects to live at the root of its hostname; path-prefix reverse proxy deployments are not supported yet.
• 0.x API responses may grow new fields. Clients should ignore fields they do not understand.

Next steps:

• More copyable deployment examples.
• More real-world dashboard screenshots and capacity explanations.
• Continued Prometheus alert rule and incident response examples.
• Shorter docs where the current pages are still too dense.