omnibase_infra 0.20.1

ONEX Infrastructure - Service integration and database infrastructure tools

ONEX Infrastructure

Production infrastructure services for the ONEX execution layer. Handlers, adapters, and runtime services for PostgreSQL, Kafka, Consul, Vault, and Redis.

What is This?

This repository provides the infrastructure layer for ONEX-based systems. While omnibase_core defines the execution protocol and node archetypes, this package provides:

• Handlers for external services (database, HTTP, messaging)
• Adapters wrapping infrastructure clients
• Event bus abstractions for Kafka/Redpanda
• Runtime services deployable via Docker

Built on omnibase-core ^0.8.0 and omnibase-spi ^0.5.0.

Install Model

omnibase_infra serves two distinct purposes depending on how you use it:

As a library / runtime (pip install)

pip install omnibase-infra
# or
uv add omnibase-infra

This gives you the Python library and bundled runtime CLIs (onex-runtime, omni-infra, onex-status, etc.). No clone required for library use or running the runtime.

For operational bootstrapping (clone required)

The operational scripts in scripts/ are not bundled in the pip package. A local clone is required to run them:

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

Scripts that require a clone:

• scripts/seed-infisical.py — Populate Infisical from contract YAMLs
• scripts/bootstrap-infisical.sh — Full first-time Infisical bootstrap
• scripts/provision-infisical.py — Create machine identities

See CLAUDE.md — Install Model for the full decision matrix.

Quick Start

# Clone the repository
git clone https://github.com/OmniNode-ai/omnibase_infra.git
cd omnibase_infra

# Start infrastructure services with Docker
cd docker
cp .env.example .env
# Edit .env - set POSTGRES_PASSWORD (required for Docker fallback)
# Set OMNIBASE_INFRA_DB_URL (required for CLI/scripts; recommended for Docker)

docker compose -f docker-compose.infra.yml up -d

# Verify services are running
docker compose -f docker-compose.infra.yml ps

Docker Services

Self-contained infrastructure via docker-compose.infra.yml:

Service	Profile	Port	Description
PostgreSQL	default	5436	Persistence (always starts)
Redpanda	default	29092	Event bus (always starts)
Valkey	default	16379	Caching (always starts)
Consul	consul	28500	Service discovery (optional)
Infisical	secrets	8880	Secrets management (optional)
Runtime	runtime	8085	ONEX runtime services (optional)

Profiles:

# Infrastructure only (default)
docker compose -f docker-compose.infra.yml up -d

# With service discovery
docker compose -f docker-compose.infra.yml --profile consul up -d

# With secrets management
docker compose -f docker-compose.infra.yml --profile secrets up -d

# Everything
docker compose -f docker-compose.infra.yml --profile full up -d

Configure via .env file - see docker/README.md for details.

Documentation

I want to...	Go to...
Get started quickly	Quick Start Guide
Understand the architecture	Architecture Overview
Deploy with Docker	Docker Guide
See a complete example	Registration Walkthrough
Write a contract	Contract Reference
Find implementation patterns	Pattern Documentation
Read coding standards	CLAUDE.md

Full documentation: docs/index.md

Repository Structure

src/omnibase_infra/
├── handlers/          # Request/message handlers
├── event_bus/         # Kafka/Redpanda abstractions
├── clients/           # Service clients
├── models/            # Pydantic models
├── nodes/             # ONEX nodes (Effect, Compute, Reducer, Orchestrator)
├── errors/            # Error hierarchy
├── mixins/            # Reusable behaviors
└── enums/             # Centralized enums

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Type checking
uv run mypy src/omnibase_infra/

# Format code
uv run ruff format .
uv run ruff check --fix .

Pre-commit Hooks Setup

Run once after cloning:

uv run pre-commit install
uv run pre-commit install --hook-type pre-push

Contributing

See CONTRIBUTING.md for commit conventions and PR guidelines.

License

MIT License - see LICENSE for details.