Circuit Breaker v0.2.8 — Release Notes

Target release: March 2026 Previous release: v0.2.5 Branch: hotfix/performance

Highlights

v0.2.8 is the largest feature release since v0.2.0. It delivers six major new surfaces — multi-map views, an interactive rack editor, built-in network monitoring, a redesigned IPAM center, a certificate manager, and a notifications center — alongside foundational platform work: a full business intelligence engine, tenant management, masquerade sessions, Proxmox observability, and a Uptime Kuma Socket.IO upgrade. Nine new database migrations (0059–0067) are included; all are backward-compatible with existing data.

Feature Areas in This Release

Multi-Map Support

You can now create up to 10 named topology maps and switch between them using a compact dropdown pill in the map toolbar. Each map is independently scoped — nodes, positions, and layout are per-map.

  • Create, rename, reorder, and delete named maps from the toolbar.
  • Assign any entity (hardware, service, network, cluster) to a specific map via the entity detail drawer or right-click context menu.
  • Pin entities to all maps as an escape hatch for core shared devices (firewalls, core switches, etc.).
  • New entities default to Map 1 (the default map), preserving existing behavior for existing users.
  • Inactive maps consume zero resources — no polling, no timers, no animation frames.
  • Maximum of 10 maps enforced with a clear error response.

Backend: GET/POST/PATCH/DELETE /api/v1/maps, entity assignment at POST /maps/{id}/entities, global pin at POST /maps/pin. Built on existing Topology/TopologyNode tables (schema from 0026) — no new tables needed.

Interactive Rack Editor (Phase 1)

The read-only rack diagram has been replaced with a fully interactive 3-panel editor.

  • Left panel — Hardware Inventory: Lists all unracked hardware for the current rack. Drag any device directly into an open U-slot on the canvas.
  • Center panel — Rack Canvas: Renders the full rack as a U-slot grid. Empty slots are droppable targets. Mounted devices are draggable (drag back to inventory to unrack). Changes are auto-saved on drop.
  • Right panel — Inspector: Click any mounted device to see its details. Remove it from the rack with a single button.
  • Cable Overlay: SVG cable visualization layer showing physical connections between ports on mounted devices.
  • All colors use CSS variables — zero hardcoded hex values — for full theme compatibility.
  • Hardware now supports mounting_orientation (horizontal/vertical) and side_rail fields for accurate physical representation.

Tech: @dnd-kit/core + @dnd-kit/utilities for accessible, DOM-native drag and drop.

Native Built-in Monitoring

Circuit Breaker can now monitor your hardware and services directly — no external monitoring tool required.

  • Probe types: ICMP ping, HTTP health check (up if HTTP status < 400), TCP port check.
  • Probes are configured per-monitor with a target address, optional port, and a configurable interval (default 60s).
  • Monitor results flow through the same integration sync worker as Uptime Kuma, so status badges, uptime percentages, and status-change events all work identically.
  • Auto-monitor on discovery: A new settings toggle automatically creates native probes for any hardware discovered via network scan.
  • Annotate status-change events with a reason and user attribution for operational context.

Backend: NativeProbePlugin — a full IntegrationPlugin implementation. No external dependencies; uses httpx for HTTP probes and stdlib socket for TCP.

Uptime Kuma — Socket.IO Enrichment

The Uptime Kuma integration now uses the Socket.IO API (Uptime Kuma 2.0+) for richer monitor data, with graceful fallback to the public HTTP API for earlier versions.

  • Heartbeat history: Fetches the last 2 hours of heartbeat records per monitor, enabling trend-line visualization.
  • Certificate expiry: Pulls daysRemaining from Uptime Kuma's cert info and surfaces it directly in Circuit Breaker.
  • Response times: avg_response_ms now populated from real Socket.IO data instead of estimated.
  • linked_hardware_id: Monitors can now be linked to a hardware entity for topology correlation.
  • A new background integration_sync_worker handles all integration polling with PostgreSQL advisory locking, preventing duplicate runs. It also emits IntegrationMonitorEvent rows on every status transition for audit history.

Business Intelligence & Analytics

Circuit Breaker now includes a backend analytics engine for capacity planning and operational intelligence.

  • Capacity forecasting: OLS linear regression over telemetry time series. Predicts when CPU, RAM, and storage will exceed a threshold based on the trailing trend. Results available at GET /api/v1/intel/capacity-forecasts.
  • Resource efficiency: Classifies hardware as over-provisioned, right-sized, or under-provisioned based on utilization patterns. Available at GET /api/v1/intel/resource-efficiency.
  • Blast-radius analysis: BFS traversal of the dependency graph to identify all assets impacted by a given node going down. Critical DOWN events from the status worker are now automatically enriched with blast-radius data. Available at GET /api/v1/intel/blast-radius/{entity_type}/{entity_id}.
  • Flap detection: Identifies services that repeatedly oscillate between up and down states. Flap incidents are stored with duration and flip counts.
  • Telemetry retention (hot/warm/cold): Background worker downsamples telemetry data on a configurable schedule — raw (hot) → hourly aggregates (warm) → daily aggregates (cold) — to keep storage bounded at scale.
  • All analytics jobs use PostgreSQL advisory locks for safe concurrent execution without an external scheduler.

New tables: capacity_forecasts, resource_efficiency_recommendations, flap_incidents. Retention configuration in AppSettings.

TLS Certificate Management

A new Certificates page gives you full visibility into your homelab's TLS certificates.

  • Add and track certificates by domain — supports self-signed and Let's Encrypt types.
  • Visual expiry status: Shield icons indicate health at a glance — green (valid), amber (expiring within 30 days), red (expired), grey (unknown).
  • Paste PEM directly or leave blank to auto-generate a self-signed certificate.
  • Auto-renew toggle per certificate.
  • Certificate detail drawer shows full metadata including SANs, issuer, and days remaining.

IPAM — Unified 4-Tab Layout

The IPAM page has been redesigned from a flat IP address list into a unified network management center with four tabs. The separate Networks page has been absorbed as the first tab, reducing navigation clutter and keeping everything subnet-related in one place.

Networks tab (replaces the standalone Networks page) - Full network/prefix CRUD with inline search and a new VLAN filter. - Subnet and gateway fields visible at a glance in the table; click any row to open the detail drawer.

IP Addresses tab - Filter chips — All / Manual / Discovered — let you quickly separate hand-entered addresses from IPs pulled in via network discovery scans. - Network filter dropdown to scope the list to a single prefix. - Conflict detection: adding an address already tracked returns a clear 409 response rather than silently duplicating. - Hardware and service linkage visible per row — click through directly to the linked entity.

VLANs tab - Manage VLAN IDs, names, and descriptions alongside network membership. - VLAN filter on the Networks tab cross-links back here for quick navigation.

Sites tab - Logical site definitions (data center, lab room, off-site) that group networks and hardware for documentation and discovery scoping.

Backend: No new API routes — the existing /api/v1/ipam, /api/v1/networks, /api/v1/vlans, and /api/v1/sites endpoints are unchanged. This is a pure frontend reorganization.

Notifications Management

A new Notifications page manages your alerting pipeline end-to-end.

  • Notification sinks: Configure delivery destinations for Slack, Discord, Microsoft Teams, or Email. Enable/disable per sink. Test delivery before going live.
  • Routing rules: Route alerts by severity (info / warning / critical / all) to specific sinks. Multiple routes per sink.
  • Provider icons in the UI for quick visual identification.
  • The webhook Dead Letter Queue (DLQ) from v0.2.5 is now surfaced in the UI — review and retry failed deliveries.

Tenant Management

v1.0 note: This historical v0.2.8 section is superseded by the v1.0 support contract and ADR 0003. Circuit Breaker 1.0 does not support true multi-tenancy; use separate deployments for separate trust boundaries.

In v0.2.8, Circuit Breaker shipped early multi-tenant foundations for operators managing shared homelab environments or multiple logical environments. These foundations are not a supported v1.0 security boundary.

  • At the time, operators could create, rename, and delete tenants from the Tenants admin page.
  • At the time, member management could add or remove users from tenants with per-tenant roles.
  • At the time, active tenant context was stored in localStorage and sent as X-Tenant-ID.
  • At the time, CRUD was admin-only and regular users saw only tenants they belonged to.

Historical backend behavior: CRUD existed at /api/v1/tenants, with member management at /api/v1/tenants/{id}/members. In v1.0 these legacy paths return a stable unsupported-tenancy response.

User Management Enhancements

Masquerade (Login-As)

Admins can now impersonate any user to troubleshoot permission issues or verify dashboard configurations.

  • Clicking "Masquerade" on a user row issues a short-lived (15-minute) JWT with is_masquerade: true claims.
  • A persistent amber banner appears at the top of every page: "Viewing as user@example.com — your admin session is preserved."
  • "Return to Admin" button in the banner instantly restores the original admin session.

OAuth Invite Flow

  • Invite links now carry an invite_token through the OAuth provider redirect, enabling seamless new-user onboarding via SSO without requiring a separate registration step.
  • accepted_at timestamp recorded on invite rows for audit purposes.

Proxmox Reliability & Observability

Proxmox is Circuit Breaker's primary data pipeline for the topology map, but sync failures were previously invisible. This release adds per-config health state.

  • Two new columns on integration_configs: last_sync_error and last_poll_error.
  • Every scheduled sync will write its outcome — ok, partial (some entities failed), or error (unreachable) — to the DB. Partial failures include the specific per-entity error strings.
  • Telemetry poll failures (node poll, VM poll, RRD poll) are tracked per-config and independently surfaced.
  • The Proxmox tab in the integrations UI will show: last-sync time, a colored status badge (green/amber/red), and an expandable error block when failures occur.
  • The perpetual "Not synced" badge goes away once the first sync completes.

Note: Migration 0063 is included. The service wiring (9 implementation steps) will land in a follow-on commit on this branch.

Security Hardening

  • Legacy auth token deprecated: The pre-v0.2 static token auth path has been removed. All authentication flows through JWT.
  • Password reset token enumeration (SEC-001): Reset tokens are now SHA256-hashed before being used as Redis keys. An attacker with Redis SCAN access can no longer enumerate live reset tokens directly. The token value returned to users is unchanged.
  • CORS wildcard filter (SEC-002): The CORS origin guard now filters wildcards per-element rather than exact-matching ["*"]. Mixed lists like ["*", "https://legit.com"] no longer pass a wildcard through alongside allow_credentials=True.
  • CSP 'unsafe-inline' removed (SEC-003): 'unsafe-inline' has been removed from script-src. 'strict-dynamic' already supersedes it in modern browsers; the keyword only created a legacy-browser XSS bypass.
  • HSTS preload directive (SEC-004): Strict-Transport-Security header now includes ; preload, enabling domain submission to browser HSTS preload lists.
  • Default client hash salt warning (SEC-005): client_hash_password() now calls get_client_salt() to respect the full env → DB → default priority chain. If neither CB_CLIENT_SALT nor a DB-stored salt overrides the public default, a WARNING is emitted at startup.
  • OIDC nonce validation (SEC-006): The OIDC authorization flow now generates and stores a nonce alongside the PKCE verifier. The callback verifies the nonce claim in the returned id_token, preventing captured ID tokens from being replayed into an active authorization flow. Migration 0067 adds a nullable nonce column to oauth_states.
  • Docker install automation: Docker installation is now optional and detected automatically on upgrade, eliminating silent skips when --docker was passed in upgrade mode.

Installer Improvements

  • Debian 13 (Trixie) compatibility: The native installer now supports Debian 13 with fallback UID assignment when preferred UIDs are taken. Errors during install surface loudly. Post-install directory ownership verified with a check loop.
  • DB address fallback: Native installer is more resilient when detecting the PostgreSQL address across different distro conventions.
  • NATS version pinning: Build pipeline now pins NATS server version to avoid unexpected upgrades breaking the embedded message bus.
  • Distro-agnostic preflight: The version whitelist in stage0_preflight has been removed. The installer now detects the distro family (Debian/Ubuntu, Fedora, RHEL/Rocky/AlmaLinux, Arch) rather than requiring a specific version. If the required packages are available, the install proceeds — no artificial gate.
  • Dynamic PGDG repo URLs: The PostgreSQL repo URL for Fedora and RHEL-family distros is now fully dynamic — arch and major version are derived at runtime rather than hardcoded. Correct on aarch64, fresh Fedora releases, and RHEL 10 when it ships.
  • Idempotent re-runs: Running the installer a second time on an existing system is now safe. PostgreSQL, pgbouncer, Redis, and NATS configuration stages detect already-initialized, running services and skip re-initialization. No service disruption on accidental re-run.
  • Inline debug hints for novice users: When any major stage fails, the installer now prints 3-5 numbered next steps directly in the terminal — the exact log path, service status command, port check, and retry invocation. No need to hunt for documentation.
  • SHA256 checksum is now a hard failure: A checksum mismatch aborts the install instead of silently continuing. Use --skip-checksum only for air-gapped deployments or local bundle installs.

Proxmox LXC Helper (cb-proxmox-deploy.sh)

  • Operation timeouts: Template download, container creation, and the in-container install/upgrade are now wrapped with timeout — 5 min, 2 min, and 10 min respectively. Previously these could hang indefinitely on network or storage issues.
  • Stale lock pre-clear: pct unlock runs proactively before both pct create and pct start to clear locks leftover from failed previous attempts.
  • IPv4 CIDR validation: The static IP input dialog now validates x.x.x.x/prefix format and re-prompts with a clear error message until a valid address is entered.
  • Richer failure output: When the in-container install fails, the output now includes a 5-step debug block: enter the container, tail the full install log, check service status, view all CB logs, and re-run the installer command.

Bug Fixes

  • Proxmox first-scan node stacking: On a fresh Proxmox discovery, all nodes spawned at position (0, 0) because the radial force-simulation layout was used for Proxmox graphs — with no edges yet, forces couldn't spread nodes apart. The map now always defaults to dagre on first load, which positions nodes correctly regardless of edge count.
  • TelemetryPanel form pre-population (BUG-009): Opening the Telemetry panel on a hardware node with an existing config no longer shows blank fields. The backend now returns a password-redacted config object in TelemetryResponse, and the panel pre-fills profile, host, username, SNMP community, poll interval, and enabled state from it.
  • Multi-U rack diagram spans (BUG-011): Devices taller than 1U now fill every slot they occupy in the rack diagram. Continuation rows display a │ marker instead of repeating the device name.
  • IPAM network scan CIDR limit (BUG-005): The /scan/{network_id} endpoint now correctly caps at 1022 hosts (the actual maximum for a /22) rather than 1024, and the error message reflects the correct limit.
  • Poll Now button state (BUG-008): The Poll Now button in TelemetryPanel is now disabled while a save operation is in progress, preventing a race condition where a poll could read stale config immediately after a save.
  • Silent async telemetry publish failure (BUG-006): When the telemetry dispatcher runs in a sync context with no event loop, the Redis cache/publish step is now logged at DEBUG level instead of failing silently.

Database Migrations

Eight new migrations apply automatically on upgrade (or via make migrate):

Migration Summary
0059 Uptime Kuma monitor enrichment — response time, cert expiry, hardware link, last heartbeat
0060 Hardware mounting orientation and side-rail fields
0061 OAuth invite token threading + invite accepted_at timestamp
0062 Native monitoring probe config, event annotations, auto-monitor-on-discovery setting
0063 Proxmox sync and poll health columns on integration_configs
0064 Integrations base_url made nullable
0065 Multi-map — activates Topology/TopologyNode for named-map support
0066 IPAM notes field + network site association
0067 OIDC nonce column on oauth_states for token replay protection

All migrations use ADD COLUMN IF NOT EXISTS / additive-only patterns. No data loss, no column drops.

Upgrade Notes

  • Mono Docker image: migrations run in /docker/entrypoint-mono.sh before supervisord; the image sets CB_AUTO_MIGRATE=false so multiple Uvicorn workers do not each invoke Alembic. Bare uvicorn / dev installs still default CB_AUTO_MIGRATE=true unless you set it to false.
  • Legacy databases (PostgreSQL with users but no alembic_version row): the app stamps Alembic to a3b4c5d6e7fc (0015) once, then upgrades to head. Set CB_DISABLE_LEGACY_ALEMBIC_STAMP=true if you must block that behavior and stamp manually instead.
  • TimescaleDB: optional at runtime; set CB_REQUIRE_TIMESCALE=true to fail startup when the extension is not installed on the server. GET /api/v1/health and admin Database status include timescaledb_available.
  • No manual steps required for standard upgrades. CB_AUTO_MIGRATE=true (default outside the mono image) applies pending migrations on API startup when enabled.
  • If running the native installer, run cb upgrade or re-run the install script. Re-running is now safe — initialized services are detected and skipped.
  • The legacy static auth token path has been removed. Ensure all API clients and scripts use JWT-based authentication.
  • Uptime Kuma Socket.IO enrichment requires Uptime Kuma 2.0.0-beta.2 or later. Earlier versions fall back to the public HTTP API automatically — no action needed.
  • Air-gapped or local-bundle installs should use --skip-checksum to bypass the new hard SHA256 check.
  • Open Settings → Notifications and configure at least one notification sink.
  • Open Settings → Certificates and register any TLS certificates you're managing manually.
  • If you use Uptime Kuma, verify your integration is running 2.0.0-beta.2+ to get heartbeat history and cert expiry data.
  • Create a second map (e.g., "DMZ" or "Lab Network") to try multi-map scoping.
  • Visit the IPAM page — your existing networks, VLANs, and IP addresses are now in the tabbed layout. Use the "Discovered" filter chip to review any IPs pulled in via scan.
  • For Proxmox users: trigger a manual discovery run and confirm the Proxmox tab now shows a green "Connected" badge.