NixOS Module

The flake exports nixosModules.default and nixosModules.codex-quota-monitor.

Minimal Example

{
  inputs.codexQuotaMonitor.url = "github:<owner>/codex-quota-monitor";

  outputs = inputs@{ self, nixpkgs, codexQuotaMonitor, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        codexQuotaMonitor.nixosModules.default
        ({ ... }: {
          services.codexQuotaMonitor = {
            enable = true;
            installCli = 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";
            # Optional and disabled by default. This writes live_plan_* metadata
            # back to CPA auth files for routers that consume fresh plan state.
            # authLivePlanSync.enable = true;
          };
        })
      ];
    };
  };
}

Key Options

services.codexQuotaMonitor.enable
services.codexQuotaMonitor.package
services.codexQuotaMonitor.installCli
services.codexQuotaMonitor.user
services.codexQuotaMonitor.group
services.codexQuotaMonitor.listenAddress
services.codexQuotaMonitor.allowedHosts
services.codexQuotaMonitor.port
services.codexQuotaMonitor.demo
services.codexQuotaMonitor.managementBaseUrl
services.codexQuotaMonitor.managementKeyFile
services.codexQuotaMonitor.manualQuotaRefreshAuth
services.codexQuotaMonitor.allowBrowserKeyStorage
services.codexQuotaMonitor.gatewayHealthUrl (http(s) or file JSON URL)
services.codexQuotaMonitor.authDir
services.codexQuotaMonitor.authLivePlanSync.enable
services.codexQuotaMonitor.refreshSeconds
services.codexQuotaMonitor.usageRefreshSeconds
services.codexQuotaMonitor.directQuotaRecoverySeconds
services.codexQuotaMonitor.timeoutSeconds
services.codexQuotaMonitor.weeklyToFiveHourMultiplier
services.codexQuotaMonitor.stateDb
services.codexQuotaMonitor.clientLabelsFile
services.codexQuotaMonitor.usageQueueRawEventLog
services.codexQuotaMonitor.historyWriteSeconds
services.codexQuotaMonitor.historyRetentionDays
services.codexQuotaMonitor.benchmarkSummary
services.codexQuotaMonitor.displayTimezone
services.codexQuotaMonitor.displayLocale
services.codexQuotaMonitor.uiFontFamily
services.codexQuotaMonitor.monoFontFamily
services.codexQuotaMonitor.alertFiveHourMinPlus
services.codexQuotaMonitor.alertWeeklyMinPlus
services.codexQuotaMonitor.alertRoutableAccountsMin
services.codexQuotaMonitor.openFirewall
services.codexQuotaMonitor.logLevel
services.codexQuotaMonitor.logFormat
services.codexQuotaMonitor.accessLog

Defaults

Bind address: 127.0.0.1
Allowed browser hosts/origins: loopback only unless allowedHosts is set
Port: 4515
Demo mode: disabled; set demo = true only for a zero-secret preview with built-in sample data
Management gateway: http://127.0.0.1:8317
Management key file: disabled by default; for bare CPA set managementKeyFile to a runtime secret path containing the same plaintext value as CPA remote-management.secret-key; omit it only when managementBaseUrl points at a local key-injecting proxy
Manual quota refresh auth: ui-token; the browser receives an in-page refresh token and does not need the CPA management key. Set manualQuotaRefreshAuth = "management-key" only for legacy behavior, or "none" only for trusted local deployments.
Browser key storage: disabled; only applies to legacy manualQuotaRefreshAuth = "management-key" deployments where localStorage persistence is acceptable
Auth live plan sync: disabled. When authLivePlanSync.enable = true, the module adds a separate timer/oneshot that writes direct Codex plan samples back to auth files as live_plan_* metadata. This requires authDir and gives only the sync unit write access to that directory; the dashboard service remains read-only with respect to auth files. The sync runner refuses to replace an auth file unless it can preserve the original owner and group, so run the unit as the auth-file owner or provide a deployment-specific systemd override.
Firewall: closed
Interactive CLI: not installed into the system profile by default; set installCli = true when users should be able to run codex-quota-monitor, cqm, or codex-quota-benchmark directly from the host shell
Service account: codex-quota-monitor
Usage refresh interval: null; the CLI default follows refreshSeconds. Set usageRefreshSeconds to sample CPA /v0/management/usage less often than ordinary health/auth/config refreshes.
Weekly-to-5h multiplier: 6.0; set weeklyToFiveHourMultiplier = null to disable the cap. Weekly exhaustion still removes that account from total 5h capacity.
SQLite history DB: /var/lib/codex-quota-monitor/history.sqlite3; set stateDb = null to disable Trends, Audit, the Stats time-series workbench, and native history backup.
Usage queue raw event log: disabled by default. Set usageQueueRawEventLog to a sanitized CLIProxyAPI v7 usage queue collector JSONL path, such as /var/lib/cli-proxy-api/usage-queue/events.jsonl, to import new request details into the SQLite-backed Stats workbench.
Client labels file: disabled by default. Set clientLabelsFile to a runtime JSON file path to enable the Stats client grouping; the module only passes the path, so keep real CPA API names in /run/secrets, /etc, or another protected runtime file rather than inline Nix text.
History write interval: 60 seconds
History retention: 30 days
Benchmark summary: disabled until benchmarkSummary points to a codex-quota-benchmark summary.json
Display timezone: local; set displayTimezone = "UTC";, displayTimezone = "Asia/Shanghai";, or another IANA timezone for fixed reset-time display
Display locale: auto; the dashboard follows the browser locale and currently supports en and zh-CN. Set displayLocale = "en"; or displayLocale = "zh-CN"; for a fixed service default.
UI font family: neutral system UI stack by default. Set uiFontFamily to a CSS font-family list when the operator wants a site-wide default.
Mono font family: neutral system monospace stack by default. Set monoFontFamily = "\"Maple Mono NF CN\", ui-monospace, monospace"; or another CSS stack when the browser host has that font installed.
Threshold alerts: disabled until an alert* option is set; they are exposed through /api/v1/alerts
Logging: logLevel = "INFO", logFormat = "text", and accessLog = true. Logs are written to stderr for journald; set logFormat = "json" for one JSON object per line.

Browser-local preferences in the dashboard override these service defaults for the current browser only. Locale, timezone, and font preferences are separate: locale controls UI language and browser-side date/number formatting, timezone controls reset-time display, and fonts only select CSS font-family stacks. The project does not bundle fonts; a named font is used only when the device rendering the page already has it installed.

If you want LAN access from a phone or small-screen browser, set listenAddress = "0.0.0.0", add the browser-facing hostname or IP to allowedHosts, and set openFirewall = true intentionally. That only makes the dashboard reachable and allows the expected Host / Origin; it does not authenticate viewers. Protect LAN or public access with firewall rules and an authenticated reverse proxy or access layer.