omnibase_infra 0.36.0

ONEX Infrastructure - Service integration and database infrastructure tools

omnibase_infra

Production infrastructure runtime for ONEX (OmniNode eXecution).

omnibase_infra owns the infrastructure implementation layer for ONEX: runtime hosting, Kafka event transport, contract-driven handler loading, registration workflows, Infisical-backed configuration, operational runbooks, and infrastructure nodes that perform external I/O.

It depends on omnibase_core for shared models and validation primitives, and on omnibase_spi for protocol boundaries. Core must not import this package.

What This Repo Owns

Area	Current source
Runtime host process and service kernel	src/omnibase_infra/runtime/
Kafka event bus and DLQ support	src/omnibase_infra/event_bus/, event bus guide
Contract-driven handler discovery	src/omnibase_infra/runtime/handler_plugin_loader.py, handler architecture
Registration orchestration and storage effects	src/omnibase_infra/nodes/node_registration_*, registration workflow
Infrastructure handlers for DB, HTTP, Consul, Infisical, Kafka, LLM, graph, vector, and filesystem integrations	src/omnibase_infra/handlers/, handler guide
Infisical config discovery and prefetch	src/omnibase_infra/runtime/config_discovery/, config discovery
Operational scripts and CLIs	scripts/, operations index

Start Here

Need	Document
Understand the repo boundary	Documentation index
Run locally	Quick start
Understand the architecture	Architecture overview
Work on nodes	Current node architecture
Work on contracts	Contract reference
Operate Kafka/DLQ/runtime services	Operations index
Validate changes	Validation framework

Install

Library or CLI use:

uv add omnibase-infra

Repository development:

git clone https://github.com/OmniNode-ai/omnibase_infra.git
cd omnibase_infra
uv sync

The packaged distribution includes the Python package and console scripts. The repo-local scripts/ directory is for development, operational bootstrap, and CI support, and requires a clone.

Common Commands

Local infrastructure lifecycle

The repo ships a top-level Makefile with user-facing infra entrypoints (OMN-10377). All Docker/Compose/Keycloak orchestration lives here, never in the public omnibase shell.

# Start core infra bundle (postgres, redpanda, valkey, infisical)
make up

# Add Keycloak (auth bundle) on top of core
make up-auth

# Reconcile Keycloak clients from desired-clients.json
make seed-keycloak

# Seed Infisical from ONEX contracts (writes with --execute)
make seed-infisical

# Show running containers
make status

# Stop the core bundle ONLY (auth/runtime stay running)
make down

# Stop the auth bundle (keycloak)
make down-auth

# Stop everything (runtime + auth + core, in safe teardown order)
make down-all

# List all targets
make help

make targets detect a missing/stopped Docker daemon and emit an actionable error before doing anything destructive. They also detect a missing ~/.omnibase/.env and point at remediation rather than failing with a stack trace. See docs/getting-started/full-platform.md for the full first-time bootstrap sequence.

Development and testing

# Run unit tests
uv run pytest tests/unit

# Run the infra validation suite
uv run python scripts/validate.py all --verbose

# Run markdown link validation
uv run python scripts/validation/validate_markdown_links.py

# Start the runtime CLI entrypoint
uv run onex-runtime

# Inspect operational status
uv run onex-status

Some operational flows require Docker, Kafka/Redpanda, PostgreSQL, Valkey, and Infisical. See full platform setup and Infisical secrets guide.

Runtime Shape

ONEX infra uses four node archetypes:

Archetype	Role
ORCHESTRATOR	Coordinates workflows and publishes events
REDUCER	Owns pure FSM state transitions and emits intents
COMPUTE	Performs deterministic transformations with no side effects
EFFECT	Performs external I/O through infrastructure handlers

Node behavior is declared in contract.yaml. Node classes are intentionally thin; runtime behavior comes from contracts, handlers, registries, and the runtime host.

Documentation Policy

Current runtime, architecture, operations, and reference guidance belongs in this repository. Historical plans, one-off verification reports, and design investigations are not primary docs and are preserved outside this public docs tree when they still need retention.

Definition-of-done evidence for documentation refresh work is tracked in the change-control evidence system, not in this repository.

License

MIT