OSS vs PRO: capability matrix

A precise, feature-by-feature map of what the free open-source core does on its own and what the PRO package adds. If you are deciding which tier you need, start with the tier model — this page is the detailed reference it points to.

Baldur is one library with one API (@baldur.protected). OSS is the free, Apache-2.0 core (pip install baldur-framework); PRO is a separate package you add on top in production. PRO adds capability — it never replaces or relicenses anything in the core.

At a glance

Capability	OSS core	PRO
Circuit breaker (incl. half-open recovery)	✅	✅
Retry with backoff	✅	✅
Idempotency	✅	✅
Health checks	✅	✅
Graceful shutdown / drain	✅	✅
Metrics (Prometheus / OpenTelemetry)	✅	✅
System control (runtime on/off)	✅	✅
Built-in web console (operate & recover)	✅	✅ (＋PRO panels)
Precomputed cache	✅	✅
Bulkhead isolation	✅	✅ (＋thread-pool)
Dead-letter queue + replay (capture, view, single-entry actions)	✅	✅
DLQ at scale (batch replay from the console, adaptive pacing, durable outbox, archive/purge)	—	✅
Audit trail (hash-chained, exportable)	—	✅
Unified notification / alerting	—	✅
Emergency mode (coordinated load shedding)	—	✅
Throttle / adaptive rate limiting	—	✅
Canary Recovery (config rollout + auto-rollback)	—	✅
Governance gates for risky automation	—	✅
Meta-Watchdog (Baldur watching itself)	—	✅

A PRO subscription includes every PRO capability — they are not sold or unlocked one at a time.

What "OSS core" means in practice

The free tier is the resilience patterns themselves, with zero infrastructure to start. A single service can survive a failing dependency, tell a load balancer the truth, drain cleanly on restart, and expose metrics — all on pip install baldur-framework alone, no license and no sign-up.

See the individual guides: Circuit Breaker, Retry, Idempotency, Health Check, Graceful Shutdown, Metrics, System Control, Precomputed Cache.

Where the boundary actually sits

The boundary is deliberately drawn so you can write production-shaped code on OSS and have the same code light up under PRO — but that means a few features expose an OSS API surface whose heavier backing ships with PRO. Knowing exactly where that line falls avoids surprises.

The clearest examples are audit and notification. On OSS, the core already emits everything worth knowing: every state change, block, and recovery surfaces as a structured event in your logs. What PRO adds is the machinery that turns those events into something a team operates on — the hash-chained, exportable audit trail that persists them as a compliance record, and unified notification that pushes an incident to a channel like Slack instead of waiting for someone to read the logs. In short: OSS observes and logs, PRO persists and pushes.

This is intentional — the events are already flowing on OSS, and the capability becomes real when you add the PRO package and a license. PRO-only settings left in an OSS install are simply inert; an OSS deployment never breaks because a PRO knob was present.

Bulkhead draws the same line inside one feature. The compartments, the registry, the @bulkhead decorator, and the metrics are all core — semaphore isolation works fully on OSS. PRO upgrades the isolation strength: a compartment that requests thread_pool isolation gets a dedicated worker pool whose execution timeout frees the caller when a task runs away (on the OSS semaphore fallback, the timeout bounds only the wait for admission — once admitted, a hung call occupies the calling thread until it returns). The same code runs on both tiers; OSS logs a startup warning naming the fallback.

A note on naming: "canary"

"Canary" names exactly one feature in Baldur — Canary Recovery (PRO) — but the word invites a common misreading of the OSS circuit breaker, so it is worth stating what each does:

Circuit-breaker half-open recovery (OSS). When an OSS circuit breaker leaves the OPEN state, it does not slam 100% of traffic back at the dependency. It admits a bounded number of concurrent probe calls (capped by BALDUR_CB_HALF_OPEN_MAX_CALLS) and reverts to OPEN at the first probe failure. This is ordinary half-open probing — it does not step traffic back through graduated percentages — and it operates on in-process traffic to one dependency. See the circuit breaker.
Canary Recovery (PRO). A separate PRO feature that rolls a configuration change out to a small slice of your fleet first, watches it, and restores the previous configuration automatically if the rollout degrades. It operates on fleet-wide configuration, not circuit-breaker traffic. See Canary Recovery.

In short: the OSS circuit breaker recovers one breaker's traffic with bounded half-open probes; PRO Canary Recovery rolls out and rolls back configuration across a fleet.

Turning PRO on

PRO is the OSS install plus the PRO package and a license, supplied through one of these:

Env Var	What it controls
`BALDUR_LICENSE_KEY`	The PRO license, provided inline as a value
`BALDUR_LICENSE_FILE`	Path to a file that holds the PRO license

Individual PRO features carry their own settings, documented in their own guides and the environment variable reference.