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 last generated compose project (keeps volumes)
make down
# Same project-wide teardown (the auth argument is ignored; keeps volumes)
make down-auth
# Repeat project-wide teardown for legacy bundle arguments (keeps volumes)
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.
Laptop profile: the stack plus your own runtime
The local catalog bundle runs postgres, redpanda, valkey, the migrations and
your own ONEX runtime (main and effects, with omnimarket installed) in
containers, under the compose project omnibase-infra-local. It needs Docker
with Compose v2, uv, make, openssl and git, and no credentials beyond
two passwords it generates. It publishes host ports 5436, 19092, 16379, 8085
and 8086.
git clone https://github.com/OmniNode-ai/omnibase_infra.git
cd omnibase_infra
# Writes ~/.omnibase/local.env (two generated passwords) and
# ~/.omnibase/local.bifrost.yaml (the model your runtime delegates to).
make local-env
# Edit the ONE line marked model_endpoint in ~/.omnibase/local.bifrost.yaml:
# the /v1/chat/completions URL of an OpenAI-compatible server that serves the
# model id omnimarket's routing contract declares (Qwen3.8-27B today).
make up-local # builds the runtime image and boots everything
make status-local # migration gate, both runtime /health bodies, delegate consumer
make delegate-local PROMPT="Reply with exactly one word: hello"
make down-local # stop (keeps data); make down-local-volumes deletes it
A cold boot provisions the broker's topics before the main runtime reports
healthy; allow several minutes. make delegate-local prints one JSON result
and the path of the run's receipt.json inside the effects container
(docker exec omnibase-infra-local-runtime-effects cat <path>). The delegation
is projected to delegation_events in the local omnidash_analytics database.
Every service connects as the postgres superuser, so row-level security is not
exercised by this profile.
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
Metadata
1 maintainer
Release files for omnibase_infra 0.38.70
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.70.tar.gz | 21.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| omnibase_infra-0.38.70-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.3 MB
Release files / omnibase_infra-0.38.70.tar.gz
| Download URL | omnibase_infra-0.38.70.tar.gz |
|---|---|
| Size | 21.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
525b5a2fa8713ebfcba62683589afd6bae97dcfe0b1b2d190ddcf848e2361661
|
|
BLAKE2b-256 checksum How to use checksums |
e27795e1fc0a6f88e286345674cbd5f62e6bfe88e9aab05f7125b1881cc89d37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","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.70-py3-none-any.whl
| Download URL | omnibase_infra-0.38.70-py3-none-any.whl |
|---|---|
| Size | 7.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e5feb842aa31bb19dd5ea77a30d9d546aa2722c960189daf3f1eb0ade86d2f1
|
|
BLAKE2b-256 checksum How to use checksums |
32cf7686e069e742a18bed038010420e7fcb43bbdc60e57bafaab2db7db9e30c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","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}
|
