# How OpenHuman's Domain Feature Gate System Manages Compile-Time Gates

> Discover how OpenHuman's domain feature gate system leverages Cargo flags for compile-time gate management, automatically syncing with a runtime DomainSet for efficient filtering.

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

---

**OpenHuman isolates major functional families behind domain abstractions controlled by Cargo feature flags at compile time, automatically reflecting those gates in a runtime DomainSet that filters controllers, stores, and tools.**

The `tinyhumansai/openhuman` repository implements a rigorous compile-time gate system that maps each functional domain to a dedicated Cargo feature. This architecture ensures that when a domain is disabled, the compiler completely omits the associated code and dependencies, producing lean binaries while maintaining runtime consistency through a mirrored permission system.

## Compile-Time Feature Flags in Cargo.toml

The root **[`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)** organizes features into two distinct groups to separate development needs from production requirements.

*   **Contributor features** – The default set enabled for development and CI, providing minimal functionality.
*   **Product features** – The exhaustive set defined in [`scripts/ci/product-features.txt`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/ci/product-features.txt) required for the shipped desktop application.

Each major functional family corresponds to a specific Cargo feature. For example, `web3`, `voice`, `media`, and `modules` each control their respective domains. When you disable a feature using `--no-default-features` or by omitting it from your build configuration, the Rust compiler excludes all code behind that gate and drops exclusive dependencies. Disabling the `web3` feature, for instance, removes the `bitcoin`, `ethers-core`, and `curve25519-dalek` crates entirely from the build.

## The DomainGroup Enum as the Canonical Registry

All domains are enumerated as variants in the **`DomainGroup`** enum located in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs) at lines 91–184.

- `Agent`, `Memory`, `Web3`, `Voice`, `Media`, `Modules`, and `Platform` are among the defined variants.
- The enum provides an **`ALL`** constant containing the complete list of domains.
- An **`index()`** implementation at lines 150–164 maps each variant to a numeric slot used by runtime bitsets for efficient permission checks.

This enum serves as the single source of truth for what constitutes a domain within the system, ensuring that both compile-time flags and runtime checks reference identical functional boundaries.

## Runtime DomainSet Mirrors Compile-Time Gates

During core construction, **[`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs)** instantiates a **`DomainSet`** that bridges compile-time features to runtime behavior. The builder provides preset configurations for common use cases:

```rust
let domains = DomainSet::full();    // Enables all domains for product builds
let domains = DomainSet::harness(); // Core-only: agent + memory + threads

```

Internally, **`DomainSet::allows(g)`** checks whether the Cargo feature corresponding to the given `DomainGroup` variant is active. Every controller registration, store initialization, and tool advertisement invokes `domains.allows(g)` to determine inclusion. This guarantees that the runtime state cannot diverge from the compiled capabilities.

## How Tools and Controllers Are Filtered

The tool registry in **[`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs)** (lines 1210–1447) demonstrates runtime gating in practice. When the system classifies a tool to its respective `DomainGroup`, it queries the `DomainSet` before registration. If `domains.allows(DomainGroup::Web3)` returns false, the tool is silently dropped, preventing accidental exposure of uncompiled functionality.

Controllers and stores follow identical patterns, using the same permission checks during the initialization phase to ensure that only enabled domain logic is mounted.

## Practical Build Configurations

You control compile-time gates through Cargo commands without modifying source code.

Enable the `voice` domain explicitly:

```bash
cargo build --features voice

```

Create a minimal build excluding heavy dependencies like Web3:

```bash
cargo build --no-default-features --features "agent memory threads"

```

Check active domains programmatically at runtime:

```rust
use openhuman_core::core::all::DomainGroup;

fn list_active_domains(domains: &DomainSet) {
    for g in DomainGroup::ALL {
        if domains.allows(*g) {
            println!("Domain enabled: {:?}", g);
        }
    }
}

```

## Why Compile-Time Gates Matter

**Binary size** – Disabling domains removes their exclusive crates, keeping the product lean. Removing `web3` eliminates cryptographic libraries that can add megabytes to the binary.

**Security** – Domains depending on native libraries (e.g., `voice` → `cpal` audio drivers) can be excluded from builds targeting restricted or sandboxed environments, reducing the attack surface.

**Modularity** – New domains require only three steps: extend the `DomainGroup` enum in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs), wire a corresponding feature flag in [`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml), and guard the runtime registration behind `domains.allows(DomainGroup::NewDomain)`.

## Summary

- The **`DomainGroup`** enum in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs) (lines 91–184) provides the canonical list of all functional domains.
- Root **[`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)** defines feature flags that map one-to-one with `DomainGroup` variants, splitting contributor and product configurations.
- **`DomainSet`** in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) constructs runtime permission sets from compile-time features, offering presets like `full()` and `harness()`.
- The tool registry in **[`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs)** (lines 1210–1447) filters tools by domain before registration.
- This architecture enables **binary size optimization**, **security hardening** through dependency exclusion, and **modular extensibility**.

## Frequently Asked Questions

### What is the difference between DomainGroup and DomainSet?

**`DomainGroup`** is a static enum defined in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs) that enumerates all possible functional domains as variants (e.g., `Web3`, `Voice`). **`DomainSet`** is a runtime structure instantiated in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) that tracks which of those domains are actually enabled based on the compile-time Cargo features, providing the `allows()` method for permission checks.

### How do I disable the web3 domain to reduce binary size?

Pass `--no-default-features` to Cargo and specify only the domains you need, excluding `web3`. For example: `cargo build --no-default-features --features "agent memory threads"`. This removes the `bitcoin`, `ethers-core`, and `curve25519-dalek` dependencies entirely from the compilation.

### Where does the runtime check if a domain is enabled?

The runtime checks occur in **`DomainSet::allows()`**, which is called during core initialization in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) and during tool registration in [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs) (lines 1210–1447). This method verifies the Cargo feature status for the requested `DomainGroup` variant.

### Can I add a custom domain to the feature gate system?

Yes. First, add a new variant to the **`DomainGroup`** enum in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs). Second, add a corresponding feature flag to the root **[`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)**. Third, guard any controllers, stores, or tools belonging to this domain with `domains.allows(DomainGroup::YourNewDomain)` checks during registration.