BLOCK 4 · AI GATEWAY (PRODUCTION) 3:30 – 3:43 · 13 min · 5L / 8HO · Lab

TOPIC 4.5 / 10 · HO #4 + STORAGE CHECK

Budget + storage check

Attach a budget — your circuit breaker. Then take three minutes to look at where the workshop's Bifrost actually lives on disk — the production-grade persistence behind everything you've built so far.

4.5

Budget — the circuit breaker

10 min 3L / 7HO 3:30 – 3:40

Slide 1 / 3 · Budgets compose three ways

Where budgets attach

TEAM SCOPING               (a VK can belong to a team — inherits team-level caps)
   └── VIRTUAL KEY         (each VK carries its own budgets[] — multiple caps, different reset windows)
        └── PROVIDER CONFIG  (a VK can also cap per-provider — e.g., $50/h OpenAI, $200/h Anthropic)

Multi-budget per VK — one VK can have $50/day AND $1000/month simultaneously (v1.5.0+ — budgets are an array)
Per-provider caps inside a VK — useful when one VK fans across providers with different cost profiles
Team scoping — VKs that share a team_id inherit team budgets

Bifrost evaluates every cap that touches the request; first one hit wins.

Slide 2 / 3 · 402 Payment Required

When a cap trips

Bifrost returns HTTP 402
Body includes which cap tripped and which scope
The gateway is your circuit breaker
Runaway loop hits one VK's cap, not your whole infra

📋 Dry-run capture target: exact 402 JSON shape → Block 4 - 402 response sample.md

Slide 3 / 3 · Five clicks to budget attached

HO #4 — Attach a budget (7 min)

Sidebar → Models → Budgets & Limits
Create Budget
Name: workshop-vk-budget · limit: $0.50 · reset: 1h
Scope: attach to workshop-vk-1 (the VK from 4.4)
Save → confirm budget appears active

Speaker notes

Slide 1 — budgets compose three ways: "Bifrost budgets attach in three places, and they all compose. First — the VK itself. Each VK carries a budgets array — that's plural. You can stack $50 a day and $1,000 a month on the same key, and Bifrost evaluates both. First one to trip wins. Second — provider configs inside a VK. If one VK fans across OpenAI and Anthropic with very different cost profiles, you can cap them separately. Third — team scoping. If a VK has a team_id, it inherits team-level budgets too. The strictest cap closest to the work is the right pattern — runaway loops trip a small cap, not your whole infrastructure."

Slide 2 — the 402: "When a cap trips, Bifrost returns HTTP 402 Payment Required. The body tells you which cap tripped. This is your circuit breaker. We'll see this surface in Block 4.9 when we send rapid messages from Nuxt until the cap is hit."

Slide 3 — HO: "Seven minutes. Budgets & Limits → Create. Fifty cents, one-hour reset, attached to workshop-vk-1. We're going small because we want to hit it later in 4.9 — production caps are larger, but the mechanism is identical."

Demo piece — Attendees

Click sequence:

Sidebar → Models → Budgets & Limits
Create Budget
Form: Name workshop-vk-budget, Limit $0.50, Reset interval 1h
Scope: Attach to VK → workshop-vk-1
Save

Optional micro-demo (~60s if time): instructor hits the gateway via curl with the VK; watches the budget tick up in real time in the dashboard.

curl -s -X POST localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $WORKSHOP_VK" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-4-6","messages":[{"role":"user","content":"hello"}]}' \
  | jq '.usage'

Then refresh the Budgets view — usage incremented.

4.5.5

Where it all lives

3 min 2L / 1HO 3:40 – 3:43 ★ LOAD-BEARING (storage model)

Slide 1 / 3 · Two layers, three modes

Bifrost's two config layers

Layer	What it holds	Behavior
`config.json` (file)	Storage backends, encryption key, plugins (e.g. semantic_cache), `$schema` header, and optionally providers + governance for bootstrap	File-based. Edit → restart to load.
`config_store` (SQLite default)	Providers, Virtual Keys, governance rules, prompts — runtime mutable	UI-driven. Writes go to SQLite. Survives restarts.

Everything you did in Beats 4.2–4.5 is in config_store. It's already persisted.

Three operating modes:

Mode	`config_store.enabled`	What goes where	When to use
Pure UI (workshop default)	`true`, file is minimal	All providers + governance via dashboard	Fastest start; the UI is the source of truth
Bootstrap + UI	`true`, file has providers + governance	File seeds an empty `config_store` on first run; UI takes over after	Reproducible bring-up; infra-as-code feel for the bootstrap, UI for daily edits
File-only	`false` (UI disabled)	Everything in `config.json`; restart-to-change	Multi-node clusters; declarative-only shops

Precedence rule: If config_store has data, the file's providers/governance are ignored after first run.

Slide 2 / 3 · Where it lives on disk

Workshop-local storage: `./bifrost/`

./bifrost/                ← Beat 4.1.3 set this via --app-dir
├── config.json           ← plugins (semantic_cache); restart-to-load
├── config.db             ← providers, VKs, budgets, routing rules, prompts (SQLite)
├── config.db-shm         ← SQLite shared-memory (WAL mode)
├── config.db-wal         ← write-ahead log
├── logs.db               ← LLM request/response logs (separate SQLite)
└── logs.db-shm / logs.db-wal

Defaults note: If --app-dir is NOT specified, Bifrost uses the OS config directory — ~/.config/bifrost/ on macOS/Linux. We chose workshop-local so attendees with pre-existing Bifrost installs don't collide.
Production note: SQLite is the default for single-node OSS. The storage swap (SQLite → PostgreSQL via config_store.type: "postgres" in config.json) is the foundation real production deployments build on. Same UI, different backend — invisible to attendees' app code.

Slide 3 / 3 · Verify (60-second HO)

Restart-safe by default

Ctrl-C your Bifrost terminal
npm run bifrost again
Refresh the dashboard
Providers · VK · budget · all still there

"Restart-safe by default. That's production-grade behavior, not an accident."

Production-tier callout: OSS gives you this on day one. A real production deployment runs on Bifrost Enterprise — same persistence model, plus clustering (multi-node), SSO / OIDC (Okta, Entra, Google, GitHub), Vault for API key management, RBAC + team-level governance, and in-VPC deployment. The mental model you're learning now is what scales up.

Speaker notes

Slide 1 — name the split: "Bifrost has two config layers. config.json — the file you started it with — holds storage backends, encryption key, and plugins. That's the layer you'll see in a few minutes when we talk about the semantic_cache plugin. config_store — by default a SQLite database — holds everything you've been creating in the UI: providers, virtual keys, governance rules. Two layers, two behaviors. The file requires restart to reload. The database persists automatically."

Slide 1 — three modes: "And there are three operating modes you'll see in production. Pure UI — what we're doing today. config.json is minimal, dashboard is the source of truth. Fastest to get started. Bootstrap + UI — providers and governance go in config.json, which seeds an empty config_store on first run. After that, the UI takes over for daily edits, but you've got a reproducible bring-up artifact. This is what most production teams settle into. File-only — config_store.enabled: false. UI is disabled. Everything is declarative in config.json, every change is a restart. This is the multi-node cluster pattern from Beat 4.8.E — when you can't have one node's UI edits drift away from the others'. Precedence rule to remember: if config_store already has data, the file's providers and governance are ignored. The file seeds the empty store; it doesn't override a populated one. There's a sample full config.json in the appendix — talk through it with your team when you're picking a mode."

Slide 2 — show the disk: "Both stores live inside the workshop's ./bifrost/ folder — because back in Beat 4.1.3 we started Bifrost with --app-dir ./bifrost. That flag is the reason your state isn't in ~/.config/bifrost. config.db is your providers, VKs, budgets, routing rules, prompts. logs.db is your observability data — every request and response, separate database so logs growth doesn't bloat config queries. SQLite is the default. When you outgrow single-node SQLite — when you need shared state across a cluster — you swap the storage type in config.json to PostgreSQL. Same code, same UI, different backend. That's how Bifrost scales to enterprise without anyone rewriting their app."

Slide 3 — verify it: "Sixty seconds. Stop Bifrost. Start it again. Refresh the dashboard. Every provider, every key, every budget you created — still there. Restart-safe by default. That's production-grade behavior, not an accident."

Slide 3 — production-tier framing: "One more frame before we move on. What you just verified is OSS Bifrost's day-one behavior, and it's already production-grade. But when this is the gateway in front of a real production application, the working assumption is you're at the Enterprise tier. Same Bifrost, same persistence model — plus clustering across nodes, SSO with Okta or Entra, Vault for API keys, RBAC and team governance, in-VPC deployment. We're not demoing Enterprise features today — but every muscle you build in this workshop transfers straight up. OSS teaches the model. Enterprise is what you run when the model is supporting real traffic."

Stage direction: make the restart real — let attendees see the Bifrost terminal shut down and boot back up. The "everything's still there" moment is what sells it. Don't talk through the restart; let the dashboard refresh be the punchline.

Demo piece

Instructor terminal — show the storage on disk (from workshop repo root):

ls -la ./bifrost/

You should see config.json (the file Beat 4.8.F references for the semantic_cache plugin entry), plus config.db, config.db-shm, config.db-wal, logs.db, logs.db-shm, logs.db-wal. The -shm and -wal files are SQLite's write-ahead-log machinery — they appear when the database is open. "Workshop-local — because we passed --app-dir ./bifrost. Without that flag, this state would be in ~/.config/bifrost/ and we'd be sharing it with any other Bifrost on this machine. Isolated state is a workshop choice; defaults are fine for production where one machine runs one Bifrost."

Attendee restart cycle:

# In your Bifrost terminal
Ctrl-C

# Then:
npm run bifrost

Refresh the browser tab on localhost:8080. Confirm everything's still there.

Production scaling reference (for Q&A if asked, or for Beat 4.8.E Cluster Config callback):

{
  "$schema": "https://www.getbifrost.ai/schema",
  "config_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "env.PG_HOST",
      "port": "5432",
      "user": "env.PG_USER",
      "password": "env.PG_PASSWORD",
      "db_name": "bifrost",
      "ssl_mode": "require"
    }
  }
}

Source: docs.getbifrost.ai/deployment-guides/config-json/storage