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/ |
| Contract-driven handler discovery | src/omnibase_infra/runtime/handler_plugin_loader.py |
| Registration orchestration and storage effects | src/omnibase_infra/nodes/node_registration_* |
| Infrastructure handlers for DB, HTTP, Consul, secrets, Kafka, LLM, graph, vector, and filesystem integrations | src/omnibase_infra/handlers/ |
| Config discovery and prefetch | src/omnibase_infra/runtime/config_discovery/ |
| Operational scripts and CLIs | scripts/ |
Prose for every row above lives in the knowledge base — see Documentation.
Documentation
This repository holds code, not prose. Every architecture note, pattern,
decision record, guide, reference page, and runbook that used to live under
docs/ now lives in one of the two knowledge bases. There are no pointer stubs
in the tree — this section is the pointer, and the kb-doc-gate check
(.kb-doc-gate.yaml, mode: strict) keeps it that way.
| Home | What is there |
|---|---|
OmniNode-ai/knowledge-base (public) |
Platform documentation anyone can read: architecture/, reference/, guides/, runbooks/, and the ADR ledger. This repository's pages are prefixed omnibase-infra-. |
| Need | Where |
|---|---|
| Run locally / first-time bootstrap | runbooks/omnibase-infra-quickstart.md; the full bootstrap sequence is not part of this repository |
| Understand the handler architecture | reference/omnibase-infra-handler-protocol-driven-architecture.md (internal) |
| Work on contracts | reference/omnibase-infra-contract-yaml-reference.md (public) |
| Node archetypes and registration | reference/omnibase-infra-node-archetypes.md (internal), reference/omnibase-infra-node-registration-orchestrator.md (public) |
| Operate Kafka / DLQ / the event bus | runbooks/omnibase-infra-event-bus-operations.md, runbooks/omnibase-infra-dlq-replay.md (public) |
| Validate changes | reference/omnibase-infra-validation-framework.md (internal) |
| Decision records for this repo | reference/omnibase-infra-adr-*.md (public) |
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.
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. The full first-time bootstrap sequence is not part of this repository.
Development and testing
# Run unit tests
uv run pytest tests/unit
# Run the infra validation suite
uv run python scripts/validate.py all --verbose
# 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 the secrets manager. The runbooks for bringing those up are not part of this repository.
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
Documentation does not live in this repository. The allowed markdown set is
this README.md, CLAUDE.md, CHANGELOG.md, SECURITY.md, anything under
.claude/ or .github/, and test fixtures a test actually opens as data. The
kb-doc-gate required check enforces that list in strict mode, so a new
document under docs/ fails CI rather than quietly re-growing the tree.
New prose goes to the public knowledge base by default. Prose that would name real internal topology, the lab or CI fleet, deploy lanes, or the secrets manager does not go to a public destination at all. Dated point-in-time artifacts — evidence bundles, audit snapshots, run transcripts — are not documentation and are not migrated; definition-of-done evidence is tracked in the change-control evidence system.
License
1 maintainer
Release files for omnibase_infra 0.38.31
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| omnibase_infra-0.38.31.tar.gz | 17.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| omnibase_infra-0.38.31-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 24.1 MB
Release files / omnibase_infra-0.38.31.tar.gz
| Download URL | omnibase_infra-0.38.31.tar.gz |
|---|---|
| Size | 17.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c7e6f8b7660c430f47df2f5f2e2853dd16ddb6dcdc0d6777821306bebd718c62
|
|
BLAKE2b-256 checksum How to use checksums |
b89f11c2c357638cfd83752e9d900de056c567ff2905799ada38cbc6b69da64a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / omnibase_infra-0.38.31-py3-none-any.whl
| Download URL | omnibase_infra-0.38.31-py3-none-any.whl |
|---|---|
| Size | 6.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69e9556a2fbf50af2fdfcce2dffaa955859117ddf73375d8169540afaf9baa21
|
|
BLAKE2b-256 checksum How to use checksums |
7a0f6882953accb057620f6375f9a10a235d30cb370020cfeaf522dd69f0f7fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
