Deploy With An Agent

简体中文

Use this doc when you want Codex, Claude, or another coding agent to install, smoke-test, or wire codex-quota-monitor. It assumes you already have a reachable CLIProxyAPI; this project does not install, upgrade, or manage CPA for you.

What To Prepare

• Which machine should run the monitor, and whether the agent may execute commands there
• Install path: prefer uv / Python foreground smoke test, Docker / Compose, or a flake module in an existing NixOS repo
• The CLIProxyAPI management gateway URL, usually http://127.0.0.1:8317
• The runtime path to the CPA management key file, unless the gateway URL points at a local key-injecting proxy
• The gateway health URL, usually http://127.0.0.1:8317/healthz
• Optional Codex auth-files directory for direct quota sampling
• Whether SQLite history should use the default path, be disabled, or use a custom path
• Whether the page should stay local-only, be reachable on the LAN, or sit behind an authenticated reverse proxy / access layer
• The browser-facing hostname or IP; LAN and reverse-proxy access need this in allowedHosts
• Optional benchmark summary.json path and machine-readable alert thresholds; do not ask the agent to guess these values

Agent Boundaries

• Do not install or manage CLIProxyAPI; connect only to an existing CPA.
• Do not write management keys, Codex auth tokens, or full auth JSON into the repo, Nix store, logs, chat transcript, or issues.
• For Docker, mount only the specific management key file and auth-files directory the monitor needs, and keep both mounts read-only; do not mount the whole home, .config, or unrelated secret directories.
• Keep the default bind at 127.0.0.1:4515; bind 0.0.0.0, set allowedHosts, and open the firewall only when LAN access is explicitly requested.
• For reverse-proxy access, keep the app on loopback and publish the dashboard at the root of a dedicated hostname such as https://quota.example/; do not configure path-prefix routing such as /quota/.
• If long-running service setup is unclear, do a foreground smoke test first and do not enable or switch a system service.
• Ask the agent to show the final changes, the commands it actually ran, and a short acceptance-output summary.

Copyable Task Pack

Please install and validate codex-quota-monitor for me.

Known facts:
- I already have a reachable CLIProxyAPI; do not install or manage CPA.
- management gateway 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 files dir: /path/to/auth-files
- keep the dashboard local-only by default on 127.0.0.1:4515
- use the default SQLite history unless I explicitly say otherwise
- do not configure benchmarkSummary or threshold alerts unless I provide exact values

Safety boundaries:
- do not write keys, tokens, or auth JSON contents into the repo, Nix store, logs, or reply body
- do not mount the whole home, .config, or unrelated secret directories
- do not expand LAN / public exposure unless I explicitly ask

Validation:
- prefer a reversible foreground smoke test first
- run cqm --version, print-config, and doctor
- after the service starts, check /healthz, /api/v1/status, and /api/v1/alerts
- report the actual commands, key output summary, and final URL

Install Path Hints

uv / Python is the best first-run path for validation and ordinary Linux foreground use:

Prefer uv tool install codex-quota-monitor==0.2.0.
If the tag is not published yet, use:
uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'
Run it in the foreground and complete smoke tests first; write a user/system service only if I explicitly ask.

Docker / Compose fits isolated runtime setups, Docker Desktop, or standardized container deployments:

For Docker, keep --read-only, --cap-drop=ALL, no-new-privileges, and read-only secret mounts.
Mount only /path/to/management-key as /management-key:ro and /path/to/auth-files as /auth-files:ro.
If the GHCR release image is not available yet, run docker build -t codex-quota-monitor:local . from the repository root.
For Compose, start from examples/docker-compose.yml and do not bind the host port to 0.0.0.0 by default.

NixOS is for users who already have a NixOS repo and want a declarative service:

If this is an existing NixOS repo, add the flake input github:<owner>/codex-quota-monitor,
import inputs.codexQuotaMonitor.nixosModules.default, and enable services.codexQuotaMonitor.
See docs/nixos-module.md for options and defaults; do not switch the live system unless I explicitly ask.

Acceptance Checks

Ask the agent to run or report these. Replace paths, ports, and hostnames with your deployment values:

cqm --version
cqm print-config
cqm doctor
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/alerts | jq '.'

If the agent enabled a systemd service, also check:

systemctl status codex-quota-monitor.service --no-pager

If LAN access is enabled, open http://<host-lan-ip>:4515/ from a phone or small-screen browser and confirm the page renders without full-page reload flicker.