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 start is the main runtime command. It reads burnguard.yaml from the current directory, opens the SQLite database, restores historical spend so budget tracking survives restarts, and begins accepting HTTP traffic on the configured port — forwarding every request to the appropriate upstream AI provider while counting tokens and enforcing your budget cap.

​
Usage

burnguard start
# or just:
burnguard
Running the binary with no arguments is equivalent to burnguard start. Both forms fall through to the same proxy startup path in main.go.

​
What happens on startup

1

Locate burnguard.yaml

BurnGuard looks for burnguard.yaml in the current working directory. If the file does not exist the process exits immediately with a fatal error — see Error conditions below.
2

Load and parse config

The YAML file is read and unmarshalled into the internal Config struct. A parse error (invalid YAML, wrong types) is also fatal.
3

Open the SQLite database

BurnGuard opens (or creates) the SQLite database at the path given by server.db_path. The database stores every proxied request along with its token count and cost.
4

Initialise the database schema

db.Init runs the schema migration that creates the requests table if it does not already exist. This is idempotent and safe to run against an existing database.
5

Restore historical spend

BurnGuard queries the database for total lifetime spend:
SELECT COALESCE(SUM(cost), 0) FROM requests
The result is used to seed the in-memory budget tracker, so your current-month spend is accurate across proxy restarts.
6

Initialise the budget tracker

An in-memory Tracker is created with the restored spend total and the budget.limit from config. Every proxied request increments this tracker in real time.
7

Create the alerter

The alerter is initialised with the Slack webhook, Discord webhook, and threshold list from alerts in config. It fires notifications when spend crosses a threshold percentage of the budget limit.
8

Start the reverse proxy

The proxy handler is registered on the default http.ServeMux behind a BudgetGuard middleware that blocks requests once the hard cap is reached. The server starts listening on server.proxy_port.
9

Start cloud sync (if enabled)

If sync.enabled is true, a background goroutine is launched that pushes request records to the BurnGuard Cloud API (sync.url) every sync.interval seconds.

​
Expected startup output

Database connection pool established
Total spend so far: $12.345678
Listening on :8080
Sync started — every 60s to https://api.burnguard.run
The sync line is only printed when sync.enabled: true. The spend figure reflects the sum of all rows in the requests table at boot time.

​
Error conditions

MessageCauseFix
No burnguard.yaml found. Run 'burnguard init' first.Config file is missing from the current directoryRun burnguard init or cd to the directory that contains burnguard.yaml
Database open / init errorBurnGuard cannot create or open the file at server.db_pathCheck that the directory exists and the process has read/write permission on that path
YAML parse errorburnguard.yaml contains invalid syntax or wrong value typesValidate the file against the burnguard.yaml reference
All startup errors are fatal — the process exits with a non-zero code and prints the error via log.Fatal. There is no partial startup.

​
Stopping the proxy

Send SIGINT (Ctrl+C) or SIGTERM to the process to stop the proxy. The proxy binary uses a bare log.Fatal(http.ListenAndServe(...)) call with no signal handler and no graceful-shutdown logic. In-flight requests are terminated immediately when the process exits.
There is no graceful drain. If your application has long-running AI API calls in flight when the proxy is stopped, those requests will be interrupted. For production use, consider placing the proxy behind a load balancer that can drain connections before signalling the process.

​
Running as a background service

For long-running deployments you will want the proxy managed by your operating system’s service supervisor.

​
macOS — launchd

Create ~/Library/LaunchAgents/run.burnguard.plist: 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>             <string>run.burnguard</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/burnguard</string>
    <string>start</string>
  </array>
  <key>WorkingDirectory</key>  <string>/path/to/your/project</string>
  <key>RunAtLoad</key>         <true/>
  <key>KeepAlive</key>         <true/>
  <key>StandardOutPath</key>   <string>/tmp/burnguard.log</string>
  <key>StandardErrorPath</key> <string>/tmp/burnguard.err</string>
</dict>
</plist>
Then load it: 
launchctl load ~/Library/LaunchAgents/run.burnguard.plist

​
Linux — systemd

Create /etc/systemd/system/burnguard.service: 
[Unit]
Description=BurnGuard AI reverse proxy
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/burnguard start
WorkingDirectory=/path/to/your/project
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
Enable and start: 
sudo systemctl daemon-reload
sudo systemctl enable --now burnguard
During local development, use Air for hot-reload. Create an .air.proxy.toml that points cmd at burnguard start and root at your project directory — Air will restart the proxy automatically whenever you edit burnguard.yaml.

​
Port conflicts

If port 8080 is already in use you will see: 
listen tcp :8080: bind: address already in use
To resolve this, open burnguard.yaml and change server.proxy_port: 
server:
  proxy_port: ":9090"
Then update every base_url reference in your application to point to the new port (e.g. http://localhost:9090/anthropic/v1/messages).

Build docs developers (and LLMs) love

Get started for freeTalk to us