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 init generates a burnguard.yaml file in your project directory by walking you through an interactive setup wizard. Once the file exists, you can edit it manually at any time — BurnGuard reads it fresh on every burnguard start. The file controls every aspect of the proxy: the port it listens on, the budget limit it enforces, which AI providers to route to, where to send alerts, and whether to sync usage to BurnGuard Cloud.

​
Generating the config file

1

Run the setup wizard

burnguard init
The wizard asks about your providers, budget limit, Slack/Discord webhooks, alert thresholds, and an optional cloud sync token. It writes burnguard.yaml to your current directory when finished.
2

Edit manually (optional)

Open burnguard.yaml in any text editor. Changes take effect the next time you run burnguard start.
3

Start the proxy

burnguard start

​
Full annotated example

burnguard.yaml
server:
  proxy_port: ":8080"       # TCP port the proxy listens on
  db_path: burnguard.db     # SQLite database file for persistent usage storage

budget:
  limit: 50.00              # Hard monthly cap in USD; set to 0 to disable enforcement

providers:
  anthropic:
    base_url: https://api.anthropic.com   # Route /anthropic/... requests here
  openai:
    base_url: https://api.openai.com      # Route /openai/... requests here

alerts:
  slack_webhook: "https://hooks.slack.com/services/..."   # Slack incoming webhook URL
  discord_webhook: ""                                      # Discord webhook URL (optional)
  thresholds:
    - 0.5   # Alert at 50% of budget
    - 0.8   # Alert at 80% of budget
    - 1.0   # Alert at 100% of budget (budget exhausted)

sync:
  enabled: true                          # Enable syncing usage to BurnGuard Cloud
  token: "bg_your_sync_token_here"       # Sync token from burnguard.run
  url: "https://api.burnguard.run"       # Cloud API base URL
  interval: 60                           # Sync every 60 seconds

​
server section

The server block configures the proxy listener and local storage.
​
server.proxy_port
string
default:"\":8080\""
The TCP address and port BurnGuard listens on. Must include the leading colon (e.g. ":8080"). Your application sends requests to http://localhost:8080 when this is the default.
​
server.db_path
string
default:"\"burnguard.db\""
Path to the SQLite database file used for persistent usage storage. BurnGuard creates this file automatically on first start. The path can be relative (resolved from the working directory) or absolute.

​
budget section

The budget block sets the hard monthly spend cap that BurnGuard enforces before forwarding any request.
​
budget.limit
float
required
Monthly spend cap in USD. When cumulative spend tracked in the SQLite database reaches this value, all further requests are blocked with HTTP 403 and never forwarded to the provider. Set to 0 to disable enforcement entirely (alerts will still fire if configured).

​
providers section

The providers block is a map of provider names to their upstream base URLs. Each key becomes a path prefix on the proxy — requests arriving at /anthropic/... are forwarded to the anthropic entry’s base_url, and so on.
​
providers.<name>.base_url
string
The upstream base URL for this provider. BurnGuard strips the provider path prefix and appends the remainder to this URL before forwarding. For example, a request to /anthropic/v1/messages with base_url: https://api.anthropic.com is forwarded to https://api.anthropic.com/v1/messages.

​
alerts section

The alerts block controls Slack and Discord webhook notifications and the budget fraction thresholds that trigger them.
​
alerts.slack_webhook
string
A Slack incoming webhook URL. When a threshold is crossed, BurnGuard POSTs a JSON payload {"text": "..."} to this URL. Leave empty to disable Slack alerts.
​
alerts.discord_webhook
string
A Discord webhook URL. When a threshold is crossed, BurnGuard POSTs a JSON payload {"content": "..."} to this URL. Leave empty to disable Discord alerts. Both Slack and Discord can be active at the same time.
​
alerts.thresholds
float[]
A list of budget fractions (0.0 – 1.0) at which to fire an alert. 0.5 means 50% of budget.limit, 1.0 means 100%. Each threshold fires at most once per proxy session — restarting the proxy resets all triggered states. The recommended set is [0.5, 0.8, 1.0].
Alert thresholds are tracked in memory, not in the database. Each threshold fires only once per proxy session. If you need alerts to re-arm after they have fired, restart the proxy with burnguard start.

​
sync section

The sync block controls whether the proxy ships usage records to BurnGuard Cloud for the web dashboard.
​
sync.enabled
boolean
default:"false"
Set to true to enable background syncing. When enabled, BurnGuard sends unsynced usage records to the cloud API at the configured interval and marks them as synced locally. Set to false (or omit the block) to keep everything local.
​
sync.token
string
The Bearer token sent in the Authorization header of every sync request. Get your token by signing up at burnguard.run. Tokens start with bg_.
​
sync.url
string
default:"\"https://api.burnguard.run\""
The base URL of the BurnGuard Cloud API. The syncer appends /v1/usage to this value when posting records. Only change this if you are running a self-hosted backend.
​
sync.interval
integer
default:"60"
How often (in seconds) the syncer wakes up to send unsynced records. At each tick, up to 100 unsynced records are batched and posted. The default of 60 means usage data reaches the dashboard within about one minute.
Never commit burnguard.yaml to version control if it contains a real sync token or webhook URLs. Add the file to .gitignore or use environment-variable substitution before committing. A leaked sync token gives anyone access to your BurnGuard Cloud account, and a leaked webhook URL allows others to spam your Slack or Discord channel.

Build docs developers (and LLMs) love

Get started for freeTalk to us