vibey-bootstrap

The cross-cutting layer for Azure Functions, FastAPI services, and AKS workers. One call bootstraps logging → App Configuration + Key Vault → Application Insights and hands you a populated os.environ. Everything past that (alerts, tracing, Service Bus, ten log transports, a scaffold CLI) is opt-in via pip extras. Used across 17+ Azure Functions repos at Vizius.

Formerly azure-bootstrap — see NOTICE.md.

Why

Every Azure app hits the same startup deadlock: you need logging to report config loading, but App Insights logging needs config to initialize. Most repos solve it with a copy-pasted src/infrastructure/ folder that drifts. This library is that folder, done once, tested, and versioned.

The four-phase bootstrap breaks the cycle:

1. Console logging — works immediately, before anything loads.
2. Telemetry from env — App Insights if APPLICATIONINSIGHTS_CONNECTION_STRING is already set.
3. Configuration — Azure App Configuration + Key Vault references → os.environ. Local values (local.settings.json, your shell) always win; nothing is overwritten.
4. Telemetry upgrade — if the connection string only arrived via config, upgrade now.

Guarantees: the v1 API surface is preserved byte-identical across v2, v3, and v4 (v4 changes only the distribution and import name — see MIGRATING-TO-V4.md); every extra is opt-in and most are stdlib-only; log transports never block, never raise, and use a bounded buffer. USE_MOCK_BOOTSTRAP=true runs everything without Azure.

Quick start

pip install vibey-bootstrap

import os
from vibey_bootstrap import initialize_application, get_bootstrap_logger

logger = get_bootstrap_logger(__name__)   # usable before bootstrap completes
config_repo = initialize_application()     # runs all four phases

db_host = os.getenv("DATABASE_HOST")       # App Config + Key Vault values are in os.environ

Requires Python 3.11+. Falls back to plain environment variables when App Configuration is not configured, so the same code runs locally and in Azure.

Worked example: production-grade logging in four lines

from vibey_bootstrap.alerts import install_global_exception_hooks, register_dispatcher
from vibey_bootstrap.bootstrap import ensure_bootstrap
from vibey_bootstrap.logging import configure_logging


def my_email_sender(recipients, subject, html_body):
    ...  # any callable with this signature (Graph, SendGrid, ACS)


configure_logging()
install_global_exception_hooks()
ensure_bootstrap()
register_dispatcher(my_email_sender, recipients=["dev-alerts@example.com"])

After this, every line emitted through stdlib logging carries a correlation ID, extra fields render as greppable key=repr(value) pairs, noisy third-party loggers are silenced, and uncaught exceptions fire CRITICAL alerts with dedup, rate-limiting, and escalation. Runnable version: examples/01_quickstart.py.

What's in the box

# Common combinations
pip install 'vibey-bootstrap[alerts,fastapi,health]'
pip install 'vibey-bootstrap[servicebus,sb-lock,retry,heartbeat]'
pip install 'vibey-bootstrap[all]'

The full extras matrix (40+ extras, what each pulls in, when you need it) is in the Usage Guide.

Examples

examples/ holds 46 numbered single-concept files plus 3 end-to-end app templates. Every file runs with USE_MOCK_BOOTSTRAP=true and ends with an # ── Expected output ── block. Start with:

Reading order and per-example extras: examples/README.md.

Docs & links

• Documentation site — usage guide, migration guides, generated API reference for all 45 public packages
• Usage Guide — installation & extras matrix, every subpackage, three end-to-end recipes, TypeScript/Next.js integration
• API Reference — rendered from docstrings and signatures on every push
• CHANGELOG · v1 → v2 · v2 → v3 (additive) · v3 → v4 (rename only; pin vibey-bootstrap>=4,<5)
• PyPI · Issues · Security policy

Related projects

Part of the same open-source family — MIT, on PyPI:

• claudeloop · codexloop · cursorloop · agyloop — autonomous coding-session runners with the same contract, different vendor
• vibey — six-phase queue conductor over the loop runners
• vibey-skills — Claude Code plugin marketplace: 18 plugins / 71 Agent Skills (includes a plugin for this library)
• engineering-influence-skills — Claude Code plugin marketplace for the content pipeline
• homebrew-tap — brew tap adammatthewsteinberger/tap
• clippy-pet — the fun one

Contributing

git clone https://github.com/adammatthewsteinberger/vibey-bootstrap
cd vibey-bootstrap
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test,all]"
pytest -m "not integration"          # unit suite with coverage

Branch from develop, Conventional Commits, PRs need green CI (unit + integration

• docs build). Coverage floor is 85% (90% for new code). Details in CONTRIBUTING.md; AI-assistant context lives in CLAUDE.md.

License & attribution

MIT — see LICENSE. Originally developed as TheViziusGroup/azure-bootstrap while at The Vizius Group; republished here as adammatthewsteinberger/vibey-bootstrap with The Vizius Group's permission — see NOTICE.md.

Built by Adam Matthew Steinberger · more open source