# onWatch

**AI API quota monitor — track usage and spending across multiple providers in one local dashboard.**

- **Official site:** https://onwatch.onllm.dev
- **GitHub:** https://github.com/onllm-dev/onwatch
- **License:** GPL-3.0

## What It Is

onWatch is a lightweight background agent (Go binary, <50 MB RAM) that polls AI API providers for quota and usage data, stores history in SQLite, and serves a Material Design 3 web dashboard. It bridges the gap between point-in-time snapshots and the historical, per-cycle, cross-session view developers need to avoid surprise throttling or budget overruns.

**Supported providers:** Anthropic, OpenAI Codex, GitHub Copilot, MiniMax, Gemini CLI, Cursor, Z.ai, Synthetic, Antigravity

**Zero telemetry. All data stays on your machine.**

## Compatible Combos

| Infra | Runtime | Notes |
|-------|---------|-------|
| Any VPS/VM / workstation | Docker Compose | Build from source; no pre-built image |
| macOS / Linux | Binary | One-line installer or Homebrew |
| Windows | Binary | PowerShell installer or `.bat` |

## Inputs to Collect

### All phases
- API keys for each provider you want to monitor (set in `.env`)
- Port for the web dashboard (default: `9211`)
- Path for SQLite database persistence

## Software-Layer Concerns

- **Stack:** Go 1.25+ binary; SQLite for storage; Material Design 3 web dashboard
- **Config:** `.env` file (generated by interactive setup wizard `onwatch setup`)
- **Data:** SQLite at `ONWATCH_DB_PATH` (default: `/data/onwatch.db` in Docker)
- **Docker:** Build from source — no official pre-built image on Docker Hub/GHCR; use the provided `Dockerfile`

### Key environment variables (from `.env`)
```
ONWATCH_PORT=9211
ONWATCH_DB_PATH=/data/onwatch.db
# Add provider API keys:
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GITHUB_TOKEN=...   # for Copilot
```

### docker-compose.yml
```yaml
services:
  onwatch:
    build: .
    image: onwatch:latest
    container_name: onwatch
    restart: unless-stopped
    ports:
      - "${ONWATCH_PORT:-9211}:9211"
    volumes:
      - ./onwatch-data:/data
    env_file:
      - .env
    environment:
      ONWATCH_DB_PATH: /data/onwatch.db
```

> **Pre-create data dir:** `mkdir -p ./onwatch-data && chown -R 65532:65532 ./onwatch-data`

## Upgrade Procedure

1. `git pull` to fetch the latest source
2. Rebuild: `docker compose build --no-cache`
3. Restart: `docker compose up -d`
4. Verify dashboard loads at `http://localhost:9211`

## Gotchas

- **Build from source:** No pre-built Docker image is published — you must clone the repo and run `docker compose build`
- **Data dir ownership:** The container runs as UID 65532 (nonroot); pre-create `./onwatch-data` and set correct ownership before first launch
- **Beta software:** Active development; APIs and config schema may change between versions
- **Binary installs:** The one-line curl installer and Homebrew tap are the easiest path on macOS/Linux if Docker is not needed

## References

- README: https://github.com/onllm-dev/onwatch/blob/main/README.md
- Site: https://onwatch.onllm.dev
