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.

BurnGuard protects against runaway AI spend through two complementary layers. The first layer is a set of soft alerts: when cumulative spend crosses a configured fraction of your budget, BurnGuard fires a Slack or Discord notification so you can take action early. The second layer is a hard block: once total spend reaches budget.limit, every subsequent request is rejected with HTTP 403 before it ever leaves your machine — no tokens are consumed and no charges are incurred.

​
Budget enforcement

BurnGuard’s BudgetGuard middleware checks the in-memory spend tracker before forwarding every request to the provider. If the tracker reports that total spend has reached or exceeded the configured limit, the request is blocked immediately.

​
How the check works

When a request arrives, the tracker compares totalSpend against budgetLimit using a mutex-protected read. If totalSpend >= budgetLimit, BurnGuard returns an HTTP 403 to your application and drops the request. The provider never receives it, so you are not charged.

​
What your app sees

HTTP 403 Blocked!
Your application receives an HTTP 403 response with the body text Blocked!. Any error handling or retry logic in your code will run, but further retries will also return 403 until you reset the budget (see below).

​
Persistence across restarts

BurnGuard stores every usage record in the SQLite database at server.db_path. On startup it loads the cumulative spend from the database and initialises the in-memory tracker with that total. This means budget enforcement survives restarts: if you have spent $45 of a $50 limit and restart the proxy, it will still block requests once spend reaches $50.

​
How to reset enforcement

You have two options:
  1. Delete the database file — removes all stored spend history. The proxy starts fresh from $0.
  2. Increase budget.limit in burnguard.yaml and restart — raises the ceiling without losing history.
burnguard.yaml
budget:
  limit: 100.00   # Raised from 50.00
Setting budget.limit to 0 disables enforcement entirely. The proxy will forward every request regardless of accumulated spend. Alert thresholds will also not fire because the alerter checks if budget <= 0 and returns early. Only set limit: 0 if you intentionally want metering without enforcement.

​
Alert thresholds

Thresholds are decimal fractions of budget.limit in the range 0.0–1.0. When cumulative spend crosses a threshold, BurnGuard logs the event and fires webhook alerts to any configured destinations.

​
How thresholds are evaluated

After every request the alerter divides spent by budget to get a ratio, then iterates through the thresholds list. If the ratio is greater than or equal to a threshold value and that threshold has not already fired this session, the alert triggers and the threshold is marked as triggered.

​
Threshold state and resets

Triggered state is stored in memory, not in the database. Each threshold fires exactly once per proxy session. Restarting burnguard start resets all triggered flags, so thresholds will fire again if spend still exceeds them at startup.
burnguard.yaml
alerts:
  thresholds:
    - 0.5   # Alert at 50% of budget
    - 0.8   # Alert at 80% of budget
    - 1.0   # Alert at 100% of budget (budget exhausted)
The default set gives you an early warning at 50%, an urgent warning at 80%, and a final notification at the moment the hard cap is hit.

​
Slack alerts

​
Getting a Slack webhook URL

Create an incoming webhook for your workspace at api.slack.com/messaging/webhooks. Slack will give you a URL starting with https://hooks.slack.com/services/....

​
Configuration

burnguard.yaml
alerts:
  slack_webhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX"
  thresholds:
    - 0.5
    - 0.8
    - 1.0

​
Alert message format

BurnGuard sends a plain-text message with the percentage used and the raw dollar amounts: 
BurnGuard: Budget 80% used ($40.0000 of $50.0000)
The payload sent to Slack is: 
{
  "text": "BurnGuard: Budget 80% used ($40.0000 of $50.0000)"
}

​
Discord alerts

​
Getting a Discord webhook URL

Open your Discord server settings, navigate to Integrations → Webhooks, and create a new webhook for the channel you want to receive alerts. Discord will give you a URL starting with https://discord.com/api/webhooks/....

​
Configuration

burnguard.yaml
alerts:
  discord_webhook: "https://discord.com/api/webhooks/0000000000000000000/XXXXXXXXXXXX"
  thresholds:
    - 0.5
    - 0.8
    - 1.0

​
Alert message format

The message text is identical to Slack. The payload sent to Discord uses the content field: 
{
  "content": "BurnGuard: Budget 80% used ($40.0000 of $50.0000)"
}

​
Using Slack and Discord together

You can set both slack_webhook and discord_webhook at the same time. When a threshold fires, BurnGuard sends the alert to every non-empty webhook destination in a single call to send. Both your Slack channel and your Discord channel will receive the notification simultaneously.
burnguard.yaml
alerts:
  slack_webhook: "https://hooks.slack.com/services/..."
  discord_webhook: "https://discord.com/api/webhooks/..."
  thresholds:
    - 0.5
    - 0.8
    - 1.0
Webhook requests are dispatched with go a.send(message) — they run in a background goroutine and do not block the proxied request. Even if your Slack or Discord endpoint is slow or temporarily unavailable, the latency of the original AI API call is not affected.

Build docs developers (and LLMs) love

Get started for freeTalk to us