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.

The BurnGuard proxy binary runs entirely on your local machine and works without any cloud component — but the backend API and Next.js dashboard that power the usage charts and team features can also be self-hosted. You might choose this path for data privacy requirements, compliance restrictions on sending usage data to third-party services, or to run BurnGuard on a custom domain inside your organization’s infrastructure.

​
Architecture

A fully self-hosted BurnGuard deployment consists of three independent programs:
ComponentTechnologyPurpose
ProxyGo binary + SQLiteRuns locally, intercepts AI API calls, enforces budgets
Backend APIGo + PostgreSQLReceives synced usage data, serves the dashboard API
DashboardNext.jsWeb UI for analytics, budget configuration, and team access
The proxy binary is always local. Self-hosting adds the backend API and dashboard alongside a PostgreSQL database.

​
Prerequisites

Before you start, make sure the following tools are installed:
  • Go 1.23+ — required to build and run the backend API
  • Node.js 20+ — required for the Next.js dashboard
  • Docker and Docker Compose — used to run PostgreSQL locally
  • golang-migrate CLI — used to apply database migrations

​
Start PostgreSQL

The repository includes a docker-compose.yml that starts a PostgreSQL 16 instance with the credentials the backend expects by default. 
docker compose up -d
This creates a container named bunguard-db listening on localhost:5432 with the database bunguard, the user bunguardadmin, and the password bunguardadminpassword. Data is persisted in the named volume db_data.

​
Run Database Migrations

With PostgreSQL running, apply all schema migrations: 
make migrate-up
This runs every SQL file in internal/migrations/ in sequence using golang-migrate. The Makefile reads the DATABASE_URL from your .envrc file (see the next section), so make sure that file exists before running this command. To roll back all migrations: 
make migrate-down

​
Configure Environment Variables for the Backend

Create a .envrc file in the repository root with the following variables. If you use direnv, run direnv allow after saving the file; otherwise export the variables manually or source the file directly. 
DATABASE_URL=postgres://bunguardadmin:bunguardadminpassword@localhost:5432/bunguard?sslmode=disable
PORT=3001
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
FRONTEND_URL=http://localhost:3000
WEBAUTHN_RP_ID=localhost
VariableDescription
DATABASE_URLPostgreSQL connection string. Must match the credentials in docker-compose.yml.
PORTPort the backend API listens on. Defaults to 3001 if unset.
GITHUB_CLIENT_IDOAuth App client ID from github.com/settings/developers. Required for GitHub sign-in.
GITHUB_CLIENT_SECRETCorresponding secret for the GitHub OAuth App.
GOOGLE_CLIENT_IDOAuth 2.0 client ID from the Google Cloud Console. Required for Google sign-in.
GOOGLE_CLIENT_SECRETCorresponding secret for the Google OAuth client.
FRONTEND_URLOrigin of the Next.js dashboard. Used for CORS and OAuth redirect validation.
WEBAUTHN_RP_IDThe Relying Party ID for WebAuthn passkeys. Must be the hostname of the page where passkeys are registered — localhost for local development.

​
Start the Backend API

# Standard start
make dev-server

# With Air for live reload on file changes
air -c .air.server.toml
The backend will be available at http://localhost:3001. You can verify it is running by opening that URL in a browser — a 404 or JSON response from the API confirms it is alive.

​
Configure the Frontend

Create a .env.local file inside the web/ directory: 
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_MAX_AGE=604800
VariableDescription
NEXT_PUBLIC_API_URLFull URL of your self-hosted backend API.
NEXT_PUBLIC_APP_URLPublic URL of the Next.js dashboard itself. Used for absolute links and OAuth redirects.
NEXT_PUBLIC_MAX_AGESession cookie max-age in seconds. Defaults to 604800 (7 days) if unset.

​
Start the Dashboard

cd web && npm install && npm run dev
The dashboard will be available at http://localhost:3000. On first load, sign in using GitHub OAuth, Google OAuth, or a WebAuthn passkey (Touch ID / Face ID / Windows Hello), depending on which OAuth credentials you have configured.

​
Configure the Proxy to Use Your Self-Hosted Backend

Open your burnguard.yaml and point sync.url at your local backend instead of the public BurnGuard cloud: 
sync:
  enabled: true
  token: "bg_your_sync_token"
  url: "http://localhost:3001"  # your self-hosted backend
  interval: 60
Restart the proxy after saving: 
burnguard start
The proxy will now sync usage data to your self-hosted backend every 60 seconds (or whatever interval you set). Generate a sync token by signing in to your self-hosted dashboard and creating one from the token management page.

​
Production Deployment

For production, build and run the backend using the included Dockerfile: 
docker build -t burnguard-api .
docker run -p 3001:3001 --env-file .env burnguard-api
The image uses a two-stage build: a golang:1.26-alpine builder compiles the binary, and a minimal alpine:3.19 runtime image runs it. The entrypoint.sh script runs pending migrations automatically before starting the server, so no separate migration step is needed in a containerised deployment. For the Next.js dashboard, run a standard npm run build && npm start or deploy to any platform that supports Node.js (Vercel, Railway, Fly.io, etc.) with the two NEXT_PUBLIC_* environment variables set to your production URLs.
Set WEBAUTHN_RP_ID to your actual production domain (for example, app.yourcompany.com) before users register passkeys. WebAuthn binds credentials to the Relying Party ID at registration time — passkeys created under localhost will not work on your production domain, and vice versa. If you change WEBAUTHN_RP_ID after users have registered passkeys, those credentials become invalid and users will need to re-register.
For GitHub and Google OAuth, register separate OAuth Apps (or OAuth clients) for your production domain and update GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET in your production environment. Set the authorized redirect URIs to https://your-production-domain.com/api/auth/callback/github and the equivalent Google callback URL.

Build docs developers (and LLMs) love

Get started for freeTalk to us