Upgrade

简体中文

Codex Quota Monitor keeps its runtime state in one SQLite file when history is enabled. Back up that file before major upgrades.

Compatibility Policy

• 0.x releases may refine UI copy and change JSON endpoints before the API is declared 1.0 stable.
• Existing documented command-line options and NixOS module options should remain compatible within a minor line.
• /api/v1/status, /api/v1/recommendations, /api/v1/diagnostics, /api/v1/alerts, and /metrics are the documented integration surface for 0.2.x.
• Unversioned /api/* JSON paths, summary.subline, summary.fastPill, top-level fastMode, and tabs.pool.stats were removed during the 0.x cleanup. Use the /api/v1/* paths and the documented quota/recommendation fields instead.
• SQLite history schema version 2 removes Fast/Routing snapshot columns and legacy Fast policy audit events. Back up the DB before upgrading; the monitor migrates the table shape on startup.
• Unknown JSON fields should be ignored by clients.

Before Upgrading

Record:

codex-quota-monitor --help
codex-quota-monitor --version
codex-quota-monitor print-config
codex-quota-monitor doctor
codex-quota-monitor init --mode user >/tmp/codex-quota-monitor-init.txt
curl -fsS http://127.0.0.1:4515/healthz
curl -fsS http://127.0.0.1:4515/api/v1/diagnostics | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/alerts | jq '.'

After a Python install, cqm can replace codex-quota-monitor in these interactive checks.

If you use SQLite history, back up the state DB:

cp /var/lib/codex-quota-monitor/history.sqlite3 /var/lib/codex-quota-monitor/history.sqlite3.bak

Adjust the path for Docker, uv, pipx, or custom state locations.

If you use config files, keep a copy of the active file shown by print-config or doctor.

uv

uv tool upgrade codex-quota-monitor
systemctl restart codex-quota-monitor

For rootless user services, restart with systemctl --user restart codex-quota-monitor.

Rollback:

uv tool install --force 'codex-quota-monitor==<previous-version>'
systemctl restart codex-quota-monitor

If you installed with pipx, use pipx upgrade codex-quota-monitor and pipx install --force 'codex-quota-monitor==<previous-version>' instead.

Docker

Pull the target image and recreate the container:

docker pull ghcr.io/xsyxnx/codex-quota-monitor:0.2.0

Keep the same /data volume to preserve history. Roll back by starting the previous tag with the same volume.

NixOS

Update the flake input and evaluate before switching:

nix flake update codexQuotaMonitor
nix build .#nixosConfigurations.<host>.config.system.build.toplevel --no-link

Then use your normal operator-controlled deployment path.

After Upgrading

Run:

curl -fsS http://127.0.0.1:4515/healthz
curl -fsS http://127.0.0.1:4515/api/v1/status | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/diagnostics | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/alerts | jq '.'
curl -fsS http://127.0.0.1:4515/metrics | sed -n '1,20p'

Open the dashboard and verify Pool, Diagnostics, Alerts, and Trends if history is enabled.