👁️ VWatch

Know what your AI spends.

VWatch is an open-source AI API cost monitoring tool. Track spend, set budgets, cache duplicate requests, and get smart model recommendations — all through a local proxy.

Your team spends thousands on AI APIs with zero visibility into where the money goes. Prompts are bloated, responses are uncached, and nobody knows a single request just cost $5 until the monthly bill arrives. VWatch fixes that.

✨ Features

• 📊 Real-time spend tracking per model, project, and API key
• 💰 Budget controls with alerts — Slack, Discord, and custom webhooks; observe, warn, block, or auto-downgrade
• ⚡ Intelligent caching — identical requests return cached responses at zero token cost
• 🔄 OpenAI-compatible proxy — drop-in replacement, zero code changes
• 🧠 Smart model recommendations — "Switch to gpt-4o-mini, save $181/month"
• 📈 Dashboard with analytics and insights — spend overview, forecasts, optimization opportunities
• 🔑 Project & API key management — group usage by app, team, or client
• 🖥️ CLI tool — vwatch init, vwatch serve, vwatch status, vwatch demo, vwatch preflight
• 🐳 Docker support — one-command deployment with Docker Compose

🚀 Quick Start

pip install vwatch
vwatch init
vwatch serve

Point your AI SDK at http://localhost:8000 and start tracking.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",  # ← the only change
    default_headers={"X-VWatch-Key": "your-project-key"},
)

Then open http://localhost:8000/dashboard.

Install from source

git clone https://github.com/ScipionT2/VWatch.git
cd VWatch
python3 -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
vwatch init && vwatch serve

Want a populated dashboard without sending real traffic? Run vwatch demo --reset before vwatch serve.

🔍 How It Works

VWatch sits between your application and AI providers as a transparent proxy:

Your App ──▶ VWatch Proxy ──▶ OpenAI API
                 │
                 ├─ 💰 logs cost per request
                 ├─ ⚡ serves cached duplicates for free
                 ├─ 🚨 enforces budgets & fires alerts
                 └─ 📊 feeds the live dashboard

1. Swap your base URL — point any OpenAI-compatible SDK at VWatch instead of the provider.
2. Every request gets analyzed — token counts, cost, cache eligibility, budget impact, and cheaper-model alternatives.
3. You see everything — the dashboard shows spend by model and project, forecasts, cache savings, and actionable recommendations.

Everything runs locally. Your prompts and keys never leave your infrastructure.

⚙️ Configuration

Run vwatch init to create a .env from .env.example. Key settings:

Variable	Default	Description
OPENAI_API_KEY	—	Upstream key for proxy mode
PORT	8000	Server port
ALERT_DAILY_BUDGET	50.00	Daily budget in USD
BUDGET_MODE	observe	observe | warn | block | downgrade
ALERT_WEBHOOK_URL	—	Slack/Discord/custom webhook for alerts
ENABLE_CACHE_DEDUP	true	Cache identical requests
CACHE_TTL_SECONDS	3600	Cache lifetime
VWATCH_ADMIN_KEY	—	Protects admin/control-plane endpoints

For production deploys (Docker, Cloud Run, Nginx/HTTPS, custom domains), see DOMAIN.md and deploy/ — and run vwatch preflight before exposing a public instance.

Docker

docker compose up -d

🧪 Tests

python -m pytest tests/ -v

177 tests, all offline — no API keys required.

🏢 Built by VCorv

VWatch is built by VCorv — a technology company building tools for the AI era.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md to get started. Good first steps: add pricing for a new model, improve the dashboard, or expand provider support.

📄 License

MIT — see LICENSE.