oberwatch

README

Oberwatch

Open-source proxy, spend governor, and operational dashboard for AI agents.
Route agent traffic through one endpoint, track real model costs, enforce budgets, and keep a live control plane in front of your providers.

---

Why Oberwatch

AI agents are expensive, fast-moving, and easy to lose control of. Oberwatch puts a control layer in front of them:

• One proxy endpoint for agent traffic
• Per-agent spend tracking with real pricing tables
• Budget thresholds, alerts, downgrade paths, reject/kill enforcement
• Live dashboard for costs, agents, settings, and emergency controls
• SQLite-backed persistence for agents, costs, alerts, sessions, and runtime state
• First-run onboarding with single-user session auth

What Ships Today

Area	What you get
Proxy	OpenAI-compatible and Anthropic-style traffic routed through a single Oberwatch endpoint
Budgets	Per-agent and default budgets with alert, reject, downgrade, and kill actions
Alerts	Threshold alerts at configurable percentages, live dashboard toasts, webhook and Slack dispatch
Dashboard	Overview, Agents, Costs, and Settings pages with live SSE updates
Auth	First-run setup flow, login/logout, cookie sessions, password change
Persistence	SQLite storage for costs, alerts, agents, settings, and emergency stop state
Safety	Emergency stop that pauses agent traffic while keeping the management UI/API online
Pricing	Built-in pricing defaults plus config overrides, including streaming usage extraction

How It Works

Agent SDK / app
      |
      v
  Oberwatch proxy
      |
      +--> identifies agent
      +--> checks budget policy
      +--> forwards to provider
      +--> extracts token usage
      +--> calculates cost
      +--> stores spend + alerts + traces/state
      |
      v
 Dashboard + API + SQLite

Quick Start

One-line install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/OberWatch/oberwatch/main/scripts/install.sh | sh

Then open http://localhost:8080 to complete setup.

Docker

docker run -d -p 8080:8080 -v oberwatch-data:/data ghcr.io/oberwatch/oberwatch:beta

For preview testing, use the beta channel instead of the staging channel:

Docker Compose (for Enterprise Edition)

wget https://raw.githubusercontent.com/OberWatch/oberwatch/main/docker-compose.yml
# Edit to uncomment enterprise services and add license key
docker compose up -d

Build from source

git clone https://github.com/OberWatch/oberwatch.git
cd oberwatch
make build
./bin/oberwatch serve

Local development

git clone https://github.com/OberWatch/oberwatch.git
cd oberwatch
make dev

make dev is the default local workflow. It runs:

• the Go backend with air for automatic rebuild/restart
• the Svelte dashboard dev server with hot reload
• a proxy from /_oberwatch/* to http://localhost:8080

First-Run Experience

Oberwatch is designed to boot cleanly on a fresh machine or hosted platform.

1. Start the binary or container.
2. Open the dashboard.
3. Create the single admin account in the onboarding flow.
4. Sign in.
5. Point agents at the proxy URL shown by Oberwatch.

Management auth is session-based. After setup, the dashboard and management API use secure cookies instead of a shared dashboard token.

Pointing Agents At Oberwatch

Use Oberwatch as the base URL your agent runtime talks to, and send an agent identity header.

Example OpenAI-compatible request:

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Oberwatch-Agent: research-agent" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Summarize the latest sprint notes."}]
  }'

That agent name becomes the key for:

• budget enforcement
• cost tracking
• alerts
• dashboard visibility
• runtime controls such as reset, enable, rename, and kill

Budget Enforcement

Oberwatch can enforce both shared defaults and per-agent overrides.

Supported actions when spend crosses policy limits:

• alert
• reject
• downgrade
• kill

Current behavior includes:

• configurable threshold alerts, commonly 50, 80, 100
• automatic live dashboard notifications when thresholds are crossed
• persistent kill state for manual and runaway kills
• automatic recovery after period reset for budget-exceeded kills
• emergency stop across all agent traffic without taking the control plane offline

Dashboard

The embedded dashboard is part of the main binary.

Current pages:

• Overview for spend, active agents, alerts, uptime, and emergency stop
• Agents for runtime status, budget usage, edit panel, rename, kill/enable/reset
• Costs for totals, breakdowns, charts, and CSV export
• Settings for system health, provider status, pricing, and password change

The UI uses server-sent events for live updates, including:

• budget threshold toasts
• emergency stop changes
• cost refresh triggers
• live alert visibility

Pricing and Cost Calculation

Oberwatch tracks real costs instead of raw token counts alone.

It currently supports:

• built-in pricing defaults for OpenAI, Anthropic, and Google models
• config-based pricing overrides
• extraction of usage from standard response bodies
• streaming usage accumulation for providers that emit final usage data
• fallback estimation when providers omit usage entirely

Very small non-zero amounts are displayed with higher precision so sub-cent spend does not collapse to $0.00.

Configuration

Start with the example config:

• oberwatch.example.toml

You can run fully config-free, but a config file becomes useful when you want to define:

• explicit agent budgets
• downgrade chains
• alert thresholds
• upstream base URLs
• trace retention and SQLite paths
• webhook or Slack alert destinations

Environment variables override TOML using double-underscore nesting.

Examples:

export OBERWATCH_SERVER__PORT=8080
export OBERWATCH_GATE__ENABLED=true
export OBERWATCH_TRACE__STORAGE=sqlite

Production Deployment

If you expose Oberwatch on the public internet, put it behind a reverse proxy such as Caddy or Nginx and terminate TLS there.

Warning: Never expose Oberwatch without TLS in production. API keys pass through the proxy in request headers.

See production.md for the production deployment guide placeholder.

Deployment and Release Channels

Oberwatch publishes images across two registries with different intent.

Channel	Registry	Purpose
latest, 0.1, 0.1.0	Docker Hub + GHCR	Stable tagged releases
beta	GHCR	Preview build from main
staging	GHCR	Integration/staging build
sha-<commit>	GHCR	Immutable branch build for debugging and verification

Recommended usage:

• Production: oberwatch/oberwatch:0.1.0 or oberwatch/oberwatch:latest
• Preview testing: ghcr.io/oberwatch/oberwatch:beta
• Staging environments: ghcr.io/oberwatch/oberwatch:staging

CLI

Oberwatch ships as a Cobra-based CLI.

Primary commands:

• oberwatch serve
• oberwatch gate
• oberwatch trace
• oberwatch test run
• oberwatch validate
• oberwatch init
• oberwatch version

Repo Guide

Core paths:

• cmd/oberwatch - CLI entrypoint
• internal/api - management API and auth
• internal/proxy - provider proxy path
• internal/budget - budget tracking and enforcement
• internal/pricing - pricing engine and usage extraction
• internal/storage - SQLite persistence
• dashboard/svelte - Svelte dashboard source

Project docs:

• CONTRIBUTING.md
• BRANCHING.md
• SECURITY.md
• CHANGELOG.md
• AI_CODING.md
• CLAUDE.md

Contributing

See CONTRIBUTING.md for local setup, checks, commit conventions, and workflow details.

The short version:

make dev

Then before sending work upstream, run the same checks CI expects.

License

Oberwatch is licensed under the GNU Affero General Public License v3.0.

Copyright (C) 2026 Bouali Consulting Inc.