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

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) 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), 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) 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) 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) 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), 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) 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:

use openhuman::util::sanitize_for_llm;

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

Initializing the runtime bootstrap:

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:

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:

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 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), [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), [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), and [src/openhuman/tui/mod.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tui/mod.rs).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}