TokenGuard

Financial firewall for LLM API calls. Sit TokenGuard between your app and providers (OpenAI, Anthropic, OpenRouter, Groq, and other OpenAI-compatible APIs). It estimates cost, enforces per-user budgets, detects agent loops, tracks usage, and only then forwards safe requests.

Your App → TokenGuard → budget / loop / cost checks → Provider

Quick start

Smoke test (no Turso / Redis)

$env:TOKENGUARD_GUARD_ENABLED='false'
$env:TOKENGUARD_LISTEN_ADDR='127.0.0.1:18080'
$env:TIKTOKEN_CACHE_DIR='.tiktoken-cache'

go run ./cmd/tokenguard

Invoke-WebRequest http://127.0.0.1:18080/healthz -UseBasicParsing

Guarded mode

1. Copy .env.example to .env and fill Turso + Upstash credentials.
2. Ensure models you use exist in the pricing catalog (OpenRouter sync is on by default; pricing.json is optional bootstrap).
3. Build and run:

go build -o tokenguard.exe ./cmd/tokenguard
.\tokenguard.exe

4. Provision a user (mgmt enabled) and call providers through TokenGuard — see HOW_TO_USE.md.

Automated tests

go test ./...              # unit + offline integration
go test ./test/... -count=1  # static JSON e2e suite only

Fixtures: testdata/. Suite: test/ (httptest mocks, no Turso/Redis).

Showcase site

Product marketing lives in web/ (Next.js) — separate from the embedded /dashboard. See web/README.md.

Documentation

Doc	Description
HOW_TO_USE.md	Full setup, providers, budgets, dashboard
WHY_THIS_STACK.md	Why Go, Turso, Upstash, and the rest
docs/INDEX.md	Docs map
docs/PRODUCT.md	What it is for and who uses it
docs/ARCHITECTURE.md	Request flow and packages
docs/DESIGN.md	Design decisions
docs/STACK.md	Tech stack
docs/STRUCTURE.md	Repo layout
docs/API.md	HTTP routes and headers
docs/DEPLOY.md	Deploy on Render
docs/INTEGRATION.md	Connect SDKs and apps
AGENTS.md	Guidance for coding agents

For developers (after deploy)

URL	Purpose
/docs	Public how-to (no secret)
/portal	Product sign-in + API keys (when portal enabled)
/dashboard	Operator console (admin secret)
/v1/tokenguard.json	Machine-readable discovery
/healthz	Liveness

Stack (short)

Go 1.24 · Turso (libSQL) · Upstash Redis REST · tiktoken · Next.js (web/)

License

See repository owners for licensing terms.