The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
description: >- How OpenHuman loads optional native modules at runtime: the registry, admission checks and what happens when a module faults. icon: puzzle-piece
Loadable modules
Feature gates decide what compiles into the binary. Modules decide what the running binary can reach. A module is a first-party native library, loaded into the core process, that serves a small typed interface over TinyBus.
The trade is explicit. A module shares the core's address space and crash domain, so it is trusted code and the admission checks matter. In return, a user who never generates a document never pays for the document writer in download size, memory or dependencies.
Host access and contracts
Hosts reach module clients through the openhuman-rpc facade chain. The shared
openhuman_rpc::embed::modules::client(config) returns a
tinybus::module::ModuleClient built from explicit configuration
over the process-wide lazy loader before or after core startup. Constructing
a client starts nothing and requires no signed-in session. Set bundled-artifact
discovery before its first call. A build without the modules feature has no client; with modules disabled
in configuration a call returns an explicit unavailable error.
A *-bus crate contains serialized vocabulary, errors, identifiers, versions,
schemas and static tool declarations. Parsing, provider dispatch, cryptography,
processes and device access execute inside the compiled module. Hosts retain
configuration, credentials, approvals and execution policy. They never link an
implementation fallback when a module is unavailable. Stateful adapters release
module-owned resources through explicit close, cancellation and shutdown calls.
The remaining migration work and temporary dependency exceptions are tracked in the module-boundary inventory.
The registry
crates/openhuman-core/src/modules/registry/ compiles eleven records. Only this registry may select an artifact. Nothing reads a module name from config and goes looking for it.
| Module | Provides |
|---|---|
tinycomputer |
Desktop and browser observation and control |
tinysearch |
Web-search provider dispatch |
tinydocs |
Document extraction and .docx / .pptx synthesis |
tinywallet |
Key derivation and transaction signing |
tinyjuice |
Tool-output compression and recovery |
tinyvoice |
Audio framing, VAD, and transcript hallucination detection |
tinymcp |
The MCP client and registry |
tinyconnectors |
OAuth connector actions and triggers |
tinybox |
Sandbox/resource lifecycle, bounded and supervised execution, jail and Docker operations, shell execution, file transfer and port forwarding |
tinychannels |
Messaging channel transports |
tinyflows |
Scheduled jobs: scheduler runtime, cron job store and schedule maths (tinyflows-bus schedule contract) |
tinyhosts |
Hosting provider operations |
Each record carries a version, the release it came from, and one PlatformAsset per supported build. Seven records publish eleven builds: ubuntu-24.04 and ubuntu-22.04 on x86_64 and arm64, macos-26 and macos-15 on arm64 and x86_64, windows-2025-x86_64, windows-2022-x86_64 and windows-11-arm64. TinyComputer publishes sixteen assets; TinyBox, TinyMCP and TinyWallet each publish seventeen, adding Arch Linux and Fedora builds. Asset availability is module-specific, so a release's count should not be inferred from another module's matrix.
Every asset carries a SHA-256 copied verbatim from the published release's own checksum file. Do not compute a replacement pin from a local build. The digest must describe the artifact the release workflow signed, not the one on your machine.
Resolution order
Each step avoids the cost of the next:
- Already serving on the host's broker.
- An operator override: a path in
[modules].overrides, or a source mode ([modules] source/OPENHUMAN_MODULE_SOURCE, local development only; CI usesrelease).linkedserves a module compiled into the runningopenhuman-core(build it with--features linked-modules, which linkscrates/openhuman-modules-linked; no product build or other host can reach that crate).sourceserves a library built from the module's vendored gitlink bynode scripts/modules/build.mjs <id|all>(it writestarget/module-sources/<id>/with an operator-trustmodules.toml; setOPENHUMAN_MODULE_SOURCE_DIRto that directory). Local digests are never registry pins.node scripts/modules/pin-status.mjsreports whether each gitlink is in sync with, ahead of or behind its registry pin (ahead means you are running a locally compiled module that CI will refuse), andnode scripts/modules/release-and-repin.mjs <id>publishes a release and re-pins from itschecksum.toml. The strictcheck-module-pins.mjsis unchanged. - The module search path:
OPENHUMAN_MODULE_PATH, then the platform data directories. - Bundled releases staged into the app at build time.
- The release cache, downloading only if
[modules].allow_downloadis true.
An override bypasses the digest check, because the artifact is whatever sits at that path. That is acceptable only because it is the operator's own file, named in the operator's own config. It also means an override cannot add a module that is not already in the registry.
Platform candidates are ordered newest first, with fallthrough. On Linux, glibc 2.39 or newer prefers the 24.04 build and falls back to 22.04. glibc 2.35 or newer gets 22.04. Anything older, plus musl or an unknown libc, gets an empty candidate list, so no published artifact loads there by design.
Admission
These checks run in order, all before any module code runs:
- Directory ownership and mode, and a regular platform library file within the size cap.
- The digest allowlist beside the artifact, when present, which is authoritative for its directory.
- Resolve the ABI descriptor symbol, and validate its frozen 16-byte prefix before reading the rest.
- Validate the full descriptor: matching pointer width, endianness and target triple, a compatible TinyBus series, and module feature bits that are a subset of the host's. A module built with
panic = "abort"is refused, because an aborting panic takes the host down with it. - Parse the manifest and resolve dependencies, rejecting missing providers, cycles and name clashes.
- Initialize, take the vtable, attach the transport.
Each module declares its interface in its own small *-bus contract crate: the interface name, the object path, one constant per member, and a contract version. The bind rule is that majors are equal and the module's minor is at least the host's. A newer module serves an older host, and the reverse is refused instead of half working. Never redeclare a contract type in OpenHuman, and call members through the contract's constants, not string literals.
Faults are terminal
Of the eleven lifecycle states, five are terminal: rejected, faulted, failed, stopped and disabled. A module in one of those answers "unavailable" immediately and is never retried in the same process.
This follows from a second rule: the loader never unloads a library. A stopped module releases its transport and its names, but its code, thread-locals, panic metadata and callback addresses stay mapped until the process exits. Replacing an artifact needs a restart. Retrying a faulted module in place would run code whose invariants you already know are broken.
Untrusted code does not belong here. It belongs in a separate process, which is what the sandbox backends are for.
Configuration
[modules]
enabled = true # when off, features report it instead of failing at use
allow_download = true # false suits an air-gapped or reproducible deployment
# install_dir = "..." # defaults to the user cache dir, then the workspace
Nothing is downloaded silently either way. The digest comes from the compiled-in registry, not from the release being fetched.
The modules RPC namespace exposes list, status and load (by id, never by path), plus computer_status and browser_check_readiness for the computer module's readiness. browser_forget_sites forgets what browser tasks learned about one site or every site (see Jev).
Adding or moving one
A module's behavior belongs in the submodule that owns it. The host side is the adapter: the proxy, the config it pushes at initialization and the policy around the call. When you change a module:
- Land the change upstream and cut a release there.
- Move the gitlink under
vendor/. - Update the record's version, release URL and digests from that release's checksum file.
- Test both the gate-on and gate-off builds, because a missing leaf gate should mean the module is absent, not present and failing.
See also
- Architecture: where modules sit relative to the core.
- Building the Rust core: the feature gates that decide what compiles.
- Performance and footprint: what the lazy-loading trade is worth.