# Always-Compiled Kernel Modules in OpenHuman: The Essential Core Architecture

> Explore OpenHuman's always-compiled kernel modules: util runtime voice mcp tui and platform. Discover the dependency-free foundation that powers every build.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: architecture
- Published: 2026-08-31

---

**OpenHuman's Rust core contains six kernel families—`util`, `runtime`, `voice`, `mcp`, `tui`, and `platform`—that are compiled into every build regardless of feature gates, forming the dependency-free foundation required for the application to start and pass tests.**

The OpenHuman project (`tinyhumansai/openhuman`) organizes its Rust codebase into kernel families that control compilation scope through Cargo feature flags. While most functional domains are optional and can be excluded to create slim builds according to the source code, a carefully curated set of **always-compiled kernel modules in OpenHuman** provides the invariant infrastructure that every build—from full product releases to CI-lite test runs—requires to function.

## What Defines an Always-Compiled Kernel Module?

These modules constitute the **kernel floor**: the minimal code layer that remains present when all optional features are disabled. According to the source analysis, these families share three defining characteristics:

- **Never gated**: They contain no `#[cfg(feature = "...")]` attributes at the module declaration level.
- **Dependency-free or lightweight**: They avoid heavy external dependencies, ensuring fast compilation and minimal binary overhead.
- **Infrastructure-critical**: They provide types and functions that other (potentially gated) modules depend upon for basic operation.

## The Six Always-Compiled Kernel Families

The following kernel families are declared as "always compiled, never gated" in the OpenHuman source tree.

### 1. util — Dependency-Free Utilities

The `util` family at [[`src/openhuman/util/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/util/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/util/mod.rs) contains self-contained helper functions used throughout the core. These include path sanitisation routines and text utilities that have no external dependencies. Because every other module—including those in the kernel floor—relies on these primitives, `util` is unconditionally compiled.

### 2. runtime — Core Runtime Façade

Located in [[`src/openhuman/runtime/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/mod.rs), the `runtime` family provides the **ShellTool** façade and bootstrap types required by the core regardless of which concrete runtimes (Node, Python, etc.) are enabled. While specific runtime implementations live behind feature gates, the façade itself and the Node bootstrap logic in [[`src/openhuman/runtime/node/bootstrap.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/node/bootstrap.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/node/bootstrap.rs) remain always-compiled to ensure consistent API availability.

### 3. voice — Public API Façade

The `voice` module at [[`src/openhuman/voice/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/voice/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/voice/mod.rs) acts as a permanent entry point that re-exports a consistent public API. The concrete speech-to-text (STT) and text-to-speech (TTS) implementations are gated behind the `voice` feature, but the façade provides stubs for server management, dictation listeners, and streaming interfaces that allow dependent code to compile without conditional compilation attributes.

### 4. mcp — HTTP Client Infrastructure

The `mcp` root at [[`src/openhuman/mcp/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/mod.rs) is always-compiled because `mcp::http_client` is required by other always-on domains. While the actual MCP services—`server`, `registry`, and `audit`—reside behind feature gates beneath the root, the HTTP client implementation serves as shared infrastructure for core components that must function even when the full MCP stack is disabled.

### 5. tui — CLI Entry Stub

Declared in [[`src/openhuman/tui/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tui/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tui/mod.rs), the `tui` root provides the single always-present symbol `run_from_cli`. This function serves as the CLI entry point stub; when the `tui` feature is disabled, it returns a clear "feature disabled" error rather than causing a compilation failure. The actual UI implementation components (`app`, `render`, `state`, `terminal`, `runner`) are gated behind the `tui` feature flag.

### 6. platform — Core Process Behavior

The `platform` family in [[`src/openhuman/platform/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/mod.rs) implements fundamental process-level behavior including `about_app`, `connectivity`, `cost`, `doctor`, `health`, `proc_metrics`, `service`, `socket`, `startup`, and `update`. These modules form the operational backbone of the application and are never gated because they provide essential service orchestration and health monitoring that all builds require.

## Practical Usage Examples

When developing against OpenHuman, you can rely on these modules without feature-gate annotations. The following examples demonstrate accessing the always-compiled kernel floor.

Accessing utility helpers:

```rust
use openhuman::util::sanitize_for_llm;

let safe = sanitize_for_llm("User input with <dangerous> chars");
println!("Sanitized: {}", safe);

```

Initializing the runtime bootstrap:

```rust
use openhuman::runtime::node::bootstrap::NodeBootstrap;
use std::sync::Arc;

fn init_node() -> Option<Arc<NodeBootstrap>> {
    // The bootstrap type exists even when the `runtime-node` feature is off.
    // The actual binary will be `None` in that case.
    openhuman::runtime::node::bootstrap::init()
}

```

Using the MCP HTTP client:

```rust
use openhuman::mcp::http_client::McpHttpClient;

let client = McpHttpClient::new();
let resp = client.get("/status").await?;
println!("MCP status: {}", resp.status());

```

Calling the TUI CLI stub:

```rust
use openhuman::tui::run_from_cli;

fn main() {
    // In a build without the `tui` feature this will emit a clear "feature disabled" error.
    if let Err(e) = run_from_cli() {
        eprintln!("TUI unavailable: {}", e);
    }
}

```

## Why the Kernel Floor Matters

This architecture provides three critical guarantees for the OpenHuman codebase:

1. **Testability**: CI-lite builds can compile and run integration tests against the kernel floor without pulling in heavy optional dependencies like Web3 clients or full TUI frameworks.
2. **API Stability**: The façade pattern ensures that public APIs remain consistent; callers never need `#[cfg]` attributes to handle missing modules because the stubs always exist.
3. **Build Flexibility**: Developers can create minimal "headless" binaries that exclude the `tui`, `voice`, or `mcp` services while retaining the core `platform` functionality required for process management.

## Summary

- **Six kernel families** (`util`, `runtime`, `voice`, `mcp`, `tui`, `platform`) are always-compiled kernel modules in OpenHuman.
- These modules reside in specific [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs) files under `src/openhuman/` and form the **kernel floor**.
- They provide dependency-free infrastructure required for the core to start, compile tests, and support feature-gated domains.
- Always-compiled modules use the **façade pattern**, exposing stable APIs while concrete implementations remain optional.
- All other domains (`documents`, `web3`, `channels`, `flows`, etc.) are optional and can be removed via feature gates without breaking the build.

## Frequently Asked Questions

### How do always-compiled modules differ from feature-gated modules in OpenHuman?

Always-compiled modules are declared without `#[cfg(feature = "...")]` attributes and are present in every build configuration. Feature-gated modules, such as specific runtime implementations or full TUI rendering, are conditionally compiled based on Cargo feature flags and may be absent in slim or specialized builds.

### Can I disable the always-compiled kernel modules to reduce binary size?

No. These modules are intentionally non-optional because they provide essential infrastructure that the OpenHuman core requires to function. They are designed to be lightweight and dependency-free to minimize their impact on binary size even in minimal builds.

### What happens if code tries to use a gated feature through an always-compiled façade?

The always-compiled façade provides type stubs and function signatures that match the gated implementation. If the feature is disabled, calling these functions typically returns `None` or an `Err` indicating the feature is unavailable, rather than causing a compilation error. For example, `run_from_cli()` in the `tui` module returns a clear error message when the `tui` feature is disabled.

### Where can I find the definitive list of always-compiled modules in the source code?

The kernel floor is defined by module declarations in the crate root that lack feature-gate attributes. Key files include [[`src/openhuman/util/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/util/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/util/mod.rs), [[`src/openhuman/runtime/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/runtime/mod.rs), [[`src/openhuman/platform/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/platform/mod.rs), [[`src/openhuman/voice/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/voice/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/voice/mod.rs), [[`src/openhuman/mcp/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/mod.rs), and [[`src/openhuman/tui/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tui/mod.rs)](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tui/mod.rs).