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.
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file omnibase_infra-0.38.11.tar.gz.
File metadata
- Download URL: omnibase_infra-0.38.11.tar.gz
- Upload date:
- Size: 12.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
79861097a8b5911a00cfca8ccb8625c71f1255b2238c0af800acc3dbaab9513d
|
|
| MD5 |
4261b8931bab1d6d5309d2cd59b3bb71
|
|
| BLAKE2b-256 |
41910c2657164ac78a3297c219d9eecf22dc8c2a32d3330b1b4294cfa0163d8c
|
File details
Details for the file omnibase_infra-0.38.11-py3-none-any.whl.
File metadata
- Download URL: omnibase_infra-0.38.11-py3-none-any.whl
- Upload date:
- Size: 6.1 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
447795bc47528e1104a40ed34d1c35c1fb08176a493c632984a42122e1f91527
|
|
| MD5 |
f8bdd30b248f72405905f716fb8cb461
|
|
| BLAKE2b-256 |
95ded15b07ebc5de624061330d40eb378fd4fc9b9a7a6b1348bdf710e1c29f86
|
