Bifrost — Plugins & Extensibility Reference

Status: Reference doc Last updated: 2026-09-14

This documents Bifrost’s extensibility surface as discovered while reviewing the full Helm chart schema (helm show values bifrost/bifrost) during install. The goal: before ever forking Bifrost’s source code to add a capability, check here — almost everything is already configurable via values.yaml + helm upgrade, no code change or rebuild required.

See bifrost-installation-as-built.md for how the current deployment is configured, and the official chart’s full default values (helm show values bifrost/bifrost) for the authoritative, up-to-date schema — this doc summarizes what existed as of chart 2.1.40 / app 1.5.12.

The three ways to extend Bifrost, in order of effort

Config, via values.yaml (no rebuild, no code) — covers almost everything below
Custom plugins (.so files) — for genuinely custom logic Bifrost doesn’t already expose as config
Forking the source — last resort; loses the simple upstream-upgrade path (helm upgrade to a new tag)

Built-in plugins (enable via `bifrost.plugins.<name>.enabled: true`)

All disabled by default. Each is a toggle plus a config block in values.yaml:

Plugin	What it does
`telemetry`	Prometheus `/metrics` scrape endpoint, optional push-gateway
`logging`	Content/header logging controls
`governance`	Virtual-key mandatory enforcement, required headers
`semanticCache`	Caches responses by semantic similarity of the prompt — configurable embedding provider/model, similarity threshold, TTL
`otel`	OpenTelemetry traces/metrics export (supports multiple named profiles, HTTP or gRPC)
`datadog`	APM traces + LLM Observability, agent or agentless mode
`bigquery`	Streams request traces to a BigQuery table
`kafka`	Publishes traces to a Kafka topic (SASL/TLS supported)
`pubsub`	Publishes traces to a GCP Pub/Sub topic
`splunk`	Sends events/metrics to Splunk HEC
`maxim`	Integration with Maxim’s own observability platform
`custom`	Load your own `.so` plugin binary — see below

Relevant to Router.Africa specifically: semanticCache could meaningfully cut provider costs on repeated/similar prompts once there’s real traffic volume — worth revisiting once usage patterns are visible. telemetry (Prometheus) is a cheap way to get real dashboards without adopting a heavier observability plugin.

MCP (Model Context Protocol) gateway

Bifrost can act as an MCP gateway — connecting to external MCP tool servers (stdio or HTTP/SSE) and exposing curated tool bundles (“Virtual MCPs”) to specific virtual keys. Configured under bifrost.mcp. Includes OAuth and token-exchange auth modes for enterprise IdP integration. Not currently used in this deployment — relevant if Router.Africa ever wants to offer agent/tool-calling capabilities as part of the product, not just raw chat completions.

Governance (budgets, rate limits, virtual keys, routing rules)

This is the layer that matters most for a billing product like Router.Africa, configured under bifrost.governance:

budgets — spend caps with configurable reset windows (30s up to 1Y, calendar-aligned or rolling)
rateLimits — token and request limits per window
customers / teams / virtualKeys — the actual multi-tenant structure: a virtual key can be scoped to a customer, given its own budget/rate-limit, and restricted to specific providers/models
routingRules — CEL-expression-based routing (e.g. “if model starts with gpt-, route to Azure, fall back to OpenAI”)
pricingOverrides — override the cost Bifrost calculates for a specific model/key, useful if you’re negotiating custom provider rates that differ from list price
complexityAnalyzerConfig — semantic classification of prompt complexity (simple/medium/complex) to support tiered routing — e.g. cheap model for simple prompts, frontier model for complex ones

This is worth a dedicated look once the billing ledger work resumes — virtualKeys + budgets + customers maps closely onto the “one currency balance per customer” model discussed in the business design doc. It may be worth building Router.Africa’s ledger on top of this rather than fully separately, rather than assuming it all needs to be built from scratch.

Guardrails

Content moderation / policy enforcement layer (bifrost.guardrails) — pluggable providers (e.g. GrayScale, Bedrock, Azure) with CEL-expression rules for which traffic gets scanned, on input/output/both, with configurable sampling rate. Not configured currently; relevant if content-safety requirements come up later.

Alerting & webhooks

bifrost.alerting — declarative alert channels (Slack, Teams, PagerDuty, generic webhook) with CEL-expression rules (e.g. “budget usage >= 80%”)
bifrost.webhooks — endpoint declarations for async job completion events

Both are zero-cost to configure later — pure values.yaml additions, no infra changes needed.

Custom plugins (`.so` files)

For logic Bifrost doesn’t expose as config at all. Referenced under bifrost.plugins.custom, pointing at a compiled .so file mounted into the pod. Requires building a dynamically-linked Bifrost binary (Bifrost’s docs cover this under “Building Dynamically Linked Bifrost Binary” / “Writing Plugins”). This is the middle ground between config and a full fork — worth trying before forking if a genuinely custom capability is needed.

Cluster mode (multi-node, Enterprise-relevant)

bifrost.cluster supports OSS multi-node via mesh (gossip) or broker transport, with Kubernetes/DNS/Consul/etcd/mDNS-based peer discovery. Important, already covered in the install doc’s Section 14 equivalent: OSS multi-node still requires the shared config.json pattern (not config_store) to avoid configuration drift between nodes — cluster mode here is about request-level coordination (e.g. governance counter sync via gRPC), not a workaround for that limitation.

SSO / SCIM (Enterprise)

bifrost.scim supports Okta, Entra, Keycloak, Zitadel, Google Workspace, and generic OIDC, with attribute-to-role/team mapping and SCIM inbound provisioning. Not relevant until there’s an internal team large enough to need SSO rather than the single dashboard admin account currently in place.

What this means practically for Router.Africa

Resolved 2026-09-19: Router.Africa keeps its own Postgres ledger for money and uses Bifrost governance for enforcement — each API key maps 1:1 to a virtual key, giving per-key rate limits, budgets and model allowlists. See architecture/decisions-log.md (Ledger source of truth, API key ↔ Bifrost virtual key mapping). The paragraph below is the original open question, kept for context.

The chart’s governance layer (virtual keys, budgets, customers, pricing overrides) is more capable than what a first read of the business/design docs assumed needed to be custom-built. Before writing a bespoke billing ledger from scratch, worth explicitly evaluating: how much of “customer has a currency balance, spends it per request, gets cut off at zero” can Bifrost’s own virtualKeys + budgets + pricingOverrides already do, versus what genuinely needs Niobi-side custom logic on top. This doesn’t change anything about the Niobi payment integration itself, but could meaningfully shrink the custom engineering surface on the Bifrost-facing side.