Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Verifieddanny/BurnGuard/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have the BurnGuard proxy running locally, a burnguard.yaml config generated by the interactive wizard, and your first AI request flowing through the proxy with live token counting and budget enforcement active.

​
Prerequisites

BurnGuard ships as a single statically compiled binary with no external runtime, no Docker, and no system dependencies. All you need is a terminal.

​
Installation

1

Install BurnGuard

Pick the method that matches your platform. All four options install the same binary.
brew tap verifieddanny/tap
brew install burnguard
The curl and PowerShell scripts download the latest release from GitHub, place the binary in /usr/local/bin (macOS/Linux) or %LOCALAPPDATA%\BurnGuard (Windows), and add it to your PATH automatically.Verify the install:
burnguard --help
# Usage: burnguard [init|start]
2

Run the setup wizard

The interactive init command asks you a handful of questions and writes a burnguard.yaml in your current directory. No YAML editing required.
burnguard init
The wizard walks you through:
  1. Provider selection — choose Anthropic, OpenAI, or both
  2. Monthly budget limit — a USD amount (default: 50.00)
  3. Cloud sync token — optional; paste a bg_... token from burnguard.run to enable the dashboard
  4. Slack webhook — optional; paste an incoming webhook URL for Slack alerts
  5. Discord webhook — optional; paste a Discord webhook URL
  6. Alert thresholds — choose which percentages trigger a notification (50%, 80%, 100% are pre-selected)
  7. Proxy port — the local port to listen on (default: 8080)
When the wizard finishes it writes a config file like this:
burnguard.yaml
server:
  proxy_port: ":8080"
  db_path: burnguard.db

budget:
  limit: 50.00

providers:
  anthropic:
    base_url: https://api.anthropic.com
  openai:
    base_url: https://api.openai.com

alerts:
  slack_webhook: "https://hooks.slack.com/services/..."
  discord_webhook: ""
  thresholds:
    - 0.5
    - 0.8
    - 1.0

sync:
  enabled: true
  token: "bg_your_sync_token_here"
  url: "https://api.burnguard.run"
  interval: 60
3

Start the proxy

burnguard start
On startup, BurnGuard:
  • Loads burnguard.yaml from the current directory
  • Opens (or creates) the SQLite database at the configured db_path
  • Reads the sum of all previous request costs from the database and seeds the in-memory budget tracker — enforcement picks up exactly where it left off
  • Starts the HTTP proxy on the configured port
  • Launches the background sync goroutine if sync.enabled is true
You should see output like:
2025/01/15 10:32:01 Database connection pool established
2025/01/15 10:32:01 Total spend so far: $0.000000
2025/01/15 10:32:01 Listening on :8080
2025/01/15 10:32:01 Sync started — every 1m0s to https://api.burnguard.run
4

Update your app to point at the proxy

Change one line in your application — the base URL. Your API key stays in your app exactly where it is and is forwarded transparently by BurnGuard.
# Before
client = Anthropic()

# After — point at the proxy's /anthropic prefix
client = Anthropic(base_url="http://localhost:8080/anthropic")
BurnGuard does not manage or store your AI provider API key. Your key must remain in your application as usual — BurnGuard forwards all headers, including Authorization and x-api-key, to the upstream provider unchanged. Never remove your key from your app.
5

Verify it's working

Fire a request from your app and watch the proxy logs. After each non-streaming response you will see a line like:
2025/01/15 10:32:14 [anthropic] Input: 142 Output: 87 Cost: $0.001842
For streaming responses, the log line appears when the stream closes:
2025/01/15 10:32:19 Stream — Input: 310 Output: 204 Cost: $0.004110
If your spend crosses an alert threshold, you will also see:
2025/01/15 10:35:00 Alert triggered: BurnGuard: Budget 50% used ($25.0000 of $50.0000)
Once you hit the budget limit, any further request will be blocked before it reaches the provider:
HTTP 403 Blocked!
Sign up at burnguard.run to get a sync token. Paste it into the init wizard (or add it to burnguard.yaml under sync.token) and the proxy will push your usage data to the cloud every 60 seconds. The dashboard shows total spend, a daily chart (7/30/90-day views), per-model cost breakdowns, and recent request logs.

​
Next Steps

How It Works

Understand the request flow, SSE streaming, budget middleware, and sync internals.

Configuration

Full reference for every field in burnguard.yaml.

Cloud Dashboard

Connect a sync token and explore the burnguard.run analytics UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us